14 Getting Started with ADF Task Flows

14.1.1 Task Flow Advantages

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

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.

• Bounded task flow: A specialized form of task flow that, in contrast to an unbounded task flow, 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 known as a task flow definition. By default, JDeveloper proposes the following filename for the source file of a bounded task flow:

  task-flow-definitionN.xml

  where N is a number that increments each time that you create a new bounded task flow.

  The file contains the metadata for the bounded task flow. Multiple task flow definitions (bounded task flows) 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. For example, JDeveloper, by default, creates an empty unbounded task flow (source file name is adfc-config.xml) when you create a Fusion web application using the Fusion Web Application template. At runtime, the Fusion web application can call bounded task flows from activities that you added to this 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 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 a number of view activities that 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 bookmarkable view activities. For more information, see Section 15.2.3, "Bookmarking View Activities".

• 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 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 reconcileShoppingCart invokes 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.2.3, "What You May Need to Know About the 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.4, "What You May Need to Know About Memory Scope for Task Flows".
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.8, "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.2, "Creating an ADF Region". 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 a 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 bounded task flow 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 bounded task flow that determine whether or not it can be reentered. For more information, see Section 18.4, "Reentering a 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 labeled toView2 defines the transition between ViewActivity1 and ViewActivity2. ViewActivity1 displays before ViewActivity2 when the task flow in Figure 14-5 executes.

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

Figure 14-5 contains a method call (methodCall1) that invokes after ViewActivity2 and before it calls the taskflowCall1 bounded task flow. In a task flow, you invoke an activity such as a method before or after a page renders. Invoking a method outside of a particular page can facilitate reuse because you can reuse the page in other contexts that don't require the method (for example, 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.

A wildcard control flow rule represents a control flow from-activity-id that contains a trailing wildcard (foo*) or a single wildcard character (*). Use the single wildcard character when you want to pass control from any activity in the task flow to the wildcard control flow rule. Alternatively, use a trailing wildcard when you want to constrain the activities that can pass control to the wildcard control flow rule.

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.1 How to Create a Task Flow

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 Task Flow dialog to create an ADF bounded task flow.

To create a task flow:

1. Create the task flow:

   1. In the Application Navigator, right-click the project where you want to create the task flow and choose New.

   2. 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 Task Flow Dialog

      
      

   3. In the Create 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.

      
      

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

      Clear the Create with Page Fragments checkbox that is selected by default if you want the view activities that you add to the task flow to reference JSF pages. Leave the Create with Page Fragments checkbox selected if you want the view activities that you add to the task flow to reference page fragments files (.jsff).

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

      
      

   5. After you create the task flow, you can update it using the diagram, overview, and source editors

      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.5, "Refactoring to Create New ADF Task Flows and Templates".

      
      

2. Drag an activity from the ADF Task Flow page in the Component Palette onto the diagram. Normally, you would start with a view activity. For more detailed procedures for adding any type of activity, see Section 14.3.1, "How to Add Additional Activities to an ADF Task Flow."

   • 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. For more information, see Section 15.2, "Using View Activities".

     
     

     Note: You can also add a view activity to a task flow by dragging a page from the Application Navigator and dropping it on the diagram for the task flow.

     
     

   • If you drag a router activity onto the diagram, you can user the Property Inspector to create an expression whose evaluation will determine which control flow rule will be followed. For more information, see Section 15.4, "Using Router Activities."

   • If you drag a method call activity onto the diagram, you can use the Property Inspector to configure the method to be called. For more information, see Section 15.5, "Using Method Call Activities."

   • 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. For more information, see Section 15.6, "Using Task Flow Call Activities".

   • If you are creating a bounded task flow, and you drag a task flow return activity onto the diagram, you can use the Property Inspector to configure the activity. For more information, see Section 15.7, "Using Task Flow Return Activities."

3. Create control flow cases between the activities (for more information and detailed procedures, see Section 14.3.3, "How to Add Control Flows"):

   1. In the ADF Task Flow page of the Component Palette, select Control Flow Case.

   2. On the diagram, click a source activity, for example a view, and then click the destination activity. For example in Figure 14-15, two activities have been linked with a control flow. Both source (view1) and the destination (view2) activities are linked.

   3. Set the outcome value, 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).

4. If you are creating a bounded task flow, once that flow is complete, you may want to designate one of the activities as the default activity. Doing so ensures that specific activity will be executed first whenever the task flow is run. By default, the first activity you added to the task flow is the default. To change to a different activity, right-click the appropriate activity in the diagram and choose Mark Activity > Default Activity. For more information, see Section 14.2.3, "What You May Need to Know About the Default Activity in an ADF Bounded Task Flow."

14.2.2 What Happens When You Create a 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.

As shown in Example 14-1, <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.

<?xml version="1.0" encoding="windows-1252" ?>
<adfc-config xmlns="http://xmlns.oracle.com/adf/controller" version="1.2" id="__1">
  <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-2 shows a sample task flow reference within a task flow call activity.

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

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

14.2.3 What You May Need to Know About the 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-9, a green circle identifies the default activity in a task flow diagram.

Figure 14-9 Default Activity in 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. 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.8, "Creating a Train").

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

<task-flow-definition id="survey">
    <default-activity>SurveryPrompt</default-activity>
    <view id="SurveryPrompt">
      <page>/SurveryPrompt.jsff</page>
    </view>
    <use-page-fragments/>
</task-flow-definition>

14.2.4 What You May Need to Know About Memory Scope for Task Flows

Each task flow in your Fusion web application defines a pageFlow scope to manage state. The pageFlow scope begins when the task flow begins and ends when the task flow ends. A pageFlow scope defines a unique storage area for each instance of a task flow within an application which is used to pass data values between the activities in the task flow. When one task flow calls another, the calling task flow cannot access the called task flow's pageFlow scope. This means, for example, that a UI component on a page referenced by a task flow's view activity cannot access the pageFlow scope of another task flow even if this task flow is an ADF region embedded in the same page as the UI component.

You can register multiple managed beans with task flows. Figure 14-10 shows examples from the Fusion Order Demo application where the default unbounded task flow (adfc-config.xml) and the customer registration task flow reference multiple managed beans with varying scope values. You can determine the scope assigned to a managed bean.

Figure 14-10 Managed Beans Registered with Task Flows

Table 14-4 lists available scopes for managed beans and describes when it is appropriate to use each scope in a managed bean that you register with a task flow. The table lists the scopes in order of their life span. For example, the application scope has a longer life span than the request scope.

When you register a managed bean with a task flow, JDeveloper generates an entry similar to the following in the task flow's source file:

<managed-bean id="__15">
    <managed-bean-name id="__16">egBackingBean</managed-bean-name>
    <managed-bean-class id="__13">oracle....egBackingBean</managed-bean-class>
    <managed-bean-scope id="__14">backingBean</managed-bean-scope>
</managed-bean>

The <managed-bean-scope> element holds the value for the scope of the managed bean (backingBean in the example).

When you bind a UI component to a managed bean, JDeveloper appends Scope to the scope name in the EL expression that it generates to reference the managed bean. For example, the binding attribute of a table component that references the managed bean has the following EL expression:

<af:table id="cartTab"
          ...
          binding="#{backingBeanScope.egBackingBean.table}"
         ...
</af:table>

Restrict the scope of the managed bean that you reference through a UI component's binding attribute to backingBean or request scope. Instances of UI components cannot be serialized. Objects in scopes other than backingBean and request are expected to be serializable. For this reason, you should not bind UI components to managed beans that have a scope other than backingBean or request. Note that JDeveloper defaults the binding attribute for UI components and region fragments to use the backingBean scope.

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

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

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

14.3.1 How to Add Additional Activities 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:

1. In the Application Navigator, double-click a task flow source file.

   For example, Figure 14-12 shows the editor and the Component Palette that automatically appears when you double-click a task flow source file (task-flow-definition.xml).

   Figure 14-12 Task Flow Diagram

   
   

2. 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 Page Fragment 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 Bounded 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".

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

As shown in Figure 14-13, 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-13 displays the activities you can add to an ADF task flow.

Figure 14-13 ADF Unbounded Task Flow Component Palette

14.3.3 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-14, 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.

There can be multiple control flow cases for each control flow rule.

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

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

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

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

2. In the ADF Task Flow page of the Component Palette, select Control Flow Case.

3. On the diagram, click a source activity, for example a view, and then click the destination activity. For example in Figure 14-15, two activities have been linked with a control flow. Both source (view1) and the destination activities are linked.

   Figure 14-15 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.

4. 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-15. You can overwrite the text with a new from-outcome, for example, toView2.

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

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

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

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

2. Drag Wildcard Control Flow Rule from the ADF Task Flow page of the Component Palette and drop it on the task flow diagram.

3. Select Control Flow Case from the ADF Task Flow page list of the Component Palette.

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

5. 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, enter 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.3.5 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-5 shows the general syntax of a control flow rule element in the task flow 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.3.4, "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-5, 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.3.6 What Happens at Runtime: Evaluating Control Flow Rules

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:

1. from-activity-id, from-action, from-outcome

2. from-activity-id, from-outcome

3. 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 bounded task flow 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.4.1 How to Run a Bounded Task Flow 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 bounded task flow that contains view activities that are page fragments, see Section 14.4.2, "How to Run a Bounded Task Flow That Uses Page Fragments".

To run or debug a bounded task flow 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 bounded task flow in the Application Navigator and choose either Run or Debug.

14.4.2 How to Run a Bounded Task Flow 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.3.1, "Page Fragments and ADF Regions".

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

1. 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, JDeveloper does this automatically for you.

2. Create a view activity in the project's unbounded task flow that refers to the page. See Section 14.3.1, "How to Add Additional Activities to an ADF Task Flow" for more information.

3. Right-click the view activity in the Application Navigator or in the task flow diagram and choose Run.

14.4.3 How to Run a Bounded Task Flow That Has Parameters

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

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

1. If the bounded task flow 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

   
   

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

3. Click OK.

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

1. Create a bounded or unbounded task flow. See Section 14.2.1, "How to Create a Task Flow" for more information.

2. Add a view activity to the task flow. See Section 14.3.1, "How to Add Additional Activities to an ADF Task Flow" for more information.

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

4. In the diagram, right-click the view activity and choose Run.

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

1. Select the project in the Application Navigator.

2. From the main menu, choose Run > Choose Active Run Configuration > Manage Run Configurations.

3. In the Manage Run Configurations dialog, choose Run/Debug/Profile and choose New.

4. In the New dialog, enter the name for the new run configuration.

5. If you want to base the new configuration on an existing one, choose a configuration in the Copy Configuration Settings dropdown list.

6. Click OK to exit the dialog.

7. Click Edit.

8. 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 bounded task flows).

9. In the left panel of the Edit Configuration dialog, click ADF Task Flow.

10. In the Task Flow dropdown list, located on the right panel, select the ADF task flow containing the run target.

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

12. 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 Bounded Task Flow That Has Parameters" for more information.

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

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

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

   
   

3. 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 a Task Flow".

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

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

1. In the editor, open the page flow containing the pages you want to use in the new bounded task flow.

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

   
   

3. 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 a Task Flow".

14.5.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-6 describes the results of each conversion.

To convert an ADF bounded task flow:

1. In the editor, open the bounded task flow diagram.

2. Right-click anywhere in the diagram other than on an activity or control flow.

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