14 Getting Started with ADF Task Flows

This chapter describes how to create ADF task flows that enable navigation, encapsulation, reuse, managed bean lifecycles, and transactions within an application. It includes the basic steps for creating a task flow diagram, adding activities and control flows to it, and running the finished task flow.

This chapter includes the following sections:

Section 14.1, "Introduction to Task Flows"
Section 14.2, "Creating Task Flows"
Section 14.3, "Adding a Bounded Task Flow to a Page"
Section 14.4, "Designating a Default Activity in an ADF Bounded Task Flow"
Section 14.5, "Running ADF Task Flows"
Section 14.6, "Setting Project Properties for ADF Task Flows"
Section 14.7, "Refactoring to Create New ADF Task Flows and Templates"
Section 14.8, "What You Should Know About Task Flow Constraints"

14.1 Introduction to Task Flows

ADF task flows provide a modular approach for defining control flow in an 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 view, executing application logic, or calling another task flow. The transactions between the activities are called control flow cases.

As shown in Figure 14-1, an activity is represented as a node in an ADF task flow diagram. Figure 14-1 contains two view activities called Create and Confirm. These view activities are similar to page nodes within a JSF page flow.

Figure 14-1 ADF Task Flow

14.1.1 Task Flow Advantages

ADF task flows offer significant advantages over standard JSF page flows, as described in Table 14-1.

Table 14-1 ADF Task Flow Advantages

JSF Page Flow	ADF Task Flow
The entire application must be represented within a single JSF page flow.	The application can be broken up into a series of task flows that call one another.
All nodes within a JSF page flow must be JSF pages. No other types of objects can exist within the JSF page flow.	You can add to the task flow diagram nodes such as views, method calls, and calls to other task flows.
Navigation is only between pages.	Navigation is between pages as well as other activities, including routers. For more information, see Section 15.4, "Using Router Activities".
Application fragments cannot be reused.	ADF task flows are reusable within the same or an entirely different application. After you break up your application into task flows, you may decide to reuse task flows containing common functionality. For more information see Chapter 32, "Reusing Application Components".
There is no shared memory scope between multiple requests except for session scope.	Shared memory scope (for example, page flow scope) enables data to be passed between activities within the task flow. Page flow scope defines a unique storage area for each instance of an ADF bounded task flow.

14.1.2 Task Flow Types

The two types of ADF task flow are:

Unbounded task flow: A set of activities, control flow rules, and managed beans that interact to allow a user to complete a task. An ADF unbounded task flow consists of all activities and control flows in an application that are not included within any bounded task flow.
B ounded task flow: A specialized form of task flow that has a single entry point and zero or more exit points. It contains its own set of private control flow rules, activities, and managed beans. An ADF bounded task flow allows reuse, parameters, transaction management, and reentry.

For a description of the activity types that you can add to an ADF unbounded or bounded task flow see Chapter 15, "Working with Task Flow Activities".

A bounded task flow is also called a task flow definition. A task flow definition source file contains the metadata for the bounded task flow. Multiple task flow definitions can be included within the same task flow definition file.

A typical application is a combination of an unbounded and one or more bounded task flows. Every Fusion web application contains an unbounded task flow, even if the unbounded task flow is empty. The application can then call bounded task flows from activities within the unbounded task flow.

As shown in Figure 14-2, the first activity to execute in an application is often a view activity within an ADF unbounded task flow. A view activity represents a JSF page that displays as part of the application. The activity shown in Figure 14-2 starts with the Home view activity and then calls a bounded task flow. The calltoLogin_taskFlow activity calls a bounded task flow that enables a user to log into the application.

Figure 14-2 Unbounded Task Flow Calling a Bounded Task Flow

You can also design an application in which all application activities reside within the ADF unbounded flow. This mimics a Struts or JSF application, but doesn't take advantage of ADF bounded task flow functionality. To take full advantage of task flow functionality, use ADF bounded task flows.

14.1.2.1 ADF Unbounded Task Flows

A Fusion web application always contains an ADF unbounded task flow, which contains the entry point or points to the application. Figure 14-3 displays the diagram for the unbounded task flow from the Fusion Order Demo Application. This task flow contains the Home, MyOrders, checkout, registerUser, and updateUserInfo view activities, which are all entry points to the application.

Figure 14-3 Unbounded Task Flow in Fusion Order Demo Application

You typically use an unbounded instead of a bounded task flow if:

You want to take advantage of ADF Controller features not offered by bounded task flows, such as bookmarked view activities. For more information, see Section 15.2.3, "Bookmarking View Activities".
You don't need ADF Controller features that are offered when using a bounded task flow.
The task flow will not be called by another task flow.
The application has multiple points of entry. In Figure 14-3, the task flow can be entered through any of the pages represented by the view activity icons on the unbounded task flows.

Pages are associated with view activities. The icon for a view activity displays a page image like this:
You want to bookmark more than one activity on the task flow. See Section 15.2.3, "Bookmarking View Activities" for more information.

An unbounded task flow cannot declaratively specify parameters. In addition, it cannot contain a default activity, an activity designated as the first to run in the unbounded task flow. This is because an unbounded task flow does not have a single point of entry. To perform any of these requires an ADF bounded task flow.

In order to take advantage of completely declarative ADF Controller transaction and reentry support, use a bounded rather than an unbounded task flow.

14.1.2.2 ADF Bounded Task Flows

An ADF bounded task flow is used to encapsulate a reusable portion of an application. A bounded task flow is similar to a Java method in that it:

Has a single entry point
May accept input parameters
May generate return values
Has its own collection of activities and control flow rules
Has its own memory scope and managed bean lifespan (a page flow scope instance)

The checkout-task-flow activity in Figure 14-3 is a call to an ADF bounded task flow. An unbounded task flow can call an ADF bounded task flow, but cannot be called by another task flow. A bounded task flow can call another bounded task flow, which can call another and so on. There is no limit to the depth of the calls.

The checkout process is created as a separate ADF bounded task flow, as shown in Figure 14-4.

Figure 14-4 Checkout Bounded Task Flow in Fusion Order Demo Application

The reasons for creating the checkout-task-flow activity as a called bounded task flow are:

The bounded task flow always specifies a default activity, a single point of entry that must execute immediately upon entry of the bounded task flow.

In the checkout task flow, the activity labeled syncShoppingCartForAuthenticatedUser is a call to a method that returns a list of items that an anonymous user (one who has not yet logged in to the application) may have chosen to purchase. Any items chosen before authentication are included in the shopping cart after the user has logged in. Because it is the default activity, the method is always invoked before the shopping cart order page displays.
checkout-task-flow is reusable. For example, it can be included in other applications requiring an item checkout process. The bounded task flow can also be reused within the same application.
Any managed beans you decide to use within checkout-task-flow can be specified in page flow scope, so are isolated from the rest of the application.

The main features of ADF bounded task flows are summarized in Table 14-2.

Table 14-2 ADF Bounded Task Flow Features

Feature	Description
Well-defined boundary	An ADF bounded task flow consists of its own set of private control flow rules, activities, and managed beans. A caller requires no internal knowledge of such things as page names, method calls, child bounded task flows, managed beans, and control flow rules within the bounded task flow boundary. Input parameters can be passed into the bounded task flow, and output parameters can be passed out on exit of the bounded task flow. Data controls can be shared between task flows.
Single point of entry	An ADF bounded task flow has a single point of entry, a default activity that executes before all other activities in the task flow. For more information, see Section 14.4, "Designating a Default Activity in an ADF Bounded Task Flow".
Page flow memory scope	You can specify page flow scope as the memory scope for passing data between activities within the ADF bounded task flow. page flow scope defines a unique storage area for each instance of an ADF bounded task flow. Its lifespan is the ADF bounded task flow, which is longer than request scope and shorter than session scope. For more information, see Section 14.2.11, "What You May Need to Know About Memory Scopes".
Addressable	You can access an ADF bounded task flow by specifying its unique identifier within the XML source file for the bounded task flow and the file name of the XML source file. For more information, see Section 15.6.7, "What Happens When You Add a Task Flow Call Activity".
Reuse	You can identify an entire group of activities as a single entity, an ADF bounded task flow, and reuse the bounded task flow in another application within an ADF region. For example, the Hot Items and Start Shopping tabs on the home page of the Fusion Order Demo application reuse the same task flow embedded in a region. Different parameters are passed to each region to determine the lists of products that display.For more information, see Section 17.1, "Introduction to ADF Regions". You can also reuse an existing bounded task flow simply by calling it. For example, one task flow can call another bounded task flow using a task flow call activity or a URL. In addition, you can use task flow templates to capture common behaviors for reuse across different ADF bounded task flows. For more information, see Section 18.10, "Creating an ADF Task Flow Template".
Parameters and return values	A caller can pass input parameters to an ADF bounded task flow and accept return values from it. For more information, see Section 16.3, "How to Pass Parameters to an ADF Bounded Task Flow". In addition, you can share data controls between bounded task flows. For more information, see Section 16.4, "Sharing Data Control Instances".
Transaction management	An ADF bounded task flow can represent a transactional unit of work. You can declaratively specify options on the task flow definition that determine whether, when entering the task flow, the task flow creates a new transaction, joins an existing one or is not part of the existing transaction. For more information, see Section 18.3, "Managing Transactions".
Reentry	You can specify options on the task flow definition that determine whether or not the ADF bounded task flow can be reentered. For more information, see Section 18.4, "Reentering an ADF Bounded Task Flow".
On-demand loading of metadata	ADF bounded task flow metadata is loaded on demand when entering an ADF bounded task flow.
Security	You can secure an ADF bounded task flow by defining the privileges that are required for someone to use it.

14.1.3 Control Flows

A task flow consists of activities and control flow cases that define the transitions between activities. In Figure 14-5, the control flow labeledtoView2 defines the transition between ViewActivity1 and ViewActivity2. When the task flow executes, ViewActivity1 displays prior to ViewActivity2.

Figure 14-5 Task Flow with Activities and Control Flow Cases

Task flow with activities and control flow rules.

Figure 14-5 contains a method call. The method's logic is invoked after ViewActivity2 and before it calls a bounded task flow. In a task flow, you have the option of invoking an activity such as a method before or after a page is rendered. Invoking logic outside of a particular page can facilitate reuse because the page can be reused in other contexts that don't require the method (for example, within a different task flow).

Control flow rules are based on JSF navigation rules, but capture additional information. JSF navigation is always between pages, whereas control flow rules describe transitions between activities. For example, a control flow rule can indicate a transition between a view activity and a subsequent method call activity. Or, it can indicate that control passes from the page to another task flow.

Save point restore, task flow return, and URL view activities cannot be the source of a control flow rule.

The basic structure of a control flow rule mimics a JSF navigation rule. Table 14-3 describes how metadata maps from JSF navigation rules to control flow rules.

Table 14-3 Mapping of JSF Navigation Rules to Control Flow Rules

JSF Navigation Rule	Control Flow Rule
Navigation Rule	Control Flow Rule
From View ID	From Activity ID
Navigation Case	Control Flow Case
From Action	From Action
From Outcome	From Outcome
To View ID	To Activity ID

Note:

When using ADF Controller task flows, perform all application navigation using ADF Controller control flow rules instead of using navigation rules in faces-config.xml.ADF Controller delegates navigation handling when no matching control flow cases are found in ADF Controller metadata. However, not all ADF Controller functionality is guaranteed to work correctly if navigation is performed by a non-ADF Controller NavigationHandler.

A wildcard control flow rule represents a control flowfrom-activity-id that contains a trailing wildcard (foo*) or a single wildcard character (*). In Figure 14-6, the wildcard control flow rule contains a single wildcard character, indicating that control can pass to the activities connected to it in the task flow diagram from any activity within the task flow.

Figure 14-6 Wildcard Control Flow Rule With Single Wildcard

The trailing wildcard in Figure 14-7 indicates that control flow can pass to the loginPage view from any valid source activity whose activity-id begins with the characters storefront.

Figure 14-7 Wildcard Control Flow Rule with Trailing Wildcard

14.2 Creating Task Flows

The processes for creating ADF bounded and unbounded task flows are similar. The main difference is that you select the Create as Bounded Task Flow checkbox in the Create ADF Task Flow dialog (shown in Figure 14-8) to create an ADF bounded task flow.

Before you begin to create a task flow, you must already have an application and project (see Chapter 1, "Introduction to Building Fusion Web Applications with Oracle ADF" for more information). You'll use the project to store any JSF pages, Java code, and XML source files associated with the task flow.

Note:

When you create the project, you may not need to create an unbounded task flow for it. If ADF Page Flow is specified as a selected technology on the Technology Scope page of the Project Properties dialog, the new adfc-config.xml source file is automatically created within the project. The adfc-config.xml source file is the main source file for an unbounded task flow.

14.2.1 How to Create an ADF Task Flow

You create an ADF unbounded task flow or an ADF bounded task flow in the Create Task Flow dialog shown in Figure 14-8.

To create an ADF unbounded or bounded task flow:

In the Application Navigator, right-click the project where you want to create the task flow and choose New.
In the New Gallery, expand Web Tier, select JSF and then ADF Task Flow and click OK.

The dialog shown in Figure 14-8 displays.

Figure 14-8 Create ADF Task Flow Dialog
In the Create ADF Task Flow dialog, 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.

Deselecting the checkbox automatically changes the default value in the File Name field. This value will be used to name the XML source file for the ADF task flow you are creating. The XML source file contains metadata describing the activities and control flow rules in the task flow:
- The default name for an unbounded task flow is adfc-config.xml.
- The default name for the source file for a bounded task flow matches the value specified in the Task Flow ID field.
Because a single project can contain multiple task flows, a number may be added to the default value in the File Name field in order to give the source file a unique name, for example, task-flow-definition3.xml.
Click OK.

A diagram representing the task flow displays in the editor.

Tip:
You can view a thumbnail of the entire task flow diagram by clicking the diagram and then choosing View > Thumbnail from the main menu.

After you create the task flow, you can update it in the Overview editor for task flows using the:

Diagram tab: A visual representation of a single task flow. Each node in the task flow diagram corresponds to an activity. Each line connecting activities corresponds to a control flow case.
Source tab: The XML source file for a task flow.
Overview tab: Options corresponding to metadata elements in the source file.

You can also use the Structure window to update the task flow.

Tip:

There are other ways to create task flows, for example, by refactoring the contents of an existing ADF task flow into a new task flow. For more information, see Section 14.7, "Refactoring to Create New ADF Task Flows and Templates".

14.2.2 How to Add an Activity to an ADF Task Flow

After you create a task flow, a task flow diagram and the Component Palette automatically display. The task flow diagram is a visual editor on which you can add the activities and control flows for the task flow. You can add them to the diagram by dragging them from the Component Palette.

To add an activity to an ADF task flow:

In the Application Navigator, double-click a task flow source file, for example, adfc-config.xml, to display the task flow diagram and Component Palette.

You can find XML source files under the Page Flows node in the WEB-INF node for the project containing the task flow.

In the task flow editor Overview editor for task flows, the Diagram tab displays the task flow diagram, as shown in Figure 14-9.
Figure 14-9 Task Flow Diagram

Notice that the Component Palette shown in Figure 14-9 automatically displays ADF task flow components.
Drag an activity from the ADF Task Flow page in the Component Palette onto the diagram.
- If you drag a view activity onto the diagram, you can double-click it to display the Create JSF JSP Page wizard, where you can define characteristics for the page or page fragment. For more information, see Section 15.2, "Using View Activities".
- If you drag a task flow call activity onto the diagram, you can double-click it to display the Create ADF Task Flow dialog where you can define settings for a new bounded task flow. For more information, see Section 15.6, "Using Task Flow Call Activities".

Tip:

E ach activity you drag to the task flow diagram can display optional status icons and a tooltip that provides additional information about the activity. For example, after you drag a view activity to the task flow diagram, it may display a warning icon until you associate it with a JSF page.

To turn on the icons, select Show at the top of the task flow diagram, and then select Status and one of the following:

Error: Displays when there is a problem in the task flow metadata which prevents it from running. For example, a view activity in the metadata can contain a <bookmark> or <redirect> element, but not both.
Warning: Displays when an activity is incomplete. For example, a view activity that doesn't have a physical page associated with it or a task flow call that doesn't have a task flow reference associated with it are both considered incomplete activities. The resulting task flow metadata may prevent it from running.

You can drag your mouse over a secondary icon to read a tooltip describing the icon's meaning.

14.2.3 What Happens When You Add an Activity to an ADF Task Flow

As shown in Figure 14-10, the Component Palette contains separate sections for components and diagram annotations. The contents of the Components section differ slightly depending on whether you are creating an ADF bounded or an unbounded task flow. For example, if you are creating an ADF bounded task flow, the Components section contains an additional task flow return activity.

Figure 14-10 displays the activities you can add to an ADF task flow.

Figure 14-10 ADF Unbounded Task Flow Component Palette

Component Palette for an unbounded task flow.

14.2.4 How to Add Control Flows

A control flow case identifies how control passes from one activity to the next in the application. To create a control flow, you select Control Flow Case in the ADF Task Flow page of the Component Palette and drag it from a source activity to a target activity. Dragging the control flow case between the two activities automatically creates a control flow comprised of the following:

control-flow-rule: Identifies the source activity using a from-activity-id.
control-flow-case: Identifies the target activity using a to-activity-id.

Once you identify an activity as the source for a control flow case, any additional control flow case that has the activity as its source is organized under the same control flow rule. In Figure 14-11, there is one control-flow-rule that identifies view1 as the source activity, and two control-flow cases that identify the target activities view2 and view3.

Tip:

You can drag and drop an activity onto an existing control flow. This splits the existing control flow into two, with the activity in the center.

There can be multiple control flow cases for each control flow rule. The order of control flow cases is determined by the order in which they appear in the adfc-config.xml file.

Figure 14-11 Multiple Control Flow Cases from a Single Activity

Multiple control flow cases from one activity.

Example 14-1 shows the metadata for the multiple control flow cases shown in Figure 14-11.

Example 14-1 Control Flow Rule Metadata Within a Task Flow Definition

<task-flow-definition id="task-flow-definition">
.
.
.    
    <control-flow-rule>
      <from-activity-id>view1</from-activity-id>
      <control-flow-case>
        <from-outcome>toView2</from-outcome>
        <to-activity-id>view2</to-activity-id>
      </control-flow-case>
      <control-flow-case>
        <from-outcome>toView3</from-outcome>
        <to-activity-id>view3</to-activity-id>
      </control-flow-case>
    </control-flow-rule>
.
.
.
 </task-flow-definition>

Use the task flow diagram as a starting point for creating basic control flows between activities. Later, you can edit control flow properties in the Structure window, Property Inspector or overview editor for the task flow diagram.

To define a control flow case directly in the task flow diagram:

In the Application Navigator, double-click a task flow source file, for example, adfc-config.xml, to display the task flow diagram.
In the ADF Task Flow page of the Component Palette, select Control Flow Case.
On the diagram, click a source activity, for example a view, and then click the destination activity. For example in Figure 14-12 , two activities have been linked with a control flow. Both source (view1) and the destinitation activities are linked.

Figure 14-12 Control Flow Case

JDeveloper adds the control flow case to the diagram. Each line that JDeveloper adds between activities represents a control flow case. The arrow indicates the direction of the control flow case. The from-outcome contains a value that can be matched against values specified in the action attribute of UI components.
To change the from-outcome, select the text next to the control flow in the diagram. By default, this text is the wildcard * character as shown in Figure 14-12. You can overwrite the text with a new from-outcome, for example, toView2.
To change the from-activity-id (identifies the source activity) or to-activity-id (identifies the target activity), drag either end of the arrow in the diagram to a new activity.

Tips:

After you select the control flow in the task flow diagram, you can also change its properties in the Property Inspector or the Structure window. The Structure window is helpful for displaying the relationship between control rules and cases.

You can also click Control Flows on the Overview tab for the task flow diagram to add cases, as shown in Figure 14-13. To add a case, make sure that the From Activity (source activity) and the To Activity (target activity) for the rule have already been added to the task flow.

Figure 14-13 Control Flows on Overview Editor for the Task Flow

14.2.5 How to Add a Wildcard Control Flow Rule

You can add a wildcard control flow rule to an unbounded or bounded task flow. The steps for adding it are similar to those for adding any activity to a task flow diagram.

To add a wildcard control flow rule:

In the Application Navigator, double-click a task flow source file, for example, adfc-config.xml, to display the task flow diagram.
Drag Wildcard Control Flow Rule from the ADF Task Flow page of the Component Palette and drop it on the task flow diagram.
Select Control Flow Case from the ADF Task Flow page list of the Component Palette.
In the task flow diagram, drag the control flow case from the wildcard control flow rule to the target activity.

The target can be any activity type.
By default, the label below the wildcard control flow rule is *, which corresponds to a single * character in its from-activity-id value. To change this value, select the wildcard control flow rule in the diagram. In the Property Inspector for the wildcard control flow rule, enter a new value in the from_activity_id_field, for example, project*. The wildcard must be a trailing character in the new label.

Tip:
You can also change the from-activity-id value in the Overview editor for the task flow diagram.

14.2.6 What Happens When You Create a Control Flow Rule

Understanding the elements that define the rules in the source file for the task flow helps when creating control flow rules directly in the ADF task flow diagram, ADF task flow overview editor, or Structure window, or when adding them directly in the XML source file. Example 14-2 shows the general syntax of a control flow rule element in the task flow source file.

Example 14-2 Control Flow Rule Syntax in the Source File

<control-flow-rule>
    <from-activity-id>from-view-activity</from-activity-id>
  <control-flow-case>
    <from-action>actionmethod</from-action>
    <from-outcome>outcome</from-outcome>
    <to-activity-id>destinationActivity</to-activity-id>
  </control-flow-case>
  <control-flow-case>
   .
   .
   .
  </control_flow-case>
</control-flow-rule>

Control flow rules can consist of the following metadata:

control-flow-rule: A mandatory wrapper element for control flow case elements.
from-activity-id: The identifier of the activity where the control flow rule originates, for example, source.

A trailing wildcard (*) character in from-activity-id is supported. The rule will apply to all activities that match the wildcard pattern. For example, login* matches any logical activity ID name beginning with the literal login. If you specify a single wildcard character in the metadata (not a trailing wildcard), the control flow automatically converts to a wildcard control flow rule activity in the diagram. For more information, see Section 14.2.5, "How to Add a Wildcard Control Flow Rule".
control-flow-case: A mandatory wrapper element for each case in the control flow rule. Each case defines a different control flow for the same source activity. A control flow rule must have at least one control flow case.
from-action: An optional element that limits the application of the rule to outcomes from the specified action method. The action method is specified as an EL binding expression, such as #{backing_bean.cancelButton_action}.

In Example 14-2, control passes to destinationActivity only if outcome is returned from actionmethod.

The value in from-action applies only to a control flow originating from a view activity, not from any other activity types. Wildcards are not supported in from-action.
from-outcome: Identifies a control flow case that will be followed based on a specific originating activity outcome. All possible originating activity outcomes should be accommodated with control flow cases.

If you leave both the from-action and the from-outcome elements empty, the case applies to all outcomes not identified in any other control flow cases defined for the activity, thus creating a default case for the activity. Wildcards are not supported in from-outcome.
to-activity-id: A mandatory element that contains the complete identifier of the activity to which the navigation is routed if the control flow case is performed. Each control flow case can specify a different to-activity-id.

14.2.7 What Happens at Runtime

At runtime, ADF Controller evaluates control flow rules from the most specific to the least specific match to determine the next transition between activities. Evaluation is based on the following priority, which is similar to that for JSF navigation rules:

from-activity-id, from-action, from-outcome
from-activity-id, from-outcome
from-activity-id

ADF Controller first searches for a match in all three elements: from-activity-id, from-action, and from-outcome. If there is no match, ADF Controller searches for a match in just the from-activity-id and from-outcome elements. Finally, ADF Controller searches for a match in the from-activity-id element alone.

If ADF Controller cannot find a control flow rule within its metadata to match a request, it will allow the standard JSF navigation handler to find a match.

An unbounded task flow can have more than one ADF Controller XML source file. Because control flow rules can be defined in more than one ADF Controller XML source file, similar rules may be defined in different files. If there is a conflict in which two or more cases have the same from-activity-id, and the same from-action or from-outcome values, the last case (as listed in the adfc-config.xml, bootstrap, or task flow definition source file) is used. If the conflict is among rules defined in different source files, the rule in the last source file to be loaded is used.

14.2.8 What Happens When You Create an ADF Task Flow

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. Another configuration file, adf-config.xml, is also created automatically (for more information, see Section A.11, "adf-config.xml" for more information).

As shown in Example 14-3, <adfc-config> appears first as the top-level element in all ADF Controller XML source files. Bounded task flows, activities and control flow rules are defined inside the <adfc-config> element. Bounded task flows are identified within the source file by the <task-flow-definition> metadata element.

Example 14-3 ADF Bounded Task Flow XML Source File

<?xml version="1.0" encoding="windows-1252" ?>
<adfc-config xmlns="http://xmlns.oracle.com/adf/Controller">
  <task-flow-definition id=<"task-flow-definition">
    <use-page-fragments/>
  </task-flow-definition>
</adfc-config>

An ADF bounded task flow is identified by its task flow reference, which is comprised of a unique combination of identifier and document name. Example 14-4 shows a sample task flow reference within a task flow call activity.

Example 14-4 Task Flow Reference

<adfc-config xmlns="http://xmlns.oracle.com/adf/Controller" version="1.2">
  <task-flow-definition id="task-flow-definition">
   <use-page-fragments/>
.
.
.
    <task-flow-call id="taskFlowCall">
      <task-flow-reference>
        <document>/WEB-INF/target-task-flow-definition.xml</document>
        <id>my-task-flow</id>
      </task-flow-reference>
    </task-flow-call>
.
.
.  
  </task-flow-definition>
</adfc-config>

Note:

If you use JDeveloper to create the ADF bounded task flow, specify only one ID (indicating one task flow definition) per document.

You assig n both identifier and document name when you create the ADF bounded task flow. As shown in Example 14-4, the identifier is the value in the Task Flow ID field. The document name is the value in the File Name field.

14.2.9 What Happens at Runtime: Using ADF Task Flows

A single application can have multiple ADF unbounded task flow XML source files and multiple ADF bounded task flow XML source files. The set of files that are combined to produce the ADF unbounded task flow is referred to as the application's ADF Controller bootstrap configuration files. An ADF unbounded task flow is assembled at runtime by combining one or more ADF Controller bootstrap configuration files. All activities within the bootstrap configuration files that are not contained within an ADF bounded task flow are considered to be within the ADF unbounded task flow.

For more information, see Section 18.12, "Specifying Bootstrap Configuration Files".

The names of the source files within a single application must be different. The example in Figure 14-14 contains two unbounded task flows (adfc-config, adfc-config2) and a bounded task flow (task-flow-definition).

Figure 14-14 Application with Two ADF Unbounded Task Flow XML Source Files

Application with two unbounded task flow source files.

14.2.10 What You May Need to Know About Managed Beans

Managed beans are Java classes that you register with the application using various configuration files. For more information, see Section 19.4, "Using a Managed Bean in a Fusion Web Application". Managed beans of any scope should be defined in the adfc-config.xml file. The advantages of doing this are:

All managed beans are handled consistently.
Content within adfc-config.xml, the ADF unbounded task flow source file, can be customized via MDS, whereas content in faces-config.xml can't be (for more information, see Chapter 33, "Customizing Applications with MDS").
Managed bean definitions of session, application, and request scope can reside in any task flow, not just the top-level one. That allows for better encapsulation of task flows so that they don't have to depend on things defined externally to the task flow.

All memory scopes are supported for managed beans in adfc-config.xml. ADF bounded task flows allow managed bean scopes of application, session, request, page flow, or none.

You can bind values to page flow scope-managed bean properties before control is passed to a called ADF bounded task flow. page flow scoped beans can be defined in ADF Controller source files only (adfc-config.xml and other bootstrap source files, and task flow definition files). They are not allowed in the faces-config.xml file.

In order to allow managed bean customizations in an ADF bounded task flow, ensure the managed bean metadata resides in the task flow definition for the ADF bounded task flow. Avoid placing managed beans within the faces-config.xml file.

When an ADF bounded task flow executes, faces-config.xml is first checked for managed bean definitions, then the task flow definition file for the currently executing task flow is checked. If no match is found in either location and the managed bean is in session or application scope, adfc-config.xml and other bootstrap XML source files are checked.

Lookup precedence is based on memory scope. request scope managed beans take precedence over session scope managed beans. For example, a request scope managed bean named abc in adfc-config.xml takes precedence over a session scope managed bean named abc in the current file.

An instantiated bean takes precedence over a new instantiated instance. For example, an existing session scope managed bean named abc takes precedence over a request scope bean named abc defined in the current task flow definition file.

14.2.11 What You May Need to Know About Memory Scopes

Each ADF bounded and unbounded task flow exists inside a page flow scope that is independent of the memory scope for all other task flows. Page flow scope is not a single state like session scope. It defines a unique storage area for each instance of an ADF bounded task flow. Each instance of the called ADF bounded task flow has its own state. An ADF bounded task flow may therefore be called recursively.

Use page flow scope as a means for passing data values between activities within a task flow. Application and session scopes are also allowed within task flow definition files, but can have unpredictable result outcomes.

Best Practice:

Avoid using application and session scope variables because they can persist in memory beyond the life of the ADF task flow. This may compromise the encapsulation and reusable aspects of a task flow.

In addition, application and session scopes may keep things in memory longer than needed, causing overhead. Use these scopes for the following purposes:

Use session scope only for information that is relevant to the whole session, such as user or context information. Avoid using session scope to pass values from one ADF task flow to another. Instead use page flow scope variables within the ADF task flow, and use parameters to pass values between task flows. Using parameters gives your task flow a clear contract with other task flows that call it or are called by it.
Use view scope for variables that are needed only within the current view activity and not across view activities.
Use request scope when the scope does not need to persist longer than the current request.
Use backing bean scope managed beans in your task flow if there is a possibility that your task flow will appear in two region components on the same page and you would like to isolate region instances.

As a rule, use the narrowest scope that will work. Overuse of sessionScope variables can be a maintenance problem. There isn't a good way to know all the variables that are being used in different places of the application. There is also the risk that other users will use the same variable and that you'll overwrite each other's settings. Using parameters gives your task flow a clear contract with other task flows that call it or are called by it. If a task flow needs a particular sessionScope variable to be set elsewhere, that fact might not be obvious to someone else using your task flow.

Page flow scope does not support implicit access. For example, you cannot specify #{inpTxtBB.uiComponent} and assume page flow scope. An EL expression that specifies page flow scope must be explicitly qualified, for example, #{pageFlowScope.inpTxtBB.uiComponent}.

When one task flow calls another, the calling task flow cannot access the called task flow's page flow scope and vice versa. For example, a UI component on a page in a bounded task flow cannot access the page flow scope of another task flow, even if the task flow is an ADF region embedded in the page (for more information, see Section 17.1, "Introduction to ADF Regions"). Instead, the UI component and the ADF region must pass parameter values to one another or share data controls.

Tip:

You can expand the Scope node in the Structure window to view a list of all memory scopes available in the current application context (the deepest-nested scope in the current view port).

14.2.11.1 View Scope

A view scope instance exists for each view port that ADF Controller manages, for example, a root browser window or a region. The lifespan of a view scope instance begins and end when the current viewId of a view port is changed. If you specify view scope, JDeveloper retains objects used on a page as long as the user continues to interact with the page. These objects are automatically released when the user leaves the page.

14.2.11.2 Backing Bean Scope

A backing bean is a managed bean that contains accessors for a UI component. Backing bean scope has a lifespan of a single request and provides an isolated instance of memory for backing beans. Other than having a different scope, management of backing beans in this scope is no different from other application beans already managed by ADF, such as page flow scope and view scope beans.

14.3 Adding a Bounded Task Flow to a Page

After you create a bounded task flow, you can drop its task flow definition from the Application Navigator onto a JSF page:

If the bounded task flow contains view activities that are page fragments, it is added to the JSF page as an ADF region. For more information, see Section 17.1, "Introduction to ADF Regions".

The home page of the Fusion Order demo application, for example, contains an ADF bounded task flow that displays a summary of items that the end user has added to a shopping cart page of the Fusion Order demo application. All view activities in the bounded task flow are page fragments, so the bounded task flow will be dropped on the Fusion Order demo application home page as a region. The contents of the shopping cart summary will display within a physical region on the home page of the Fusion Order demo application.
If the bounded task flow contains view activities that are pages, you have the option of adding a button or link to the JSF page. When clicked, the button or link executes the bounded task flow.

To add a bounded task flow containing pages to a JSF page:

In the Application Navigator, drag the ADF bounded task flow onto the page and drop it where you want the button or link to be located.

You can find task flows in the Application Navigator under the Page Flows or WEB-INF nodes.
Choose Create and either Task Flow Call as Button or Task Flow Call as Link.

As shown in Figure 14-15, the task flow definition appears on the JSF page as either a button or link UI component.

Figure 14-15 Button and Link UI Components

14.4 Designating a Default Activity in an ADF Bounded Task Flow

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.

ADF unbounded task flows do not have default activities.

As shown in Figure 14-16, a green circle identifies the default activity in a task flow diagram.

Figure 14-16 Default Activity in ADF Bounded Task Flow

Default activity in unbounded task flow.

The first activity that you add to a new ADF bounded task flow diagram is automatically identified as the default activity. You can also right-click any activity in the task flow diagram and choose Mark Activity > Default Activity. The default can be any activity type and it can be located anywhere in the control flow of the ADF bounded task flow. To find the default activity, right-click anywhere on the task flow diagram and choose Go to Default Activity.

An ADF bounded task flow can have only one default activity. If you mark a second activity as the default, the first is unmarked automatically. To unmark an activity manually, right-click the activity in the task flow diagram and choose Unmark Activity > Default Activity.

You should not specify a train stop in the middle of a train as a default activity (for more information, see Section 18.7, "Creating a Train").

Example 14-5 contains sample metadata for a default activity called SurveyPrompt in a task flow definition:

Example 14-5 Default Activity Metadata in Task Flow Definition

<task-flow-definition>
   <default-activity>SurveyPrompt</default-activity>
   <view id="SurveyPrompt">
      <page>/SurveyPrompt.jspx</page>
    </view>
</task-flow-definition>

14.5 Running ADF Task Flows

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, or whether it accepts input parameters.

14.5.1 How to Run a Task Flow Definition That Contains Pages

You can run or debug an ADF bounded task flow that contains view activities that are pages.

For information on running a task flow definition that contains view activities that are page fragments, see Section 14.5.2, "How to Run a Task Flow Definition That Uses Page Fragments".

Note:

You can select a view activity inside an ADF task flow diagram or the Application Navigator and choose Run to run an ADF bounded task flow.

In an ADF bounded task flow, you must designate the view as a default activity and run the ADF unbounded task flow from the Application Navigator. For more information, see Section 14.4, "Designating a Default Activity in an ADF Bounded Task Flow".

If the first activity that runs in the ADF task flow is an activity type other than view, you must use an ADF bounded task flow.

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

In the task flow diagram, right-click the task flow and choose either Run or Debug.
You can also run the task flow directly by entering its URL in the browser, for example. http://mymachine:8988/StoreFrontModule-StoreFrontUI-context-root/faces/home
You can right-click the task flow definition in the Application Navigator and choose either Run or Debug.

14.5.2 How to Run a Task Flow Definition That Uses Page Fragments

ADF bounded task flows that use page fragments are intended to run only within an ADF region. A page fragment is a JSF JSP document that is rendered as content in another JSF page. For more information, see Section 17.1.9, "What You May Need to Know About Page Fragments".

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

Create a JSF page containing a region that is bound to the task flow definition. When you drop a bounded task flow containing page fragments onto a JSF page, JDeveloper does this automatically for you.
Create a view activity in the project's unbounded task flow that refers to the page. See Section 14.2.2, "How to Add an Activity to an ADF Task Flow" for more information.
Right-click the view activity in the Application Navigator or in the task flow diagram and choose Run.

14.5.3 How to Run a Task Flow Definition That Has Parameters

Before you run a task flow definition with parameters, you must first run a task flow definition containing pages. For more information about bounded task flow input parameters, see Chapter 16, "Using Parameters in Task Flows".

To run a task flow definition that has input parameter definitions:

If the task flow definition has defined input parameters, the Set Run Configuration dialog displays after you select either Run or Debug, as shown in Figure 14-17.

Figure 14-17 Set Run Configuration dialog
In the Input Parameters list, enter values that you want to be passed as input parameters to the task flow. If you do not specify a value, the input parameter is not used when calling the bounded task flow.

Each required input parameter in the list displays with an asterisk, as shown in Figure 14-17. You must specify the parameter value as a literal string. You cannot specify an EL expression.
Click OK.

14.5.4 How to Run a JSF Page

You can run a JSF page by right-clicking the page in the Application Navigator and choosing Run. However, if the page contains navigation UI components, such as a button or link, navigation is not guaranteed to work.

To run a JSF Page with fully functioning navigation:

Create a bounded or unbounded task flow. See Section 14.2.1, "How to Create an ADF Task Flow" for more information.
Add a view activity to the task flow. See Section 14.2.2, "How to Add an Activity to an ADF Task Flow" for more information.
In the Application Navigator, select the JSF page you want to run and drop it on top of the view activity in the task flow diagram.

This associates the view activity with the JSF page.
In the diagram, right-click the view activity and choose Run.

14.5.5 How to Run an ADF Unbounded Task Flow

To run or debug an unbounded task flow, you must select a specific view activity with which to start.

To run a view activity in an ADF unbounded task flow:

In the task flow diagram, right-click the view activity and choose either Run or Debug.

The unbounded task flow runs beginning with the selected view activity.
If you have selected something other than a single view activity (or have nothing selected), you are prompted to select one in the Set Run Configuration dialog.

14.5.6 How to Set a Run Configuration for a Project

A run configuration contains settings that determine how projects run, such as specifying the first activity to run in a task flow. You can define one or more run configurations for a project. Within a run configuration, you can designate an ADFc source file as the default run target. When you run the project, the source file is the first to run.

To define a default task flow run target:

Select the project in the Application Navigator.
From the main menu, choose Run > Choose Active Run Configuration > Manage Run Configurations.
In the Manage Run Configurations dialog, choose Run/Debug/Profile and choose New.
In the New dialaog, enter the name for the new run configuration.
If you want to base the new configuration on an existing one, choose a configuration in the Copy Configuration Settings dropdown list.
Click OK to exit the dialog.
Click Edit.
In the Default Run Target dropdown list in the Edit Run Configuration dialog, select a source file for the ADF task flow that should run first when you run the project.

Once you choose a task flow, you can set a view activity (for an unbounded task flow) or input parameters (for task flow definitions).
In the left panel of the Edit Configuration dialog, click ADF Task Flow.
In the Task Flow dropdown list, located on the right panel, select the ADF task flow containing the run target.
If you are running an unbounded task flow, the Edit Run Configuration dialog displays the Run Target Activity list. Select the view activity that will run first in the application.
Click Open.

The next time you run the project, the saved run configuration will be available in the Run > Choose Active Run Configuration menu.

If you are running a bounded task flow that has been set up to accept input parameters, a dialog will display a section for specifying values for all input parameters defined for the bounded task flow. See Chapter 14, "How to Run a Task Flow Definition That Has Parameters" for more information.

14.6 Setting Project Properties for ADF Task Flows

You can set a project property to change the default source directory for ADF task flows created within a project. The task flow definition for any ADF task flow you create within the project will be located in this directory. This source directory for a new project is, by default, C:\JDeveloper\mywork\Application46\Project1\public_html\WEB-INF

To change the default source directory for task flow definitions:

In the Application Navigator, right-click the project and choose Project Properties.
In the left panel of the Project Properties dialog, click ADF Task Flows.
Select Use Project Settings.
In the ADF Task Flow Source Directory field, enter a new default directory for task flow definitions created within the project.

14.7 Refactoring to Create New ADF Task Flows and Templates

You can convert existing activities, JSF page flows, and JSF pages into new ADF Controller components such as ADF bounded task flows and task flow templates.

14.7.1 How to Create an ADF Bounded Task Flow from Selected Activities

You can create a new ADF bounded task flow based on activities you select in an existing ADF bounded or unbounded task flow.

To create a new ADF bounded task flow from selected activities:

In the editor, open the ADF unbounded or bounded task flow containing the activities you want to use in the new task flow.
In the task flow diagram, select one or more activities.

Tip:
To select multiple activities in a diagram, click the left mouse button and drag the cursor over the activities.
You can also press the Ctrl key while selecting each activity.
Right-click your selection and choose Extract Task Flow.

The Create Task Flow dialog displays, which allows you to create a new ADF bounded task flow. For more information, see Section 14.2, "Creating Task Flows".

When you are done, the new ADF bounded task flow displays in the editor. The properties shown in Table 14-4 are automatically set for the new task flow.

Table 14-4 Properties Updated in the New ADF Bounded Task Flow

Property	Value
Task flow definition ID	Value you entered in the Task Flow ID field in the Create ADF Task Flow dialog.
Default activity	Determined as the destination of all incoming control flow cases. If more than one destination exists, an error is flagged and the entire operation is rolled back.
Control flow rules	Control flow cases with selected source activities are included in the new ADF bounded task. A source activity is an activity from which a control flow leads. The new ADF bounded task flow includes the following types of control flow cases: Both the source and target activities in the control flow case were selected to create the new task flow. Only the source activity was selected to create the new task flow. Destinations are changed to the corresponding new task flow return activities added for each outcome.

Property

Value

Task flow definition ID

Value you entered in the Task Flow ID field in the Create ADF Task Flow dialog.

Default activity

Determined as the destination of all incoming control flow cases. If more than one destination exists, an error is flagged and the entire operation is rolled back.

Control flow rules

Control flow cases with selected source activities are included in the new ADF bounded task. A source activity is an activity from which a control flow leads. The new ADF bounded task flow includes the following types of control flow cases:

Both the source and target activities in the control flow case were selected to create the new task flow.
Only the source activity was selected to create the new task flow. Destinations are changed to the corresponding new task flow return activities added for each outcome.

The following changes automatically occur in the originating task flow (the task flow containing the activities you selected as the basis for the new task flow):

A new task flow call activity is added to the originating task flow. The task flow call activity calls the new ADF bounded task flow.
The selected activities are removed from the originating task flow.
Existing control flow cases associated with the activities you selected are removed from the originating task flow. They are replaced with new control flow cases:
- An incoming control flow case to the old activity is redirected to the new task flow call activity.
- An outgoing control flow case from the old activity is redirected from the new task flow call activity.

14.7.2 How to Create a Task Flow from JSF Pages

You can create a new ADF bounded task flow based on selected pages in a JSF page flow. Only pages that are part of a flow (that is, those that are linked by JSF navigation cases) are converted to view activities in the new task flow.

To create a new task flow from selected JSF pages in a page flow.

In the editor, open the page flow containing the pages you want to use in the new bounded task flow.
In the task flow diagram, select one or more JSF pages.

Tip:
To select multiple elements in a diagram, click the left mouse button and drag the cursor over the elements.
You can also press the Ctrl key while selecting each element.
Right-click your selection and choose Generate ADF Task Flow.

The Create Task Flow dialog displays, which allows you to create a new ADF unbounded or bounded task flow. For more information, see Section 14.2, "Creating Task Flows".

14.7.3 How to Convert ADF Bounded Task Flows

You can convert an existing ADF bounded task flow to an unbounded task flow or change whether the views it contains are pages or page fragments. Table 14-5 describes the results of each conversion.

Table 14-5 Converting ADF Bounded Task Flows

Conversion	Result
ADF bounded task flow to unbounded task flow	Loses all metadata not valid for unbounded task flows, such as parameter definitions and transactions.
ADF bounded task flow to use JSF pages	Converts page fragments associated with any view activities in the task flow to JSF pages. Old page fragments are saved if you select the Keep Page Fragment checkbox. New JSF page names default to the name of the old page fragment.
ADF bounded task flow to use page fragments	Converts all pages associated with view activities in the ADF bounded task flow to page fragments. Old pages are saved if you select the Keep Page checkbox. New page fragment names default to the name of the old page

To convert an ADF bounded task flow:

In the editor, open the bounded task flow diagram.
Right-click anywhere in the diagram other than on an activity or control flow.
Choose a menu item such as Convert to Unbounded Task Flow or Convert to Task Flow with Page Fragments.

If the bounded task flow contains fragments, the menu item will be Convert to Task Flow with Pages.

14.8 What You Should Know About Task Flow Constraints

Table 14-6 summarizes assumptions about and constants for using task flows, activities, and other associated ADF Controller features.

Table 14-6 ADF Controller Features Assumptions and Constraints

Feature Area	Assumption/Constraint	Description
ADF Controller objects and diagram UI	JSF view layer	ADF Controller operates only in a JSF 1.2 environment. Oracle's web-based Fusion web application strategy focuses on JSF as the sole view layer technology.
	Dependent on Oracle ADF Faces	ADF Controller extensions are implemented on top of Oracle ADF Faces. They are dependent on the ADF Faces libraries, but ADF Controller can run against any JSF implementation, providing these libraries are present.
	Navigation and state management encapsulated	ADF Controller encapsulates both navigation and, to some extent, state management. JSF and the Servlet API are still available for the basic management of state at the application, session, and request levels.
	Model layer	ADF model layer is used to implement the application's model layer.
	Dependent on MDS	ADF Controller metadata is stored in MDS. However, MDS is currently not capable of loading `faces-config.xml`. If the customization features that MDS provides are required, you should use ADF task flows exclusively in order to define managed beans and control flow rules.
	No supported migration path from struts or model 1	There is no support for a migration from Struts or Model 1 to the Fusion ADF Controller. However, you can create a new ADF bounded task flow based on selected pages in a JSF page flow. For more information, see Section 14.7.2, "How to Create a Task Flow from JSF Pages".
Bounded task flow	Exposed as page flow-scoped state	ADF Controller manages implementation of a page flow scoped-state. Any auto-management functions provided by the framework, such as back button support and state cleanup function, assume page flow-scoped data. In order for an application to fully implement such functions for all of its pages, the entire application should be exposed as an ADF bounded task flow, using nested bounded task flows as needed. The application should store any state requiring versioning within the page flow scope.
	Transactional boundaries	The developer will use ADF bounded task flows to manage transaction boundaries.
Page flow scope	Access availability within ADF lifecycle	An application cannot attempt to access the page flow scope early in the ADF lifecycle before ADF Controller is ready to provide it. Page flow scope is not guaranteed to be available for access until after Before and After listeners have executed on the Restore View phase. ADF Controller uses before and after listeners on the Restore View phase to synchronize the server side state with the request. This is where things such as browser back-button detection and bookmark dereference are handled.
Navigation	Navigation	When using ADF Controller task flows, perform all application navigation should be performed using ADF Controller control flow rules instead of using navigation rules in `faces-config.xml`. Although the ADF Controller delegates navigation handling when no matching control flow cases are found in ADF Controller metadata, not all ADF Controller functionality is guaranteed to work correctly if navigation is performed by a non-ADF Controller `NavigationHandler`.