2 Introduction to the ADF Sample 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:

  http://www.oracle.com/technetwork/developer-tools/jdev/overview/index.html
  

  Note:

  Ensure that you download and install 11g and that it is the Studio Edition, not the Java Edition. You can verify these details in Oracle JDeveloper from the Help > About menu option.

• Download the Fusion Order Demo application ZIP file (FusionOrderDemo_R1PS3.zip). You can download the ZIP file from:

  http://www.oracle.com/technetwork/developer-tools/jdev/index-095536.html
  

• 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:

  http://www.oracle.com/technetwork/index.html
  

  Specifically, the small footprint of the Oracle Express Edition (XE) is ideally suited for setting up the database on your local machine. You can download it from:

  http://www.oracle.com/technetwork/database/express-edition/overview/index.html
  

2.2.2 How to Install the Fusion Order Demo Schema

You can download the Fusion Order Demo application from the Oracle Technology Network (OTN) web site.

To download the demo and install the FOD schema to your database:

1. Navigate to http://www.oracle.com/technetwork/developer-tools/jdev/index-095536.html and download the ZIP file to a local directory.

2. Start Oracle JDeveloper 11g and from the main menu choose File > Open.

3. In the Open dialog, browse to the location where you extracted the ZIP file to in Step 1 and select Infrastructure.jws from the infrastructure directory. Click Open.

4. In the Application Navigator, expand MasterBuildScript and then Resources, and double-click build.properties.

5. In the editor, modify the properties shown in Table 2-1 for your environment.

   Table 2-1 Properties Required to Install the Fusion Order Demo Application

   Property	Description
   jdeveloper.home	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

   
   

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

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

8. 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.

Translations exist for the following base tables: PRODUCTS_BASE (PRODUCT_TRANSLATIONS), PRODUCT_CATEGORIES_BASE (CATEGORY_TRANSLATIONS), SHIPPING_OPTIONS_BASE (SHIPPING_OPTION_TRANSLATIONS), MEMBERSHIPS_BASE (MEMBERSHIP_TRANSLATIONS) and DISCOUNTS_BASE (DISCOUNT_TRANSLATIONS).

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.

The LOOKUP_CODES table also supports the localization of the user interface. The table uses a combined key of code and language (obtained from runtime locale or preference) to determine the code's meaning. Each code has an entry for each supported language, as described in Section 2.2.3.1, "Translation Support in the Fusion Order Demo Schema."

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.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.

Before you begin:

• In the Database Navigator, modify the connection information for the FOD database connection so it has the connection information for your environment, as described in Section 2.3, "Running the Fusion Order Demo Application StoreFront Module."

• 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:

1. Open the application in Oracle JDeveloper:

   1. From the JDeveloper main menu, choose File > Open.

   2. 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.

2. 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 example, Figure 2-7 shows the expanded ApplicationModules project with the Java file node TestClientCustomInterface.java selected.

   Figure 2-7 Test Client Selected in Application Navigator

   
   

3. Right-click the test client and choose Run.

   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.

4. 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:

1. Open the application in Oracle JDeveloper:

   1. From the JDeveloper main menu, choose File > Open.

   2. 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.

2. 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.

   Figure 2-8 Application Module Node Selected in Application Navigator

   
   

3. Right-click the application module node and choose Run.

   For the names of the runnable application modules, see the tables in Section 2.4.2 through Section 2.4.5.

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

   Refer to the referenced documentation for details about the application. For details about using the Browser to interact with the data model, see Section 6.3, "Testing View Object Instances Using the Business Component Browser."

2.4.2 Standalone Applications in the DevGuideExamples Application Workspace

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.

Figure 2-9 Runnable Applications in 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."

Table 2-4 describes the standalone applications in the DevGuideExamples application workspace. Examples from these applications appear throughout the chapters contained in Part II, "Building Your Business Services" of this guide.

2.4.3 Standalone Applications in the AdvancedExamples Application Workspace

The standalone applications assembled in the application workspace AdvancedExamples demonstrate advanced concepts that apply to the entire ADF Business Components framework.

Figure 2-10 shows the Application Navigator after you open the AdvancedExamples application workspace.

Figure 2-10 Runnable Applications in the AdvancedExamples Application Workspace

Table 2-5 describes the standalone applications in the AdvancedExamples application workspace. Examples from this application workspace are described in Chapter 37, "Advanced Business Components Techniques."

2.4.4 Standalone Applications in the AdvancedEntityExamples Application Workspace

The standalone applications assembled in the application workspace AdvancedEntityExamples demonstrate advanced concepts that apply to ADF Business Components entity objects.

Figure 2-11 shows the Application Navigator after you open the AdvancedEntityExamples application workspace.

Figure 2-11 Runnable Applications in the AdvancedEntityExamples Application Workspace

Table 2-6 describes the standalone applications in the AdvancedEntityExamples application workspace. Examples from this application workspace are described in Chapter 38, "Advanced Entity Object Techniques."

2.4.5 Standalone Applications in the AdvancedViewObjectExamples Application Workspace

The standalone applications assembled in the application workspace AdvancedViewObjectExamples demonstrate advanced concepts that apply to ADF Business Components view objects.

Figure 2-12 shows the Application Navigator after you open the AdvancedViewObjectExamples application workspace.

Figure 2-12 Runnable Applications in the AdvancedViewObjectExamples Application Workspace

Table 2-4 describes the standalone applications in the AdvancedViewObjectExamples application workspace. Examples from this application workspace are described in Chapter 39, "Advanced View Object Techniques."

2.5.1 Anonymous Browsing

You start the Fusion Order Demo application by running the home.jspx page in the StoreFrontUI project. For details about running the application using the default target, home.jspx page, see Section 2.3, "Running the Fusion Order Demo Application StoreFront Module."

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.

Figure 2-15 shows the home page.

Figure 2-15 Home Page with Multiple Regions

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 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.

Figure 2-16 shows the detail dialog that you can view for a product.

Figure 2-16 Home Page - Product Details Popup

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.

Figure 2-21 Home Page - Advanced Search Dialog - Saved Searches Option

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.

Figure 2-22 Home Page - Advanced Search Dialog - Personalization Option

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 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.

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.

Figure 2-26 shows the detail dialog for the Payment Option Code field.

Figure 2-26 Checkout Page - Payment Option Detail Dialog

Many of the fields of the payment options dialog offer user interface hints that guide you to enter specific information.

Figure 2-27 shows an example of a date entry (06-FEB-2009 10:47:21) that the format mask (dd-MMM-yyyy hh:mm:ss) defines for the Expiration Date field.

Figure 2-27 Checkout Page - Payment Options Detail Dialog - Date Format Mask

The Card Type field displays a dropdown that allows you to select from a valid list of credit card types.

Figure 2-28 displays the list of values for the Card Type field.

Figure 2-28 Checkout Page - Payment Options Detail Dialog - List of Values (LOV) Choice List

If you close the payment options dialog and click the Submit Order button in the checkout page, the purchase order is created and sent into a process flow.

After you place an order using the StoreFront module, a second module of the Fusion Order Demo application is available to process the order. For details about the WebLogic Fusion Order Demo module used to demonstrate the capabilities of Oracle SOA Suite, see Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite. For information about running this portion of the Fusion Order Demo application, see Section 2.3, "Running the Fusion Order Demo Application StoreFront Module."

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 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 Attribute 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.

Figure 2-30 Customer Registration Page - Basic Information Form with Validation Error Popup

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.

Figure 2-32 shows the empty address input form.

Figure 2-32 Customer Registration Page - Address Input Form

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.8.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."