18 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 18.1, "About ADF Task Flows"
Section 18.2, "Creating a Task Flow"
Section 18.3, "Adding Activities to a Task Flow"
Section 18.4, "Adding Control Flow Rules to Task Flows."
Section 18.5, "Testing Task Flows"
Section 18.6, "Refactoring to Create New Task Flows and Task Flow Templates"
Section 18.7, "What You Should Know About Task Flow Constraints"

18.1 About ADF Task Flows

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

Figure 18-1 shows two view activities called Create and Confirm. These view activities are similar to page nodes within a JSF page flow.

Figure 18-1 ADF Task Flow

The are two types of ADF task flow:

Unbounded task flow: A set of activities, control flow rules, and managed beans that interact to allow a user to complete a task. The unbounded task flow consists of all activities and control flows in an application that are not included within a bounded task flow.
Bounded task flow: A specialized form of task flow that, in contrast to the unbounded task flow, has a single entry point (an entry point is a view activity that can be directly requested by a browser) and zero or more exit points. It contains its own set of private control flow rules, activities, and managed beans. A bounded task flow allows reuse, parameters, transaction management, reentry, and can render within an ADF region in a JSF page.

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

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. You can choose a filename for the bounded task flow. For example, you might use checkout-task-flow.xml if the purpose of the bounded task flow is to allow customers check out from a shopping application.

The source file contains the metadata for the bounded task flow. Multiple bounded task flows can be included within the same source file using the following metadata:
```
<task-flow-definition id="TaskFlowID1">
        ...
          </task-flow-definition>
<task-flow-definition id="TaskFlowID2">
        ...
</task-flow-definition>
```
However, as JDeveloper's visual editors show one bounded task flow per file, we do not recommend that you include more than one bounded task flow within the same source file.

A typical application is a combination of the unbounded task flow 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 an application using the Fusion Web Application template. At runtime, the Fusion web application can call bounded task flows from activities that you added to the unbounded task flow.

As shown in Figure 18-2, the first activity to execute in an application is often a view activity within the unbounded task flow. A view activity represents a JSF page that displays as part of the application. The activity shown in Figure 18-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 18-2 Unbounded Task Flow Calling a Bounded Task Flow

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

Table 18-1 describes the advantages that the control flow provided by ADF task flows offers over the control flow offered by JSF page flow. In certain scenarios you may need to use JSF page flow. For example, using phase listeners, as described in Section 25.4, "Customizing the ADF Page Lifecycle," involves using the JSF page flow's faces-config.xml configuration file. In general, it is not recommended that you mix JSF page flow and ADF task flows in your application.

Table 18-1 ADF Task Flow Advantages

JSF Page Flow	ADF Task Flow
The entire application must be represented in a single page navigation file (`faces-config.xml`). Although you can have multiple copies of `faces-config.xml` in a project, the application loads these files as one at runtime.	The application can be broken up into a series of modular 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 19.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 38, "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 a bounded task flow.

18.1.1 About Unbounded Task Flows

A Fusion web application always contains an ADF unbounded task flow, which contains the entry point or points to the application. An entry point is a view activity that can be directly requested by a browser. A Fusion web application only has one unbounded task flow. By default, the source file for the unbounded task flow is the adfc-config.xml file. Although you can create additional source files for unbounded task flows, the application combines all source files at runtime into the adfc-config.xml file. Figure 18-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 18-3 Unbounded Task Flow in Fusion Order Demo Application

You typically use the unbounded task flow 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 19.2.2, "Bookmarking View Activities".
The task flow will not be called by another task flow.
The application has multiple points of entry. In Figure 18-3, the task flow can be entered through any of the pages represented by the view activity icons on the unbounded task flows.
You want to bookmark more than one activity on the task flow. See Section 19.2.2, "Bookmarking View Activities" for more information.

The 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 the unbounded task flow does not have a single point of entry. To perform any of these requires a bounded task flow.

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

18.1.2 About 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)

For more information about memory scopes, see Section 18.2.4, "What You May Need to Know About Memory Scope for Task Flows."
Can determine whether or not it has an isolated data control frame

For more information about access to data control frames, see Section 22.2, "Sharing Data Controls Between Task Flows."
Can define an activity as an exception handling activity

For more information about exception handling in bounded task flows, see Section 22.5, "Handling Exceptions in Task Flows."

The checkout-task-flow activity in Figure 18-3 is a call to a bounded task flow. The unbounded task flow can call a 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 bounded task flow, as shown in Figure 18-4.

Figure 18-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. These managed beans (with page flow scope) are automatically released when the task flow completes.

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

Table 18-2 Bounded Task Flow Features

Feature	Description
Well-defined boundary	A 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 return values can be passed out on exit of the bounded task flow. Data controls can be shared between task flows.
Single point of entry	A 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 18.2.3, "What You May Need to Know About the Default Activity in a Bounded Task Flow".
Page flow memory scope	You can specify page flow scope as the memory scope for passing data between activities within the bounded task flow. Page flow scope defines a unique storage area for each instance of a bounded task flow. Its lifespan is the bounded task flow, which is longer than request scope and shorter than session scope. For more information, see Section 18.2.4, "What You May Need to Know About Memory Scope for Task Flows".
Addressable	You can access a 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 19.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, a 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 21.3, "Specifying Parameters for 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 bounded task flows. For more information, see Section 22.9, "Creating Task Flow Templates".
Parameters and return values	A caller can pass input parameters to a bounded task flow and accept return values from it. For more information, see Section 20.3, "Passing Parameters to a Bounded Task Flow". In addition, you can share data controls between bounded task flows. For more information, see Section 22.2, "Sharing Data Controls Between Task Flows."
Transaction management	A 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 22.3, "Managing Transactions in Task Flows".
Reentry	You can specify options on the bounded task flow that determine whether or not it can be reentered. For more information, see Section 22.4, "Reentering Bounded Task Flows".
On-demand loading of metadata	Bounded task flow metadata is loaded on demand when entering a bounded task flow.
Security	You can secure a bounded task flow by defining the privileges that are required for someone to use it. For more information, see Section 35, "Enabling ADF Security in a Fusion Web Application."

18.1.3 About Control Flows

A task flow consists of activities and control flow cases that define the transitions between activities. Figure 18-5 shows a control flow rule, labeled toView2, that defines the transition between the ViewActivity1 and ViewActivity2 view activities. The ViewActivity1 view activity displays before the ViewActivity2 view activity when the task flow in Figure 18-5 executes.

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

Task flow with activities and control flow rules.

The task flow in Figure 18-5 also contains a method call activity (methodCall1) that invokes after the ViewActivity2 view activity and before the taskflowCall1 task flow call activity. In a task flow, you invoke an activity such as a method call activity before or after a page renders. Invoking a method call activity 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). For more information about control flow rules, see Section 18.4, "Adding Control Flow Rules to Task Flows."

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 18-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 18-6 Wildcard Control Flow Rule With Single Wildcard

The trailing wildcard in Figure 18-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 18-7 Wildcard Control Flow Rule with Trailing Wildcard

For more information about wildcard control flow rules, see Section 18.4.2, "How to Add a Wildcard Control Flow Rule."

18.1.4 ADF Task Flow Use Cases and Examples

Figure 18-8 shows a screen from the Fusion Order Demo application described in Chapter 2, "Introduction to the ADF Sample Application." End users can invoke a number of bounded task flows from this screen. The Register as a customer command button invokes the customer registration task flow (customer-registration-task-flow.xml) that allows a potential customer to register to use the application. This task flow renders screens where the user enters data such as name, email address, and so on. The Register as an employee command button invokes the employee registration task flow (employee-registration-task-flow.xml) that enables employees to register. Where appropriate, the customer registration and employee registration task flows reuse the same view activities. A third task flow in Figure 18-8 is the help-task-flow.xml task flow that renders in the Registration Help area. This task flow provides assistance to the users as they navigate the tasks in the customer and employee registration task flows.

Figure 18-8 Task Flows for Registration and User Assistance

Task flows can also be used to secure your Fusion web application by reducing the number of access points that you expose to end users. For example, configure an unbounded task flow to display one page that provides navigation to the remaining pages in your application. Use bounded task flows for the remaining pages in the application. By setting the URL Invoke property of these bounded task flows to url-invoke-disallowed, your application has one access point (the page on the unbounded task flow). For more information about the URL Invoke property, see Section 19.6.4, "How to Call a Bounded Task Flow Using a URL." For more information about securing your Fusion web application, see Chapter 35, "Enabling ADF Security in a Fusion Web Application."

18.1.5 Additional Functionality for ADF Task Flows

You may find it helpful to understand other ADF features before you configure or use ADF task flows. Additionally, you may want to read about what you can do with your task flow configurations. Following are links to other functionality that may be of interest.

Task flows can invoke managed beans. For more information about defining managed beans for use with a task flow, the supported memory scopes, and other related information, see Section 18.2.4, "What You May Need to Know About Memory Scope for Task Flows" and Section 24.4, "Using a Managed Bean in a Fusion Web Application".
Task flows are reusable. For more information about reusing functionality in your application, Chapter 38, "Reusing Application Components."
Task flows can be secured by defining the privileges that are required for someone to use it. For more information, see Chapter 35, "Enabling ADF Security in a Fusion Web Application."
You can extend the functionality that your task flows implement by writing custom code. For example, you can write a custom exception handler that a task flow passes control to when a task flow activity raises an exception. For more information, see Section 22.5.3, "How to Designate Custom Code as an Exception Handler."

Make sure when you write custom code that you do not import packages that are marked internal, as in the following example:

import oracle.adfinternal.controller.*;

For information about the APIs that you can use to write custom code, see the following reference documents:
- Oracle Fusion Middleware Java API Reference for Oracle ADF Controller
- Oracle Fusion Middleware Java API Reference for Oracle ADF Faces

18.2 Creating a Task Flow

A task flow is made up of the task flow itself, plus a number of activities with control flow rules between those activities. In most cases, the majority of the activities are view activities which represent the different pages in the flow. When some method or operation needs to be called, for example before a page is rendered, you use a method call activity with a control flow case from that activity to the appropriate next activity. When you want to call another task flow, you use a task flow call activity. If the flow requires some sort of branching, you use a router activity. At the end of a bounded task flow, you use a return activity which allows the flow to exit and control is sent back to the flow that called this bounded task flow.

For more detailed information and procedures regarding the individual components of a task flow, including the metadata created for each and additional configuration that you can set, see Section 18.3, "Adding Activities to a Task Flow."

18.2.1 How to Create a Task Flow

The processes for creating 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 a bounded task flow.

Note:

When you create the project, you may not need to create the unbounded task flow for it. If ADF Page Flow is specified as a selected technology on a 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 the unbounded task flow.

Before you begin:

It may be helpful to have an understanding of what constitutes a task flow. For more information, see Section 18.2, "Creating a Task Flow."

You may also find it helpful to understand functionality that can be added using other task flow features. For more information, see Section 18.1.5, "Additional Functionality for ADF Task Flows."

To create a task flow:

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/Facelets and then select ADF Task Flow, and click OK.
  
  The dialog shown in Figure 18-9 displays.
  
  Figure 18-9 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 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 the 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.
4. In the Create Task Flow dialog, the Create with Page Fragments checkbox is selected by default.
  
  Clear this checkbox if you want the view activities that you add to the task flow to reference JSF pages that render in the main browser window as the root page. 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) that the task flow displays in an ADF region at runtime.
5. 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.
6. 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 task flow into a new task flow. For more information, see Section 18.6, "Refactoring to Create New Task Flows and Task Flow Templates".
In the ADF Task Flow page of the Component Palette, from the Component panel, drag and drop an activity onto the diagram.

Normally, you would start with a view activity. For more detailed procedures for adding any type of activity, see Section 18.3.1, "How to Add an Activity to a Task Flow."
- If you drag a view activity onto the diagram, you can double-click it to display the wizard for the JSF 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 19.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 19.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 19.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 19.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 19.7, "Using Task Flow Return Activities."
Create control flow cases between the activities (for more information and detailed procedures, see Section 18.4.1, "How to Add a Control Flow Rule to a Task Flow"):
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 18-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).
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 makes sure that this specific activity executes first whenever the task flow runs. 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 18.2.3, "What You May Need to Know About the Default Activity in a Bounded Task Flow."

18.2.2 What Happens When You Create a Task Flow

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

As shown in Example 18-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.

Example 18-1 Bounded Task Flow XML Source File

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

A bounded task flow is identified by its task flow reference, which is comprised of a unique combination of identifier and document name. Example 18-2 shows a sample task flow reference within a task flow call activity.

Example 18-2 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 bounded task flow, specify only one ID (indicating one bounded task flow) per document.

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

18.2.3 What You May Need to Know About the Default Activity in a Bounded Task Flow

The default activity is the first activity to execute in a bounded task flow. For example, the default activity always executes first when a task flow call activity passes control to the bounded task flow.

Unbounded task flows do not have default activities.

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

Figure 18-10 Default Activity in a Bounded Task Flow

Default activity in unbounded task flow.

The first activity that you add to a new 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 bounded task flow. To find the default activity, right-click anywhere on the task flow diagram and choose Go to Default Activity.

A 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 22.8, "Using Train Components in Bounded Task Flows").

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

Example 18-3 Default Activity Metadata 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>

18.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 define multiple managed beans with task flows. Figure 18-11 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 18-11 Managed Beans Registered with Task Flows

Table 18-3 lists available scopes for managed beans and describes when it is appropriate to use each scope in a managed bean that you define 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. For more information the life span of object scopes, see Section 25.3, "About Object Scope Lifecycles."

Table 18-3 Memory Scope for ADF Managed Beans

Scope	Description
application	The application scope lasts until the application stops. Values that you store in a managed bean with this scope are available to every session and every request that uses the application. Avoid using this scope in a task flow because it persists beyond the life span of the task flow.
session	The session scope begins when a user first accesses a page in the application and ends when the user's session times out due to inactivity, or when the application invalidates the session. Use this scope only for information that is relevant to the whole session, such as user or context information. Avoid using it to pass values from one task flow to another. Instead, 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. Another reason to avoid use of session scope is because it may persist beyond the life span of the task flow. Finally, if an end user opens multiple browser windows within the same session, session scoped values are shared across these browser windows. Conflicts can occur between these browser windows.
pageFlow	Choose this scope if you want the managed bean to be accessible across the activities within a task flow. A managed bean that has a pageFlow scope shares state with pages from the task flow that access it. A managed bean that has a pageFlow scope exists for the life span of the task flow.
view	Use this scope for managed bean objects that are needed only within the current view activity and not across view activities. The life span of this scope begins and ends when the current `viewId` of a view port changes. If you specify view, the application retains managed bean 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. Both JSF and Oracle ADF have an implementation of this scope. In a Fusion web application, when you use view scope in an expression, it resolves to the Oracle ADF implementation.
request	Use request scope when the managed bean does not need to persist longer than the current request.
backingBean	A backing bean is a convention to describe a managed bean that stores accessors for UI components and event handling code on a JSF page. It exists for the duration of a request and should not be used to maintain state. Use this scope if it is possible that your task flow appears in two ADF regions on the same JSF page and you want to isolate each instance of ADF region.

When you define 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.

Note:

Write EL expressions that explicitly qualify the scope to access when writing EL expressions to access custom scopes unique to Oracle ADF (pageFlow, backingBean, and view scopes). For example, write an EL expression to access a pageFlow scope as follows:

#{pageFlowScope.inpTxtBB.uiComponent}

18.2.5 What Happens at Runtime: Using Task Flows

A single application can have multiple unbounded task flow XML source files and multiple bounded task flow XML source files. The set of files that combine to produce the unbounded task flow is referred to as the application's ADF Controller bootstrap configuration files. The 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 a bounded task flow are considered to be within the unbounded task flow.

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

Figure 18-12 Application with Two Unbounded Task Flow XML Source Files

Application with two unbounded task flow source files.

18.3 Adding Activities to a Task Flow

After you create a task flow, you add activities to the task flow and configure the control flow between the activities. The Component Palette in JDeveloper displays available activities and control flows. You drag and drop the activities and control flows from the Component Palette to the diagram for the task flow. You can then configure control flow between the activities so that the task flow performs the task you want it to perform.

18.3.1 How to Add an Activity to a 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.

Before you begin:

It may be helpful to have an understanding of what activities you can add to a task flow. For more information, see Section 18.3, "Adding Activities to a Task Flow."

You may also find it helpful to understand functionality that can be added to task flows using other ADF features. For more information, see Section 18.1.5, "Additional Functionality for ADF Task Flows."

To add an activity to a task flow:

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

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

Figure 18-13 Task Flow Diagram
In the ADF Task Flow page of the Component Palette, from the Component panel, drag and drop an activity onto the diagram
- If you drag a view activity onto the diagram, you can double-click it to display the wizard to create a JSF page or page fragment. For more information, see Section 19.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 19.6, "Using Task Flow Call Activities".

Tip:

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

18.3.2 What Happens When You Add an Activity to a Task Flow

As shown in Figure 18-14, 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 a bounded or the unbounded task flow. For example, if you are creating a bounded task flow, the Components section contains an additional task flow return activity.

Figure 18-14 displays the activities you can add to the unbounded task flow.

Figure 18-14 Component Palette for an Unbounded Task Flow

18.4 Adding Control Flow Rules to Task Flows

An ADF Controller control flow rule defines how control passes from one activity to another in a task flow. A control flow rule can contain one or more control flow cases. A control flow case identifies the activity to which control flow passes. A control case also has options that allow you to configure conditional navigation (using the <if> element) and/or limit navigation based on the value of the action from where the control flow originates (using the from-action element).

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 (view activity) to another task flow.

The following task flow activities cannot be the source of a control flow rule:

Save Point Restore
Task Flow Return
URL View

The basic structure of a control flow rule mimics a JSF navigation rule. Table 18-4 describes how metadata maps from JSF navigation rules to ADF Controller control flow rules.

Table 18-4 Mapping of JSF Navigation Rules to ADF Controller Control Flow Rules

JSF Navigation Rule	ADF Controller 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
If	If
To View ID	To Activity ID

When using ADF task flows, perform all application navigation using ADF Controller control flow rules instead of using JSF navigation rules in the faces-config.xml file. ADF Controller delegates navigation handling when it does not find a matching control flow case in its metadata. However, not all ADF Controller functionality is guaranteed to work correctly if navigation is performed by a non-ADF Controller navigation handler. For more information about how ADF Controller evaluates control flow rules, see Section 18.4.4, "What Happens at Runtime: Evaluating Control Flow Rules."

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.

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.

18.4.1 How to Add a Control Flow Rule to a Task Flow

You create a control flow rule by dragging a Control Flow Case from the ADF Task Flow page of the Component Palette and dropping it on a source task flow activity and a target task flow activity.

Before you begin:

It may be helpful to have an understanding of what a control flow rule is. For more information, see Section 18.4, "Adding Control Flow Rules to Task Flows."

You may also find it helpful to understand functionality that can be added using other task flow features. For more information, see Section 18.1.5, "Additional Functionality for ADF Task Flows."

To add a control flow rule to a task flow:

In the Application Navigator, double-click the source file for the task flow where you want to add a control flow rule. For example, adfc-config.xml.
In the ADF Task Flow page of the Component Palette, select Control Flow Case.
On the diagram, click a source task flow activity, for example a view activity, and then click the destination task flow activity.

Figure 18-15 shows two task flow activities (view1) and (view2) that have been linked with a control flow case.

Figure 18-15 Control Flow Case

JDeveloper adds the control flow case to the diagram. Each line that JDeveloper adds between task flow activities represents a control flow case. The arrow indicates the direction of the control flow case. The From Outcome element contains a value that can be matched against values specified in the action attribute of UI components.
To change the value of 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 18-15. You can overwrite the text with a new value, for example, toView2.
To change the values of 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.

Tip:

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 editor for the task flow diagram to add cases, as shown in Figure 18-16. 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 18-16 Control Flows on Overview Editor for the Task Flow
Optionally, in the Property Inspector expand the Behavior section, and write an EL expression in the If field that must evaluate to true before control can pass to the activity identified by To Activity ID.

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

Before you begin:

It may be helpful to have an understanding of the control flow rule options available to you. For more information, see Section 18.4, "Adding Control Flow Rules to Task Flows."

You may also find it helpful to understand functionality that can be added using other task flow features. For more information, see Section 18.1.5, "Additional Functionality for ADF Task Flows."

To add a wildcard control flow rule:

In the Application Navigator, double-click the source file for a task flow to display the task flow diagram. For example, double-click adfc-config.xml.
In the ADF Task Flow page of the Component Palette, from the Component panel, drag and drop a Wildcard Control Flow Rule onto the diagram.
Select Control Flow Case in 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 *. This is the value for the From Activity ID element. 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.
Optionally, in the Property Inspector expand the Behavior section, and write an EL expression in the If field that must evaluate to true before control can pass to the activity identified by To Activity ID.

18.4.3 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 task flow diagram, task flow overview editor, or Structure window, or when adding them directly in the XML source file. Example 18-4 shows the general syntax of a control flow rule element in the task flow source file.

Example 18-4 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>
    <if>#{myBean.someCondition}</if>
  </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 18.4.2, "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 18-4, 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.
if: An optional element that accepts an EL expression as a value. If the EL expression evaluates to true at runtime, control flow passes to the activity identified by the to-activity-id element.

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

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 allows the standard JSF navigation handler to find a match.

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

ADF Controller also implements the following interface with a number of restrictions:

javax.faces.application.ConfigurableNavigationHandler

The restrictions are:

The Map object returned by getNavigationCases() is not modifiable. Any runtime changes to control flow rules must be made with the customization features provided with the MDS framework. For more information, see Chapter 39, "Customizing Applications with MDS."
Do not invoke the performNavigation() method after the JSF Invoke Application phase. This is to make sure that the view ID does not change between the ADF Prepare Render phase and the JSF Render Response phase. For more information about how the JSF and ADF phases integrate in the lifecycle of a page request, see Chapter 25, "Understanding the Fusion Page Lifecycle."
The metadata values for a task flow view activity's bookmark and redirect properties populate the corresponding information for the navigation case objects returned by the getNavigationCases().

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

JDeveloper and Oracle ADF provides a number of features that facilitate your testing of the task flows that you create. Among these is the ability to set ADF declarative breakpoints on task flow activities. For more information, see Section 36.9.1, "How to Set and Use Task Flow Activity Breakpoints." In addition, you can also modify a task flow's metadata for an application that is currently executing in the Integrated WebLogic Server. The changes that you make to the task flow can be deployed to the application without stopping the application and redeploying it to the Integrated WebLogic Server (also known as hot reloading). To do this, you invoke the make command on the modified task flow (right-click the task flow and select Make from the context menu that appears). This deploys the modified task flow to the application executing in the Integrated WebLogic Server. For more information about hot reloading, see the Section 36.4, "Reloading Oracle ADF Metadata in Integrated WebLogic Server."

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

18.5.1 How to Run a Bounded Task Flow That Contains Pages

You can run or debug a 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 18.5.2, "How to Run a Bounded Task Flow That Uses Page Fragments".

Note:

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

In a bounded task flow, you must designate the view as a default activity and run the task flow from the Application Navigator. For more information, see Section 18.2.3, "What You May Need to Know About the Default Activity in a Bounded Task Flow".

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

Before you begin:

It may be helpful to have an understanding of the factors that affect how you test a task flow. For more information, see Section 18.5, "Testing Task Flows."

You may also find it helpful to understand functionality that can be added using other task flow features. For more information, see Section 18.1.5, "Additional Functionality for ADF Task Flows."

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://somecompany.com/internalApp/MyApp/faces/adf.task-flow?adf.tfId=displayHelp&adf.tfDoc=%2FWEB-INF%2Fdisplayhelp.xml&topic=createPurchaseOrder

For more information, see Section 19.6.6, "What You May Need to Know About Calling a Bounded Task Flow Using a URL."
You can right-click the bounded task flow in the Application Navigator and choose either Run or Debug.

18.5.2 How to Run a Bounded Task Flow That Uses Page Fragments

Bounded task flows that use page fragments are intended to run only within an ADF region. A page fragment is a JSF document that renders as content in another JSF page. For more information, see Section 21.1.1, "About Page Fragments and ADF Regions".

Before you begin:

It may help to understand what factors affect how you test a task flow. For more information, see Section 18.5, "Testing Task Flows."

You may also find it helpful to understand functionality that can be added using other task flow features. For more information, see Section 18.1.5, "Additional Functionality for ADF Task Flows."

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

If you have not done so already, create a JSF page containing a region that binds to the bounded task flow. JDeveloper automatically creates the region for you in a JSF page when you drop a bounded task flow containing page fragments on a page. For more information about creating regions, see Section 21.2, "Creating an ADF Region."
Create a view activity in the project's unbounded task flow that refers to the page. See Section 18.3.1, "How to Add an Activity to a Task Flow" for more information.
Right-click the view activity in the Application Navigator or in the task flow diagram and choose Run.

18.5.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 20, "Using Parameters in Task Flows".

Before you begin:

It may be helpful to have an understanding of the factors that affect how you test a task flow. For more information, see Section 18.5, "Testing Task Flows."

You may also find it helpful to understand functionality that can be added using other task flow features. For more information, see Section 18.1.5, "Additional Functionality for ADF Task Flows."

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

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

Figure 18-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 18-17. You must specify the parameter value as a literal string. You cannot specify an EL expression.
Click OK.

18.5.4 How to Run a JSF Page When Testing a Task Flow

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.

Before you begin:

It may be helpful to have an understanding of the factors that affect how you test a task flow. For more information, see Section 18.5, "Testing Task Flows."

You may also find it helpful to understand functionality that can be added using other task flow features. For more information, see Section 18.1.5, "Additional Functionality for ADF Task Flows."

To run a JSF Page with fully functioning navigation:

Create a bounded or unbounded task flow. See Section 18.2.1, "How to Create a Task Flow" for more information.
Add a view activity to the task flow. See Section 18.3.1, "How to Add an Activity to a 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.

18.5.5 How to Run the Unbounded Task Flow

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

Before you begin:

It may be helpful to have an understanding of the factors that affect how you test a task flow. For more information, see Section 18.5, "Testing Task Flows."

You may also find it helpful to understand functionality that can be added using other task flow features. For more information, see Section 18.1.5, "Additional Functionality for ADF Task Flows."

To run a view activity in the 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.

18.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 ADF Controller source file as the default run target. When you run the project, the source file is the first to run.

Before you begin:

It may be helpful to have an understanding of the factors that affect how you test a task flow. For more information, see Section 18.5, "Testing Task Flows."

You may also find it helpful to understand functionality that can be added using other task flow features. For more information, see Section 18.1.5, "Additional Functionality for ADF Task Flows."

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 dialog, 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 Settings From dropdown list.
Click OK to exit the dialog.
Click Edit.
In the Default Run Target field in the Edit Run Configuration dialog, specify a source file for the task flow that should run first when you run the project.

Once you choose a task flow, you can set a view activity (for the unbounded task flow) or input parameters (for bounded task flows).
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 task flow containing the run target.
If you are running the 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 Section 18.5.3, "How to Run a Bounded Task Flow That Has Parameters" for more information.

18.6 Refactoring to Create New Task Flows and Task Flow Templates

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

18.6.1 How to Create a Bounded Task Flow from Selected Activities

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

Before you begin:

It may be helpful to have an understanding of the factors that affect how you refactor a task flow. For more information, see Section 18.6, "Refactoring to Create New Task Flows and Task Flow Templates."

You may also find it helpful to understand functionality that can be added using other task flow features. For more information, see Section 18.1.5, "Additional Functionality for ADF Task Flows."

To create a new bounded task flow from selected activities:

In the Application Navigator, double-click the source file for the unbounded or bounded task flow containing the activities you want to extract to a new bounded 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 from the context menu that appears.

The Extract Bounded Task Flow dialog displays. This dialog allows you to specify the file name and directory location for the new bounded task flow. For more information, see Section 18.2, "Creating a Task Flow".

The new bounded task flow displays in the task flow diagram. Table 18-5 describes the properties that JDeveloper automatically sets for the new bounded task flow.

Table 18-5 Properties Updated in the New Bounded Task Flow

Property	Value
Task flow definition ID	Value you entered in the File Name field in the Extract Bounded 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 bounded task. A source activity is an activity from which a control flow leads. The new 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 File Name field in the Extract Bounded 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 bounded task. A source activity is an activity from which a control flow leads. The new 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 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.

18.6.2 How to Create a Task Flow from JSF Pages

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

Before you begin:

You may also find it helpful to understand functionality that can be added using other task flow features. For more information, see Section 18.1.5, "Additional Functionality for ADF Task Flows."

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

In the Application Navigator, double-click the source file for 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 unbounded or bounded task flow. For more information, see Section 18.2, "Creating a Task Flow".

18.6.3 How to Convert Bounded Task Flows

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

Table 18-6 Converting Bounded Task Flows

Conversion	Result
Bounded task flow to unbounded task flow	Loses all metadata not valid for unbounded task flows, such as parameter definitions and transactions.
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.
Bounded task flow to use page fragments	Converts all pages associated with view activities in the 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

Before you begin:

You may also find it helpful to understand functionality that can be added using other task flow features. For more information, see Section 18.1.5, "Additional Functionality for ADF Task Flows."

To convert a bounded task flow:

In the Application Navigator, double-click the source file for the bounded task flow that you want to convert.
In the task flow diagram, right-click anywhere other than on an activity or control flow.
Choose the appropriate menu option:
- Convert to Unbounded Task Flow
- Convert to Task Flow with Page Fragments
- Convert to Task Flow with Pages

18.7 What You Should Know About Task Flow Constraints

Table 18-7 summarizes assumptions about and constraints for using task flows, activities, and other associated ADF Controller features.

Table 18-7 ADF Controller Features Assumptions and Constraints

Feature Area	Assumption/ Constraint	Description
ADF Controller objects and diagram UI	JSF view layer	ADF Controller operates in a JSF 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 18.6.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`.