Skip Headers
Oracle® Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework
11g Release 1 (11.1.1.7.0)

Part Number B31974-12
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

14 Getting Started with ADF Task Flows

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

This chapter includes the following sections:

14.1 Introduction to ADF Task Flows

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

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

Figure 14-1 ADF Task Flow

Simple ADF Task Flow.

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 14.2.4, "What You May Need to Know About Memory Scope for Task Flows" and Section 20.4, "Using a Managed Bean in a Fusion Web Application".

14.1.1 Task Flow Advantages

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

Table 14-1 ADF Task Flow Advantages

JSF Page Flow ADF Task Flow

The entire application must be represented 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 15.4, "Using Router Activities".

Application fragments cannot be reused.

ADF task flows are reusable within the same or an entirely different application.

After you break up your application into task flows, you may decide to reuse task flows containing common functionality.

For more information see Chapter 33, "Reusing Application Components".

There is no shared memory scope between multiple requests except for session scope.

Shared memory scope (for example, page flow scope) enables data to be passed between activities within the task flow. Page flow scope defines a unique storage area for each instance of an ADF bounded task flow.


14.1.2 Task Flow Types

The two types of ADF task flow are:

  • Unbounded task flow: A set of activities, control flow rules, and managed beans that interact to allow a user to complete a task. An ADF unbounded task flow consists of all activities and control flows in an application that are not included within any bounded task flow.

  • 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

Unbounded 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

Unbounded Task Flow in Fusion Order Demo

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:

    Page image in view activity icon

  • 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

Checkout bounded task flow

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.12, "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 18.3, "Sharing Data Controls Between Task Flows."

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.4, "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.5, "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

Task flow with activities and control flow rules.

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.

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

JSF Navigation Rule Control Flow Rule

Navigation Rule

Control Flow Rule

From View ID

From Activity ID

Navigation Case

Control Flow Case

From Action

From Action

From Outcome

From Outcome

To View ID

To Activity ID


Note:

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

A wildcard control flow rule represents a control 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

Wildcard control flow rule

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

Trailing wildcard

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

Note:

If your application uses Facelets XHTML files in the view layer, you manually configure navigation in a task flow's source file between the view activities that reference these Facelets XHTML files.

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 14.3, "Adding Activities to a Task Flow."

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.

Note:

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

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

      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.

Example 14-1 ADF 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>

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.

Example 14-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 ADF 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 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

Default activity in unbounded task flow.

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

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

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

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

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

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

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.

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

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.If another task flow's page references the managed bean, the managed bean creates a separate instance of this object and adds it to the pageFlow scope of its task flow.

view

Use this scope for managed bean objects that are needed only within the current view activity and not across view activities. It defines scope for each view port that ADF Controller manages, for example, a root browser window or an ADF region.

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.

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

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}

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

Application with two unbounded task flow source files.

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

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

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

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.

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

Component Palette for an unbounded task flow.

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.

Tip:

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

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

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

Multiple control flow cases from one activity.

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

Example 14-4 Control Flow Rule Metadata Within a Bounded Task Flow

<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

    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.

Tips:

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

You can also click Control Flows on the overview editor for the task flow diagram to add cases, as shown in Figure 14-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 14-16 Control Flows on Overview Editor for the Task Flow

Control Flows on Overview tab.

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.

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

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

Control flow rules can consist of the following metadata:

  • control-flow-rule: A mandatory wrapper element for control flow case elements.

  • from-activity-id: The identifier of the activity where the control flow rule originates, for example, source.

    A trailing wildcard (*) character in from-activity-id is supported. The rule will apply to all activities that match the wildcard pattern. For example, login* matches any logical activity ID name beginning with the literal login. If you specify a single wildcard character in the metadata (not a trailing wildcard), the control flow automatically converts to a wildcard control flow rule activity in the diagram. For more information, see Section 14.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 Testing ADF Task Flows

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

The Configure Default Domain dialog displays the first time you run the 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.

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

Note:

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

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

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

To run or debug a 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

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

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

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

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

Property Value

Task flow definition ID

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

Default activity

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

Control flow rules

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

  • Both the source and target activities in the control flow case were selected to create the new task flow.

  • Only the source activity was selected to create the new task flow. Destinations are changed to the corresponding new task flow return activities added for each outcome.


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

  • A new task flow call activity is added to the originating task flow. The task flow call activity calls the new ADF bounded task flow.

  • The selected activities are removed from the originating task flow.

  • Existing control flow cases associated with the activities you selected are removed from the originating task flow. They are replaced with new control flow cases:

    • An incoming control flow case to the old activity is redirected to the new task flow call activity.

    • An outgoing control flow case from the old activity is redirected from the new task flow call activity.

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

Table 14-6 Converting ADF Bounded Task Flows

Conversion Result

ADF bounded task flow to unbounded task flow

Loses all metadata not valid for unbounded task flows, such as parameter definitions and transactions.

ADF bounded task flow to use JSF pages

Converts page fragments associated with any view activities in the task flow to JSF pages. Old page fragments are saved if you select the Keep Page Fragment checkbox. New JSF page names default to the name of the old page fragment.

ADF bounded task flow to use page fragments

Converts all pages associated with view activities in the ADF bounded task flow to page fragments. Old pages are saved if you select the Keep Page checkbox. New page fragment names default to the name of the old page


To convert an ADF bounded task flow:

  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.

14.6 What You Should Know About Task Flow Constraints

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

Table 14-7 ADF Controller Features Assumptions and Constraints

Feature Area Assumption/
Constraint
Description

ADF Controller objects and diagram UI

JSF view layer

ADF Controller operates only in a JSF 1.2 environment. Oracle's web-based Fusion web application strategy focuses on JSF as the sole view layer technology.

 

Dependent on ADF Faces

ADF Controller extensions are implemented on top of ADF Faces. They are dependent on the ADF Faces libraries, but ADF Controller can run against any JSF implementation, providing these libraries are present.

 

Navigation and state management encapsulated

ADF Controller encapsulates both navigation and, to some extent, state management. JSF and the Servlet API are still available for the basic management of state at the application, session, and request levels.

 

Model layer

ADF model layer is used to implement the application's model layer.

 

Dependent on MDS

ADF Controller metadata is stored in MDS. However, MDS is currently not capable of loading faces-config.xml.

If the customization features that MDS provides are required, you should use ADF task flows exclusively in order to define managed beans and control flow rules.

 

No supported migration path from struts or model 1

There is no support for a migration from Struts or Model 1 to the Fusion ADF Controller.

However, you can create a new ADF bounded task flow based on selected pages in a JSF page flow. For more information, see Section 14.5.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.