2 Introduction to the ADF Sample Application

This chapter describes the StoreFront module of the Fusion Order Demo (FOD) application created to demonstrate the use of the Fusion web application technology stack to create transaction-based web applications as required for a web shopping storefront. The demonstration application is used as an example throughout this guide to illustrate points and provide code samples.

Before examining the individual components and their source code in depth, you may find it helpful to install and become familiar with the functionality of the Fusion Order Demo application.

2.1 Introduction to the Oracle Fusion Order Demo

In this sample application, electronic devices are sold through a storefront-type web application. Customers can visit the web site, register, and place orders for the products. In order to register customers and fulfill orders, currently only a single application is in place. In a future release, several applications, will cooperate. For a detailed description of how the application works at runtime, see Section 2.5, "Taking a Look at the Fusion Order Demo Application."

2.2.1 How to Download the Application Resources

The Fusion Order Demo application requires an existing Oracle database. You run the Fusion Order Demo application using Oracle JDeveloper 11g.

Do the following before installing the Fusion Order Demo application:

Install Oracle JDeveloper. You need Oracle JDeveloper 11g Studio Edition to view the application's projects and run the application using the JDeveloper integrated server. You can download Oracle JDeveloper from:

Install an Oracle database. The Fusion Order Demo application requires a database for its data.

The SQL scripts were written for an Oracle database, so you will need some version of an Oracle RDBMS, such as 11g, or XE. The scripts will not install into Oracle Lite. If you wish to use Oracle Lite or some other database, then you will need to modify the database scripts accordingly. You can download an Oracle database from:

The root directory where you have Oracle JDeveloper 11g installed. For example:

C:/JDeveloper/11/jdeveloper

jdbc.urlBase

The base JDBC URL for your database in the format jdbc:oracle:thin:@<yourhostname>. For example:

jdbc:oracle:thin:@localhost

jdbc.port

The port for your database. For example:

1521

jdbc.sid

The SID of your database. For example:

ORCL or XE

db.adminUser

The administrative user for your database. For example:

system

db.demoUser.tablespace

The table space name where FOD users will be installed. For example:

USERS

From the JDeveloper main menu, choose File > Save All.

In the Application Navigator, under the Resources node, right-click build.xml and choose Run Ant Target > buildAll.

In the Enter Property dialog, enter the password for the database system user and click Continue.

Once you enter the password, the Ant build script creates the FOD users and populates the tables in the FOD schema. In the Apache Ant - Log window, you will see a series of SQL scripts and finally:

buildAll:

BUILD SUCCESSFULTotal time: nn minutes nn seconds

For more information on the demo schema and scripts, see the README.txt file in the MasterBuildScript project.

2.2.3 Overview of the Fusion Order Demo Schema

Figure 2-1 shows a simplified representation of the schema for the Fusion Order Demo application. The blue shapes in the diagram represent the four core tables. The other tables and views are shown as yellow shapes that sometimes represent several tables to help simplify the diagram. Some of the tables use sequences, but only those used by the core tables are shown.

Figure 2-1 Schema Diagram for the Fusion Order Demo Application

The core tables represented by the blue diagram elements include:

PERSONS: This table stores all the users who interact with the system, including customers, staff, and suppliers. The first and last name, email address, and person type code of each user is stored. A user is uniquely identified by an ID. Other IDs provide foreign keys to tables with address information and, in the case of customer's, membership information.

ORDERS: This table represents activity by specific customers. When an order is created, the date of the order, the total amount of the order, the ID of the customer who created it, and the status of the order are all recorded. After the order is fulfilled, the order status and order shipped date are updated. All orders are uniquely identified by a sequence-assigned ID.

ORDER_ITEMS: For each order, there may be many order items recorded. The unit price and quantity of each order item are recorded. The order line item and its order ID uniquely identify each order item.

PRODUCTS_BASE: This table stores all of the products available in the store. For each product, the name and cost are recorded. All products are uniquely identified by a sequence-assigned ID. The image of the product and its description are stored in separate tables, which each reference the product ID. The columns ATTRIBUTEx are reserved for future use with descriptive flexfields (commonly required by Oracle E-Business Suite schema).

The sequences that the core tables use include:

PERSON_SEQ: Populates the ID for for each new person.

ORDER_SEQ: Populates the ID for each new order.

ORDERS_ITEMS_SEQ: Populates the ID for each new order item.

PRODUCTS_SEQ: Populates the ID for each product.

The PL/SQL package USER_CONTEXT_PKG contains a procedure set_app_user_lang() used to illustrate a simple example of how to set per-user database state from inside an application module.

Note the SHIPPING_OPTIONS view is reserved for future use and is not currently used in the Fusion Order Demo.

To support tracking of change history in the Fusion Order Demo, every table contains the history column CREATED_BY, CREATION_DATE, LAST_UPDATED_BY, LAST_UPDATED_DATE, and OBJECT_VERSION_ID, as shown in Figure 2-2.

Figure 2-2 History Columns for Tables in FOD Schema

2.2.3.1 Translation Support in the Fusion Order Demo Schema

To support localization of the Fusion Order Demo, the AVAILABLE_LANGUAGES table lists all available languages. In this table, only one row will have the DEFAULT_FLAG set to Y corresponding to the current user's language.

Taking the Shipping Options group, as shown in Figure 2-3: SHIPPING_OPTION_TRANSLATIONS is fully populated so that each product has one row for each language. The column LANGUAGE holds the translation language identifier. The entry itself may not yet be translated, in which case the SOURCE_LANGUAGE column holds the language that the entry is currently in. When a value has been translated, SOURCE_LANGUAGE and LANGUAGE will hold the same value. The PL/SQL package USER_CONTEXT_PKG creates the custom USERENV('CLIENT_INFO') variable that specifies the runtime locale used to pull the correct translations from SHIPPING_OPTION_TRANSLATIONS into the SHIPPING_OPTIONS view along with the SHIPPING_OPTIONS_BASE table data. Each order has one set of Shipping Options associated with it.

Figure 2-3 Shipping Options Grouping for the Fusion Order Demo Schema

2.2.3.2 Lookup Tables in the Fusion Order Demo Schema

The code lookup table LOOKUP_CODES table contains codes that are used throughout the Fusion Order Demo application. For example, the PERSONS table contains the columns person_type_code, marital_status_code, and gender. These codes have corresponding rows in the LOOKUP_CODES table, discriminating on the lookup_type column. Foreign keys are not defined for these rows, but instead are enforced in the user interface by populating user interface components with LOOKUP_CODES values for a particular lookup type. For example, when creating a new registration (also known as a person) in the user interface, the values that can be used for the person_type_code are populated in a dropdown list from the lookup_code values with lookup_type=person_type_code.

Using addresses as an example, as shown in Figure 2-4: PERSONS uses an intersection ADDRESS_USAGES to accommodate multiple address information. In addition ADDRESS_USAGES uses LOOKUP_CODES to store both OWNER_TYPE_CODE and USAGE_TYPE_CODE information, returning the MEANING (see table extract in Figure 2-5). ADDRESSES directly accesses COUNTRY_CODES to look up and use the COUNTRY_NAME associated with the COUNTRY_ID stored in ADDRESSES. The PERSONS table also directly stores PRIMARY_ADDRESS_ID by a direct lookup to ADDRESSES.

Figure 2-4 LOOKUP_CODES Usage in the Fusion Order Demo Schema

The correct translation is applied by using the LANGUAGE columns in both LOOKUP_CODES and COUNTRY_CODES with the runtime locale/preference.

Figure 2-5 LOOKUP_CODES Sample Data in the Fusion Order Demo Schema

The lookup table DEMO_OPTIONS defines the various options within the Fusion Order Demo application that are switched on. It also caches general configuration information such as email addresses and phone numbers to use as overrides in this demonstration scenario (for example, where email addresses are fictitious). This table is reserved for future use.

2.3 Running the Fusion Order Demo Application StoreFront Module

The Fusion Order Demo application consists of a web user interface and a business components layer. Specifically, the following projects are part of the Fusion Order Demo application:

StoreFrontService: Provides access to the storefront data and provides transaction support to update data for customer information and orders.

StoreFrontUI: Provides web pages that the customer uses to browse the storefront, place orders, register on the site, view order information, and update the user profile.

You run the StoreFront module of the Fusion Order Demo application in JDeveloper by running the home.jspx page in the StoreFrontUI project. The StoreFrontUI project uses JavaServer Faces (JSF) as the view technology, and relies on the ADF Model layer to interact with ADF Business Components in the StoreFrontService project. To learn more about the Fusion Order Demo application and to understand its implementation details, see Section 2.5, "Taking a Look at the Fusion Order Demo Application."

A second module of the Fusion Order Demo application is available to process the orders that you place using the StoreFront module. For example, the WebLogic Fusion Order Demo module uses various internal and external applications, including a customer service application, a credit validation system, and both an internal vendor and external vendor. These composite services are the subject of another developer's guide and are not addressed in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework. For details about the WebLogic Fusion Order Demo module used to demonstrate the capabilities of Oracle SOA Suite, see the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

You cannot run the WebLogic Fusion Order Demo module in JDeveloper. When you want to integrate the storefront portion with the composite services portion of the application, you must deploy the Fusion Order Demo application to a SOA-enabled Oracle WebLogic Server. Instructions to deploy any SOA web application to Oracle WebLogic Server, are addressed in the Fusion Order Demo home page on OTN at this link http://www.oracle.com/technetwork/developer-tools/jdev/index-095536.html.

The easiest way to run the Fusion Order Demo application is to open only the StoreFront module in JDeveloper and run the home.jspx page in the StoreFrontUI project.

To run the StoreFront module of the Fusion Order Demo application:

Open the application in Oracle JDeveloper:

From the JDeveloper main menu, choose File > Open.

Navigate to the location where you extracted the demo ZIP file to and select the StoreFrontModule.jws application workspace from the StoreFrontModule directory. Click Open.

Table 2-2 Connection Properties Required to Run the Fusion Order Demo Application

Property

Description

Host Name

The host name for your database. For example:

localhost

JDBC Port

The port for your database. For example:

1521

SID

The SID of your database. For example:

ORCL or XE

Do not modify the user name and password fod/fusion. These must remain unchanged. Click OK.

In the Application Navigator, right-click StoreFrontService and choose Rebuild.

In the Application Navigator, right-click StoreFrontUI and choose Run.

The Configure Default Domain dialog displays the first time you run the application and start a new domain in Integrated WebLogic Server. Use the dialog to define an administrator password for the new domain. Passwords you enter can be eight characters or more and must have a numeric character.

The home.jspx page within the StoreFrontUI project is the default run target. When you run the default target, JDeveloper will launch the browser and display the Fusion Order Demo application home page.

Once the home page appears, you can browse the web site as an anonymous user, or you can choose to log in and place orders (may require registering as a customer first). Because the Fusion Order Demo application implements ADF Security to manage access to Oracle Application Development Framework (Oracle ADF) resources, only the authenticated user will be able to view orders in their cart. Table 2-3 shows the users who are authorized as members of the fod-users role to log into the Fusion Order Demo application.

Note:

The Fusion Order Demo application ships with predefined user data. The schema for the application defines different types of users including customer, supplier, and staff types. All users are members of the fod-users role and are authorized to log in. However, only ngreenbe is the user type CUST (customer). When you log in as any other user, you will need to register as a customer before you can place an order. These additional users were created to support roles in other modules of the Fusion Order Demo application.

Table 2-3 Supplied Users in the Fusion Order Demo Application

Username

Password

Application Role

Notes

ngreenbe

welcome1

fod-users

Can add items to cart, check out, and view order information. This is the only user who is preregistered as a customer in the StoreFront module of Fusion Order Demo.

sking

welcome1

fod-users, fod-admin

Can add items to cart, but must register as a customer to check out and view order information. This user also has administration privileges (fod-admin) in the MasterPriceList module of Fusion Order Demo.

ahunold

welcome1

fod-users, fod-manager

Can add items to cart, but must register as a customer to check out and view order information. This user also has read-only privileges (fod-manager) in the MasterPriceList module of Fusion Order Demo.

pbrown / fdaviet

welcome1

fod-users

Can add items to cart, but must register as a customer to check out and view order information. These users may be added to to other roles in a future version of Fusion Order Demo.

2.4 Running the Fusion Order Demo Standalone Applications

The Fusion Order Demo application includes a set of sample applications that allow you to investigate Oracle ADF functionality that does not appear in the StoreFront module. Collectively, these sample applications are referred to as standalone applications. The standalone sample applications appear in five application workspaces, each consisting of several projects, located in the StandaloneExamples directory where you extracted the demo ZIP file.

In general, almost all of the standalone applications demonstrate concepts of ADF Business Components and data model projects. References to these standalone applications appear throughout the chapters contained in Part II, "Building Your Business Services" and Part VI, "Advanced Topics" of this developer's guide. As you read sections this guide, you may want to run the corresponding standalone application to investigate the concepts further. For a brief description of each application workspace and links to the documentation, refer to the tables in Section 2.4.2 through Section 2.4.5.

2.4.1 How to Run the Standalone Applications

How you use JDeveloper to run a standalone application depends on the individual application. Some applications are set up to use the interactive testing tool JDeveloper provides for the ADF Business Components data model project (this tool is known as the Business Component Browser). Other applications provide Java test clients (with file names like TestClientXxx.java) that use the ADF Business Components API to execute queries and display results. In the case of the Business Component Browser, you work entirely in the tool, which essentially provides a convenient user interface for interacting with business components. In the case of the Java clients, the program files output their results and print statements to the JDeveloper Log window.

Familiarize yourself with the following general procedures about how to run the standalone applications. The first procedure describes how to run an application with its provided test client. The second describes how to launch the Business Component Browser on the data model project's ADF application module. Then read Section 2.4.2 through Section 2.4.5 for more details about the individual standalone applications.

Some of the standalone applications work with a modified version of the FOD schema. For standalone applications that require schema changes, the application's project will contain a SQL script that you must run within JDeveloper.

Once you are through investigating a standalone application, you can use the script to back out the schema changes.

To run a standalone application from its provided test client:

Open the application in Oracle JDeveloper:

From the JDeveloper main menu, choose File > Open.

Navigate to the location where you extracted the demo ZIP file to, open the StandaloneExamples directory, then open the desired standalone application directory and select the application workspace (.jws) from the folder. Click Open.

In the Application Navigator, expand the project folder and locate the test client (.java) file. In some cases, the test client is added to a package located in the Application Sources folder. In other cases, the Resources folder contains the test client.

For the names and location of the test clients provided with the standalone applications, see the tables in Section 2.4.2 through Section 2.4.5.

The Configure Default Domain dialog displays the first time you run the application and start a new domain in Integrated WebLogic Server. Use the dialog to define an administrator password for the new domain. Passwords you enter can be eight characters or more and must have a numeric character.

Examine the JDeveloper Log window for the test client's output.

Refer to the referenced documentation for details about the expected results.

When the standalone application does not provide a test client to programmatically exercise the ADF Business Components API, you will use the interactive testing tool, known as the Business Components Browser.

To run a standalone application in the Business Component Browser:

Open the application in Oracle JDeveloper:

From the JDeveloper main menu, choose File > Open.

Navigate to the location where you extracted the demo ZIP file to, open the StandaloneExamples directory, then open the desired standalone application directory and select the application workspace (.jws) from the folder. Click Open.

In the Application Navigator, expand the project folder and locate the application module in a package in the Application Sources folder.

For example, Figure 2-8 shows the expanded ConditionalDelete project with the application module AppModule selected and a tooltip for the node displayed.

The Configure Default Domain dialog displays the first time you run the application and start a new domain in Integrated WebLogic Server. Use the dialog to define an administrator password for the new domain. Passwords you enter can be eight characters or more and must have a numeric character.

Use the Business Component Browser to interact with the view instances of the standalone application.

Two of the standalone applications in the application workspace DevGuideExamples use programmatic test clients to demonstrate concepts related to the ADF Business Components framework. The third application demonstrates framework functionality when you run the application in the Business Component Browser.

Figure 2-9 shows the Application Navigator after you open the DevGuideExamples application workspace.

Note that the test clients for the DevGuideExamples standalone applications provide a good starting point for understanding how to exercise methods of the ADF Business Components API. They also make good samples for test clients that you may want to create to test business component queries in a data model project. For background on working with test clients, see Section 6.4, "Testing View Object Instances Programmatically."

Launch the Business Component Browser on AppModule in the Application Sources folder.

Overrides a method in the generated entity class that conditionally prevents deletion of entity rows. In the Business Component Browser, click Delete the Current Row and observe the exception statement. Then, click Insert a New Row and delete the new row.

2.5 Taking a Look at the Fusion Order Demo Application

Once you have opened the projects in Oracle JDeveloper, you can then begin to review the artifacts within each project. The development environment for the Fusion Order Demo application is divided into two projects: the StoreFrontService project and the StoreFrontUI project.

The StoreFrontService project contains the classes that allow the product data to be displayed in the web application. Figure 2-13 shows the StoreFrontService project and its associated directories.

Figure 2-13 The StoreFrontService Project

The StoreFrontService project contains the following directories:

Application Sources: Contains the files used to access the product data. Included are the metadata files used by Oracle Application Development Framework (Oracle ADF) to bind the data to the view.

META-INF: Contains a file used in deployment.

The StoreFrontUI project contains the files for the web interface, including the backing beans, deployment files, and JSPX files. Figure 2-14 shows the StoreFrontUI project and its associated directories.

Figure 2-14 The StoreFrontUI Project

The StoreFrontUI project contains the following directories:

Application Sources: Contains the code used by the web client, including the managed and backing beans, property files used for internationalization, and the metadata used by Oracle ADF to display bound data.

When you enter the storefront site, the site is available for anonymous browsing. You can use this page to browse the catalog of products without logging into an account. The initial view shows the featured products that the site wishes to promote and gives you access to the full catalog of items. Products are presented as images along with the name of the product. Page regions divide the product catalog area from other features that the site offers.

Following are the sections of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework that describe how to create a databound web page:

Providing the structure for the web page

The home page separates features of the site into regions that are implemented using a combination of ADF Faces templates and JavaServer Faces (JSF) page fragments. ADF Faces templates and the fragments allow you to add ADF databound components. For information about the steps you perform before adding databound user interface components to a web page, see Section 20.1, "Introduction to Developing a Web Application with ADF Faces."

Displaying information on a web page

To support data binding, the featured items on the tabbed region of the home page use EL (Expression Language) expressions to reference ADF data control usages in the declarative ADF page definition file. The page definition file, which JDeveloper creates for you when you work with the Data Controls panel to drag and drop databound ADF Faces components, is unique to each web page or page fragment. The ADF data control usages enable queries to the database and ultimately work with the JSF runtime to render the databound ADF Faces components, such as the ADF Faces image component used to display images from the PRODUCT_IMAGES table. For information about creating a databound web page that references the ADF page definition file, see Section 22.1, "Introduction to Creating a Basic Databound Page."

Managing entry points to the application

The home page is supported by an ADF unbounded task flow. In general, the Fusion web application relies on this ADF Controller feature to define entry points to the application. The unbounded task flow for the entire home page and its page fragments describes view activities for displaying the home page, displaying the orders page, displaying the register user page, and it defines a task flow reference to manage the checkout process. JDeveloper helps you to create the task flow with visual design elements that you drag and drop from the Component Palette. When you create an unbounded task flow, the elements allow you to identify how to pass control from one activity in the application to the next. Because a view activity must be associated with a web page or page fragment, JDeveloper allows you also to create the files for the web page or fragment directly from the task flow diagram. The process of creating a task flow adds declarative definitions to an ADF task flow configuration file. The resulting diagram lets you work with a visual control flow map of the pages and referenced task flows for your application. For more information about specifying the entry points to the application using an ADF unbounded task flows, see Section 14.1, "Introduction to ADF Task Flows."

2.5.1.1 Viewing Product Details

To view detailed product information, you can click the product name link for any product in the home page. The product information is laid out with collapsing nodes organized by categories.

You can also select the Statistics subtab on the home page to view a graphical representation of the number of orders that customers have placed for the featured items. To present the information so that quantities are easily compared, the graph sorts the products by the number of items ordered, in descending order.

Figure 2-17 shows the bar graph used to display the featured products' current order details.

Figure 2-17 Home Page - Statistics for Featured Items

Where to Find Implementation Details

Following are the sections of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework that describe how to develop the components used to support browsing product details:

Triggering an action to display data

To display data from the data model, user interface components in the web page are bound to ADF Model layer binding objects using JSF Expression Language (EL) expressions. For example, when the user clicks on a link to display an informational dialog, the JSF runtime evaluates the EL expression for the dialog's UI component and pulls the value from the ADF Model layer. At design time, when you work with the Data Controls panel to drag an attribute for an item of a data collection into you web page, and then choose an ADF Faces component to display the value, JDeveloper creates all the necessary JSF tag and binding code needed to display and update the associated data. For more information about the Data Controls panel and the declarative binding experience, see Section 12.1, "Introduction to ADF Data Binding."

Displaying data in graphical format

JDeveloper allows you to create databound components declaratively for your JSF pages, meaning you can design most aspects of your pages without needing to look at the code. By dragging and dropping items from the Data Controls panel, JDeveloper declaratively binds ADF Faces UI components and ADF Data Visualization graph components to attributes on a data control using an ADF binding. For more information, see Section 26.1, "Introduction to Creating ADF Data Visualization Components."

2.5.1.2 Browsing the Product Catalog

To begin browsing, click the Start Shopping tab in the home page. This action changes the region of the page used to display details about featured products to a region that displays a product categories tree. You can collapse and expand the branch nodes of the tree to view the various product categories that make up the product catalog. The tree displays the product categories in alphabetical order, by category names. When you want to view all the products in a particular category, click its category node in the tree (for example, click Electronics, Media, or Office). The site refreshes the product information region to display the list of products organized as they appear in the database with an image and an accompanying description.

Figure 2-18 shows the home page with all the products in the Electronics category displayed.

Figure 2-18 Home Page - Product Categories View

Where to Find Implementation Details

Following are the sections of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework that describe how to use tables and forms to display master-detail related objects:

Dragging and dropping master and detail components

You can create pages that display master-detail data using the Data Controls panel. The Data Controls panel displays master-detail related objects in a hierarchy that mirrors the one you defined in the ADF application module data model, where the detail objects are children of the master objects. All you have to do is drop the collections on the page and choose the type of component you want to use. For example, in the Fusion Order Demo application, the page home.jspx displays the master list of product categories in an af:tree component and displays the detail list of products in an af:table component. For more information about the data model, see Section 3.4, "Overview of the UI-Aware Data Model." For more information about various types of pages that display master-detail related data, see Section 24.1, "Introduction to Displaying Master-Detail Data."

Sorting data that displays in tables

When you create an ADF Faces table component you bind the table to the complete collection or to a range of data objects from the collection. The specific components that display the data in the columns are then bound to the attributes of the collection. The iterator binding handles displaying the correct data for each object, while the table component handles displaying each object in a row. You can set the Sort property for any column when you want the iterator to perform an order-by query to determine the order. You can also specify an ORDER BY clause for the query that the view object in the data model project defines. For more information about binding table components to a collection, see Section 23.1, "Introduction to Adding Tables." For more information about creating queries that sort data in the data model, see Section 5.2, "Populating View Object Rows from a Single Database Table."

2.5.1.3 Searching for Products

To search the product catalog, you have several choices. You can begin either by clicking the disclosure icon (a + symbol) on the Search tab on the panel accordion or by clicking the Search for Deals tab in the main region. When you click either of these, the home page displays both regions at once to allow you to enter a search criteria and view the search results. You use the Search tab on the accordion panel to perform a simple keyword search against the attributes common to all products, such as product names or product descriptions. When you select the attribute to search on from the dropdown list, the panel renders a search field using an appropriate input component to accept the search criteria. For example, in the case of the default searchable attribute ProductId, where a numeric value is expected, the search field uses a spinbox (the ADF Faces component inputNumberSpinBox) to return the product ID.

Figure 2-19 shows the home page with the search results returned for the product with an ID equal to 7.

Figure 2-19 Home Page - Search View

As an alternative to entering a simple search, you can use the advanced search feature to define and save search criteria based on any combination of searchable fields that you select for the product. Click the Advanced link to open the Advanced Search dialog. Developer-defined saved searches like Find Products By Name appear in the Saved Search dropdown list.

Figure 2-20 shows the Advanced Search dialog with a single search criteria, Name, that the Find Products By Name saved search defines.

Figure 2-20 Home Page - Advanced Search Dialog

In addition to the developer-defined saved searches available in the Advanced Search dialog, the end user can create saved searches that will persist for the duration of their session. Enter the product search criteria in the Advanced Search dialog, then click the Save button to open the Create Saved Search dialog.

Figure 2-21 shows the Create Saved Search dialog that you use to specify how you want to save the search criteria you entered in the Advanced Search dialog. You can name the search, for example, Treo product name search, so that it will display in the Saved Search dropdown list of the Advanced Search dialog.

You can also manage your saved searches by selecting the Personalize function in the Saved Search dropdown list of the Advanced Search dialog.

Figure 2-22 shows the Personalize Saved Search dialog for the Find Products By Name search, with Show in Search List enabled so that it will appear in the Saved Search dropdown list. Note that because this search is not a user-defined saved search, the personalization options appear disabled.

Following are the sections of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework that describe how to define queries and create query search forms:

Defining the query for the search form to display

A query is associated with an ADF Business Components view object that you create for the data model project to define a particular query against the database. In particular, a query component is the visual representation of the view criteria defined on that view object. If there are multiple view criteria defined, each of the view criteria can be selected from the Saved Search dropdown list. These saved searches are created at design time by the developer. For example, in the Fusion Order Demo application, the ProductsVO view object defines two view criteria. When the query associated with that view object is run, both view criteria are available for selection. For more information, see Section 27.1, "Introduction to Creating Search Forms."

Creating a quick search form

A quick query search form has one search criteria field with a dropdown list of the available searchable attributes from the associated data collection. By default, the searchable attributes are all the attributes in the associated view object. You can exclude attributes by setting the attribute's Display control hint to Hide in the view object. The user can search against the selected attribute or search against all the displayed attributes. The search criteria field type will automatically match the type of its corresponding attribute type. For more information, see Section 27.1.2, "Quick Query Search Forms."

Creating a search form

You create a query search form by dropping a named view criteria item from the Data Controls panel onto a page. You have a choice of dropping only a search panel, dropping a search panel with a results table, or dropping a search panel with a tree table. For more information, see Section 27.2, "Creating Query Search Forms."

Displaying the results of a query search

Normally, you would drop a query search panel with the results table or tree table. JDeveloper will automatically wire up the results table or tree table with the query panel. If you drop a query panel by itself and want a separate results component, you can set the query component's resultComponentId attribute to the relative expression of the results component. For example, in the Fusion Order Demo application, the page home.jspx displays an af:table with the ID searchT and the results ID of the advanced search dialog is assigned this ID. For more information, see Section 27.2.2, "How to Create a Query Search Form and Add a Results Component Later."

2.5.2 The Login Process

Until you attempt to access secure resources in the storefront site, you are free to browse the product catalog and update the shopping cart as an anonymous user. However, when you click the My Orders or Checkout links that appear at the top of the home page, you will be challenged by the web container running the site to supply login credentials. The site requires that you enter a valid user name and password before it completes your request to display the linked page.

Note:

The Fusion Order Demo application supports the new customer registration process, but that user is not added to the security implementation. Thus, you must use a predefined customer's user name and password to log in, as shown in Table 2-3.

Figure 2-23 shows the login page fragment that displays before you can view order details or purchase items from the store. For demonstration purposes, log in as a customer by entering ngreenbe and welcome1 for the Username and Password, respectively.

Figure 2-23 Login Region

When you click the Log In button, the web container will compare your entries with the credential information stored in its identity store. If the web container is able to authenticate you (because you have entered the user name and password for a registered user), then the web container redirects to the web page specified by your link selection; otherwise, the site prompts you to create an account or to continue browsing as an unauthenticated user.

Where to Find Implementation Details

Following are the sections of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework that describe how to secure Oracle ADF resources so that users are required to log in to access those resources:

Enabling fine-grained security to secure Oracle ADF resources

ADF Security is a framework that provides a security implementation that is based on Java Authentication and Authorization Service (JAAS). The Oracle ADF implementation of JAAS is role-based. In JDeveloper, you define these roles and then make permission grants based on these roles to enable fine-grained security for Oracle ADF resources. JDeveloper supports declaratively defining the policy store for an ADF bounded task flow or individual web pages associated with their ADF page definition. For information about securing Oracle ADF resources, see Section 30.5, "Defining ADF Security Policies."

Triggering dynamic user authentication

When you use ADF Security, authentication is triggered automatically if the user is not yet authenticated and tries to access a page that is not granted to the anonymous-role role. After successfully logging in, another check will be done to verify if the authenticated user has view access to the requested page. For more information, see Section 30.3.5, "What You May Need to Know About ADF Authentication."

Performing permission checking within the web page

At runtime, the security policy you define for ADF resources is enforced using standard JAAS permission authorization to determine the user's access rights. If your application requires it, you can use Expression Language (EL) to perform runtime permission checks within the web page to hide components that should not be visible to the user. For example, in the Fusion Order Demo application, the page myOrders.jpx uses an expression with the value userGrantedPermission to test the user's authorization privileges before displaying their account number. For more information, see Section 30.11.1, "Using Expression Language (EL) with ADF Security."

2.5.3 The Ordering Process

You begin the order process by browsing the product catalog. When you click Add next to a product, the site updates the shopping cart region to display the item.

Figure 2-24 shows the cart summary with a single item added. The summary shows a subtotal for the items that appear in the cart.

Figure 2-24 Home Page - Shopping Cart Summary

When you are satisfied with the items in the cart, you can complete the order by clicking the Checkout link at the top of the home page. To check out and complete the order, you must become an authenticated user, as described in Section 2.5.2, "The Login Process."

After you log in, the site displays the checkout page with order details, such as the name and address of the user you registered as. The order is identified by an Order Information number that is generated at runtime and assigned to the order. An Order Summary region displays the order items that comprise the new order. This region is similar to the cart summary on the home page, except that it adds the cost of shipping and deducts any discounts that apply to the order to calculate the total purchase amount.

Figure 2-25 shows the checkout page with an order comprising four order items.

Figure 2-25 Checkout Page - Order Details Form

You can use the checkout page to customize details of the order information. For example, click the Edit icon next to the Payment Option Code field to display and edit payment funding information for the order.

Following are the sections of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework that describe how to develop forms like the ones used in the order checkout process:

Creating a databound edit form

When you want to create a basic form that collects values from the user, instead of having to drop individual attributes, JDeveloper allows you to drop all attributes for an object at once as an input form. You can create forms that display values, forms that allow users to edit values, and forms that collect values. For example, in the Fusion Order Demo application, the checkout page orderSummary.jspx displays one form to display user information and another form to collect shipping information for the user's order. For more information, see Section 22.6, "Creating an Input Form."

Defining format masks for input forms

Format masks help ensure the user supplies attribute values in the required format. To facilitate this task, ADF Business Components provides declarative support known as control hints for attributes in the data model project. For example, in the Fusion Order Demo application, the attribute for the CustomerPaymentOptionVO view object used to assign the user's credit card expiration date is configured with a format mask hint and enforced in the Payment Options page fragment paymentOptionsDetails.jsff. For information on defining format masks for input form components, see Section 5.13, "Defining Control Hints for View Objects."

Defining a list of values for selection lists

Input forms displayed in the user interface can utilize databound ADF Faces selection components to display a list of values (LOV) for individual attributes of the data collection. To facilitate this common design task, ADF Business Components provides declarative support to specify the LOV usage for attributes in the data model project. For example, in the Fusion Order Demo application, the three af:selectOneChoice components displayed in the Payment Options page fragment paymentOptionsDetails.jsff are bound to LOV-enabled attributes configured for the CustomerPaymentOptionVO view object. For more information about configuring attributes for LOV usage, see Section 5.12, "Working with List of Values (LOV) in View Object Attributes."

Keeping track of transient session information

When you create a data model project that maps attributes to columns in an underlying table, your ADF view objects can include transient attributes that display calculated values (for example, using Java or Groovy expressions) or that are value holders. For example, in the Fusion Order Demo application, the order summary page orderSummary.jspx displays the value of the InvoiceTotal attribute calculated by the expression defined on the OrderVO view object. For more information about defining transient attributes in the data model project, see Section 4.14, "Adding Transient and Calculated Attributes to an Entity Object."

2.5.4 The Customer Registration Process

The site requires that you become an authenticated user before you can display the checkout page. To make it possible for new customers complete the order process, the site needs to provide a way to guide users through customer registration. To begin, click the registration link on the home page and then click Register as a customer.

Customer registration progresses in steps, with one screen dedicated to each step. To represent the progression of these steps, the registration page displays a series of train stops labelled Basic Information, Address, Payment Options, and Review. To navigate the customer registration process, you can click certain train stops or you can click the Next button.

Figure 2-29 shows the first screen in the customer registration process. The Basic Information stop of the train is enabled and selected to identify it as the current stop. Notice that the next train stop icon, Address, is enabled but not highlighted, while the Payment options and Review train stop icons appear disabled and grayed out. Together, these train stops signify that you must complete the activity in a sequential flow.

Figure 2-29 Customer Registration Page - Basic Information Form

Before you enter any information into the Basic Information form, click the Address train stop. The page displays an error dialog to inform you that specific fields require a value before you can progress to the next step.

Figure 2-30 shows the error dialog with messages stating that the Basic Information form requires a user name and an email address.

Click OK to dismiss the error dialog. Then enter a user name and email address. Be sure to confirm the email address in the form.

Again, click Next to progress to the next task. This time, the site should display the Address screen with icon buttons that you can select to create a new address record in the database (or, in the case of an existing customer, to update an existing address record).

Figure 2-31 shows the Address screen with one column for Address Label and no row information. Because you are entering information as a new customer, no address record currently exists, so no rows are available to display below these columns.

Figure 2-31 Customer Registration Page - Address Input Task

Click New. The registration page changes to display an address input form and the current train stop remains on Address.

For the fields with an asterisk symbol (*), enter the address information specified. The asterisk symbol indicates that the value is required. Note that you must also select a country from the dropdown list since this information is required by the database. Then click Save & Return to create the new address record in the database.

Figure 2-33 shows the Address screen with the row information for the new address record.

Figure 2-33 Customer Registration Page - Address Record Complete

This concludes the tour of the Fusion Order Demo application.

Where to Find Implementation Details

Following are the sections of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework that describe how to use complex components like the ADF Faces Train component used in the registration process:

Grouping activities using a bounded task flow

Every Fusion web application contains an unbounded task flow, which contains the entry points to the application. The application can then calls bounded task flows from activities within the unbounded task flow. For example, in the Fusion Order Demo application, the bounded task flow checkout-task-flow controls the flow of the checkout process and calls another bounded task flow customer-registration-task-flow to control the flow of the registration process. For information about the bounded task flow, see Section 14.1, "Introduction to ADF Task Flows."

Displaying a progression of related activities using a train component that you associate with a bounded task flow

You configure train stops based on activities that you select in an ADF bounded task flow and then you add the af:train component to your JSF pages. For example, in the Fusion Order Demo application, the bounded task flow customer-registration-task-flow defines four train stops for the page fragments basicInformation.jsff, defineAddresses.jsff, paymentOptions.jsff, and reviewCustomerInfo.jsff. The page register.jspx displays the fragments and each page fragment displays the train component bound to the activities that define the four stops. For information about the bounded task flow and how you can use it to define train stops, see Section 18.9.3, "How to Create a Train."

Requiring values to complete an input form

The input form displays attributes of a data collection that you drop from the Data Controls panel. You can set the required property of individual components in the form to control whether an attribute value is mandatory. For details about how to customize the required property, see Section 22.2, "Using Attributes to Create Text Fields." Alternatively, you can set a display control hint property directly on the attribute where it is defined by an ADF Business Components entity object. The entity object is a data model component that represents a row from a specific table in the database and that simplifies modifying its associated attributes. For details about using control hints to make an attribute mandatory, see Section 4.10, "Setting Attribute Properties."

Scripting on this page enhances content navigation, but does not change the content in any way.