Working with Oracle ADF Controller

3 Working with Oracle ADF Controller

In the controller layer, where handling page flow of your web applications is a key concern, ADF Controller provides an enhanced navigation and state management model on top of JSF. OEPE allows you to declaratively create task flows where you can pass application control between different types of activities, such as pages, methods on managed beans, case statements, or calls to other task flows.

These task flows can be reused, and can also be nested, both within themselves and within pages. Task flows nested in pages become regions that contain their own set of navigable pages, allowing users to view a number of different pages and functionality without leaving the main page.

This section contains the following topics:

Understanding ADF Task Flows
Creating a New Task Flow
Adding Activities to a Task Flow
Adding ADF Bindings to Your Task Flow
Adding Control Flows to a Task Flow
Using Task Flows as Regions
Running an ADF Task Flow

3.1 Understanding ADF Task Flows

ADF task flows provide a modular approach for defining control flow in an ADF application. Instead of representing an application as a single large JSF page flow, you can break it up into a collection of reusable task flows. Each task flow contains a portion of the application's navigational graph. The nodes in the task flows are activities. An activity node represents a simple logical operation such as displaying a page, executing application logic, or calling another task flow. The transitions between the activities are called control flow cases.

For more information about ADF Task Flows, see the Introduction to ADF Task Flows section in the "Getting Started with ADF Task Flows" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

3.2 Creating a New Task Flow

To create a new task flow:

In the Project Explorer, right-click your web project and select ADF Task Flow in the context menu. If the ADF Task Flow menu item is not visible, select Other, and in the New Gallery, expand Application Development Framework and double-click ADF Task Flow.
In the Create ADF Task Flow wizard, specify a file name (default: task-flow.xml) and location (default: WebContent/WEB-INF folder of your web project) for the ADF Task Flow. Then click Next.
On the Task Flow Options page, select options to specify the type of task flow you want to create. The Create as Bounded Task Flow checkbox is selected by default. Deselect it to create a source file that will be incorporated into the application's unbounded task flow. Select Task flow will use page fragments if you want the view activities that you add to the task flow to reference page fragments files (.jsff). Leave it unselected if you want the view activities that you add to the task flow to reference JSF pages. Then click Finish. The task flow that you created opens by default in the Diagram view of the ADF Task Flow Editor.
After you create the task flow, you can update it using the Diagram, Overview, or Source views. When you use the Design view, the Properties pane is context-aware, making additional configuration for various activities easily accessible without switching to the Overview pane.

A new XML source file is created every time you create a new ADF unbounded or bounded task flow. By default, the XML source file for an ADF unbounded task flow is called adfc-config.xml.

Note: Do not use the same name for more than one task flow in the same workspace, even if the task flows belong to different projects. Identical task flow names can cause unpredictable behavior while debugging.

3.3 Adding Activities to a Task Flow

To add activities to a task flow:

Drag an activity from the Palette onto the ADF Task Flow. Normally, you would start with a view activity.

If you drag a view activity onto the diagram, you can double-click it to display the wizard for the page or page fragment that the task flow is configured to invoke. Use the wizard to define characteristics for the page or page fragment.
If you drag a router activity onto the diagram, you can use the Properties pane to create an expression whose evaluation will determine which control flow rule will be followed.
If you drag a method call activity onto the diagram, you can use the Properties pane to configure the method to be called.
If you drag a task flow call activity onto the diagram, you can double-click it to display the Create Bounded Task Flow dialog where you can define settings for a new bounded task flow.
If you are creating a bounded task flow, and you drag a task flow return activity onto the diagram, you can use the Properties pane to configure the activity.

Note:The default activity is the first activity to execute in an ADF bounded task flow. For example, the default activity always executes first when a task flow call activity passes control to the ADF bounded task flow. The first activity that you add to a new ADF bounded task flow diagram is automatically identified as the default activity. A green blob over a node indicates that it is the default activity.

For more information on activity types, see the Introduction to Activity Types section in the "Working with Task Flow Activities" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

3.4 Adding ADF Bindings to a Task Flow

Once you have created your task flow, you can add ADF bindings to the Router, Method Call, and TaskFlow Call activities by creating Page Definitions.

To create a Page Definition for binding task flow activities:

Drop the activity onto the task flow page. ADF bindings can only be added to the Method Call, Router, and TaskFlow Call activities on a task flow.
Mouseover the activity to view the Create Page Definition icon. Click on that icon to create a new Page Definition, or to open an existing Page Definition.
Once you have a Page Definition for that activity, create a binding.

Example of a Method Call on a task flow page showing the Create Page Definition option.

Example of a Router on a task flow page showing the Create Page Definition option.

Example of a methodAction binding on the Page Definition that can be bound to a method call activity.

To configure ADF bindings for Method Calls in a task flow:

Create a Page Definition for the Method Call, if you don't already have one, and create a binding. In the Task Flow editor, choose the Overview tab.
In the Outline panel on the left, select the activity for which your are going to associate the method call to a binding.
In the Method Call Activity panel on the right, select the edit page icon next to the Method field. The Choose Method dialog appears. The bindings available for that method are shown.
Choose the appropriate binding and click OK.

Example showing the Choose Method dialog for a Method Call taskflow page definition.

To configure ADF bindings for Router activities in a task flow:

Create a Page Definition for the Router, if you don't already have one, and create a binding. In the Task Flow editor, choose the Overview tab.
In the Outline panel on the left, select the activity for which you are going to associate the Router to a binding.
In the Router Activity panel on the right, select the edit page icon next to the Router field. The bindings available for that router are shown.
Choose the appropriate binding and click OK.

Example of an attribute binding to be used to bind a Router in a taskflow.

Example showing the Choose Binding dialog for the Router activity.

3.5 Adding Control Flows to a Task Flow

A control flow case identifies how control passes from one activity to the next in the application.

To add a control flow case:

In the Palette, select Control Flow Case.
On the diagram, click a source activity, for example a view, and then click the destination activity.
Set the outcome value in the Properties pane, using either the From Action attribute (if the outcome is to be determine by a method) or the From Outcome attribute (if the outcome can be set as a String).

3.6 Using Task Flows as Regions

You can render a bounded task flow in a JSF page or page fragment (.jsff) by using an ADF region. When first rendered, the ADF region's content is that of the first view activity in the bounded task flow. The view activities used in the bounded task flow must be associated with page fragments, not pages.

You can pass values to the ADF Region using task flow binding input parameters or contextual events. In addition, you can configure the task flow binding's parametersMap property to determine what input parameters the task flow binding passes from the bounded task flow to the ADF region.

For more information on ADF Regions, see the Introduction to Using Task Flows in ADF Regions section in the "Using Task Flows as Regions" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

Before you create an ADF region, you need to do the following:

Create a bounded task flow with one or more view activities associated with page fragments or one task flow call activity to a task flow with view activities.
Create a page to host the ADF region.

To create an ADF Region:

In the Project Explorer, drag the bounded task flow onto the JSF page and drop it where you want to place the ADF region.
In the context menu, select Region.
Review or modify (as appropriate) the following properties which OEPE automatically populates with default values in the Properties pane for the ADF region:
- Id: An ID that the JSF page uses to reference the ADF region.
- Rendered: If selected (the default state), the ADF region renders when the JSF page renders.
- Value: An EL reference to the ADF region model, for example, #{bindings.task_flow1.regionModel}. This is the region model that describes the behavior of the region.

3.7 Running an ADF Task Flow

The procedure for running and debugging task flows differs depending on whether the task flow is bounded or unbounded, whether it contains pages or page fragments.

To run or debug a bounded task flow that uses pages:

Right-click the bounded task flow in the Project Explorer and choose either Run As or Debug As.

To run or debug a bounded task flow that uses page fragments:

Create a JSF page containing a region that is bound to the bounded task flow. When you drop a bounded task flow containing page fragments onto a JSF page, OEPE automatically prompts you to create a region.
Create a view activity in the project's unbounded task flow that refers to the page.
Right-click the view activity in the Project Explorer and choose Run.

For more information on running and debugging task flows, see the Testing ADF Task Flows section in the "Getting Started with ADF Task Flows" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.