Fusion Middleware Documentation
Advanced Search


Developing Fusion Web Applications with Oracle Application Development Framework
Close Window

Table of Contents

Show All | Collapse

20 Getting Started with ADF Task Flows

This chapter describes getting started with ADF tasks flows that you can create in your Fusion web application. In addition to describing how to create ADF task flows, key ADF task flow features such as activities, control flows, control flow rules, memory scopes, and bounded and unbounded task flows are described. The chapter also describes how to refactor, test, and run a finished task flow.

This chapter includes the following sections:

20.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 20-1 shows two view activities called Create and Confirm. These view activities are similar to page nodes within a JSF page flow.

Figure 20-1 ADF Task Flow

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 21, "Working with Task Flow Activities."

    By default, JDeveloper proposes the following file name 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 file name 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 to 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, it makes the modification of bounded task flows easier if you do not 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 20-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 20-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 20-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 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 20-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 27.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 20-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 21.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 44, "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.


20.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 20-3 displays the diagram for an unbounded task flow from an application. This task flow contains a number of view activities that are all entry points to the application.

Figure 20-3 Unbounded Task Flow

Unbounded Task Flow

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 21.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 20-3, the task flow can be entered through any of the pages represented by the view activity icons on the unbounded task flow.

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.

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

The createOrder activity in Figure 20-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.

Figure 20-4 shows a bounded task flow.

Figure 20-4 Bounded Task Flow

Bounded Task Flow

The reasons for creating a 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 Figure 20-4, this is the method call activity labeled reconcileOrders. Because it is the default activity, the method call activity is always invoked before the bounded task flow renders the page referenced by the order view activity.

  • It is reusable. For example, it can be included in other applications requiring a process to manage or check out orders. The bounded task flow can also be reused within the same application.

  • Any managed beans you use within a bounded 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.

Table 20-2 summarizes the main features of a bounded task flows.

Table 20-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 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 20.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 20.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 21.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.

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 24.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 22.3, "Passing Parameters to a Bounded Task Flow."

In addition, you can share data controls between bounded task flows. For more information, see Section 24.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 24.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 24.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 41, "Enabling ADF Security in a Fusion Web Application."


Understanding the assumptions and constraints listed in Table 20-3 will help you successfully use ADF task flows, activities and other associated ADF Controller features.

Table 20-3 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 ADF Controller.

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


20.1.3 About Control Flows

A task flow consists of activities and control flow cases that define the transitions between activities. Figure 20-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 20-5 executes.

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

Task flow with activities and control flow rules.

The task flow in Figure 20-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 do not require the method (for example, a different task flow). For more information about control flow rules, see Section 20.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 20-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 20-6 Wildcard Control Flow Rule With Single Wildcard

Wildcard Control Flow Rule With Single Wildcard

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

Figure 20-7 Wildcard Control Flow Rule with Trailing Wildcard

Wildcard Control Flow Rule with Trailing Wildcard

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

20.1.4 ADF Task Flow Use Cases and Examples

Figure 20-8 shows a screen from the Summit sample application for ADF task flows. End users of the screen invoke a task flow that displays a list of customers. Using controls exposed on the screen, end users can also invoke a task flow that allows them to create or to edit an order.

Figure 20-8 Task Flows for Creating and Editing Data

Task Flows for Creating and Editing Data

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 21.6.4, "How to Call a Bounded Task Flow Using a URL." For more information about securing your Fusion web application, see Chapter 41, "Enabling ADF Security in a Fusion Web Application."

20.1.5 Additional Functionality for ADF Task Flows

You may find it helpful to understand other Oracle 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.

20.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 activities of a task flow, including the metadata created for each activity and additional configuration that you can set, see Section 20.3, "Adding Activities to a Task Flow."

20.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 a project, you may not need to create the unbounded task flow for it. If ADF Page Flow is specified as a selected technology on the Features page of the Project Properties dialog, the new adfc-config.xml file is automatically created within the project. The adfc-config.xml 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 20.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 20.1.5, "Additional Functionality for ADF Task Flows."

To create a task flow:

  1. In the Applications window, right-click the project in which you want to create the task flow and choose New > ADF Task Flow.

  2. In the Create Task Flow dialog, the Create as Bounded Task Flow checkbox is selected by default. Deselect it if you want to create 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 create. 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.

  3. In the Create Task Flow dialog, the Create with Page Fragments checkbox is selected by default.

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

  4. Click OK.

    A diagram representing the task flow appears in the editor.

    Tip:

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

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

  5. In the ADF Task Flow page of the Components window, from the Component panel, in the Activities group, 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 20.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 21.2, "Using View Activities."

      Note:

      You can also add a view activity to a task flow by dragging a page from the Applications window and dropping it on the diagram for the task flow.

    • If you drag a router activity onto the diagram, you can use the Properties window to create an expression whose evaluation determines which control flow rule to follow. For more information, see Section 21.4, "Using Router Activities."

    • If you drag a method call activity onto the diagram, you can use the Properties window to configure the method to call. For more information, see Section 21.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 21.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 Properties window to configure the activity. For more information, see Section 21.7, "Using Task Flow Return Activities."

  6. Create control flow cases between the activities (for more information and detailed procedures, see Section 20.4.1, "How to Add a Control Flow Rule to a Task Flow"):

    1. In the ADF Task Flow page of the Components window, from the Component panel, in the Control Flow group, choose 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 20-14, two activities have been linked with a control flow. Both the source (view1) and the destination (view2) activities are linked.

    3. In the Properties window, expand the General section, and choose the outcome value using either the From Action attribute (if a method determines the outcome) or the From Outcome attribute (if the outcome can be set as a String).

  7. If you are creating a bounded task flow, you may want to designate one of the activities as the default activity. This makes sure that this specific activity executes first whenever the bounded task flow runs. By default, JDeveloper makes the first activity you add to the task flow 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 20.2.3, "What You May Need to Know About the Default Activity in a Bounded Task Flow."

20.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 20-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 20-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 20-2 shows a sample task flow reference within a task flow call activity.

Example 20-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 20-2, the identifier is the value in the Task Flow ID field. The document name is the value in the File Name field.

20.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 20-9, a green circle identifies the default activity in a task flow diagram.

Figure 20-9 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 24.8, "Using Train Components in Bounded Task Flows."

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

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

20.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 20-10 shows an example from the Summit ADF task flow sample application where a bounded task flow (customers-task-flow-definition.xml) references a managed bean with a backingBean scope. You can determine the scope assigned to a managed bean.

Figure 20-10 Managed Bean Registered With Task Flow

Managed Bean Registered With Task Flow

Table 20-4 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 about the life span of object scopes, see Section 27.3, "About Object Scope Lifecycles."

Table 20-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. 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 EL 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.

In scenarios where you have more than one task flow, consider using a naming convention that assigns a unique name to each managed bean. Adopting this approach makes sure that you do not attempt to put two managed beans with the same name from different task flows into backingBean scope.


When you define a managed bean with a task flow, JDeveloper generates entries 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}

20.2.5 What You May Need to Know About the Source Files for 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 20-11 contains two unbounded task flows (adfc-config, adfc-config1) and a bounded task flow (task-flow-definition).

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

Application with two unbounded task flow source files.

20.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 Components window displays available activities and control flows. You drag and drop the activities and control flows from the Components window to the diagram for the task flow. You then configure control flow between the activities so that the task flow performs the task you want it to perform.

20.3.1 How to Add an Activity to a Task Flow

After you create a task flow, a task flow diagram and the Components window 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 Components window.

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 20.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 Oracle ADF features. For more information, see Section 20.1.5, "Additional Functionality for ADF Task Flows."

To add an activity to a task flow:

  1. In the Applications window, expand the WEB-INF node and double-click the task flow to which you want to add an activity.

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

    Figure 20-12 Task Flow Diagram

    Task Flow Diagram
  2. In the ADF Task Flow page of the Components window, from the Component panel, in the Activities group, 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 21.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 21.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, choose Show at the top of the task flow diagram, and then choose 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 there is a problem in the task flow metadata that does not prevent the task flow from running.

  • Incomplete: Displays when an activity is incomplete. For example, a view activity that does not have a physical page associated with it or a task flow call that does not 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.

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

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

Figure 20-13 displays the activities you can add to an unbounded task flow.

Figure 20-13 Activities for an Unbounded Task Flow

Activities for an Unbounded Task Flow

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

An ADF Controller 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 20-5 describes how metadata maps from JSF navigation rules to ADF Controller control flow rules.

Table 20-5 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 20.4.4, "What Happens at Runtime: How Task Flows Evaluate 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, Properties window 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.

20.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 Components window 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 20.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 20.1.5, "Additional Functionality for ADF Task Flows."

To add a control flow rule to a task flow:

  1. In the Applications window, expand the WEB-INF node and double-click the task flow where you want to add a control flow rule.

  2. In the ADF Task Flow page of the Components window, from the Component Panel, in the Control Flow group, select Control Flow Case.

  3. On the diagram, click a source task flow activity and then click the destination task flow activity.

    In many cases, the source and destination task flow activities will be view activities. In Figure 20-14, two such task flow activities (view1) and (view2) have been linked with a control flow case.

    Figure 20-14 Control Flow Case

    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.

  4. To change the value of From Outcome, choose the text next to the control flow in the diagram and overwrite the default wildcard * character.

    A useful convention is to cast the control flow rule in the form toDestination or some other form that describes the purpose of the control flow rule. To define the control flow shown in Figure 20-14, for instance, you would overwrite the wildcard with toView2.

  5. To change the values of From Activity ID (which identifies the source activity) or To Activity ID (which identifies the target activity), drag either end of the arrow in the diagram to a new activity.

    Tip:

    After you choose the control flow in the task flow diagram, you can also change its properties in the Properties window 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 20-15. 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 20-15 Control Flows on Overview Editor for the Task Flow

    Control Flows on Overview tab.
  6. Optionally, in the Properties window 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.

20.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 20.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 20.1.5, "Additional Functionality for ADF Task Flows."

To add a wildcard control flow rule:

  1. In the Applications window, expand the WEB-INF node and double-click the task flow where you want to add a wildcard control flow rule.

  2. In the ADF Task Flow page of the Components window, from the Component panel, in the Control Flow group, drag and drop a Wildcard Control Flow Rule onto the diagram.

  3. In the ADF Task Flow page of the Components window, from the Component panel, in the Control Flow group, select Control Flow Case.

  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 *. 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 Properties window for the wildcard control flow rule, enter a new value in the From Activity ID field. A useful convention is to cast the wildcard control flow rule in a form that describes its purpose. 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.

  6. Optionally, in the Properties window 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.

20.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 20-4 shows the general syntax of a control flow rule element in the task flow source file.

Example 20-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 applies 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 20.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 20-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.

20.4.4 What Happens at Runtime: How Task Flows Evaluate Control Flow Rules

At runtime, task flows evaluate 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 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 45, "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 27, "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().

20.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 42.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 choose Make). This deploys the modified task flow to the application executing in the Integrated WebLogic Server. For more information about hot reloading, see Section 42.4, "Reloading Oracle ADF Metadata in Integrated WebLogic Server."

The Configure Default Domain dialog appears 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.

20.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 20.5.2, "How to Run a Bounded Task Flow That Uses Page Fragments."

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 20.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 20.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 21.6.6, "What You May Need to Know About Calling a Bounded Task Flow Using a URL."

  • In the Applications window, expand the WEB-INF node, right-click the bounded task flow and choose either Run or Debug.

20.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 23.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 20.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 20.1.5, "Additional Functionality for ADF Task Flows."

You will need to complete these tasks:

  1. 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 23.2, "Creating an ADF Region."

  2. Create a view activity in the project's unbounded task flow that refers to the page. For more information, see Section 20.3.1, "How to Add an Activity to a Task Flow."

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

  • Right-click the view activity in the Applications window or in the task flow diagram and choose Run.

20.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, see Section 20.5.2, "How to Run a Bounded Task Flow That Uses Page Fragments."

When you attempt to run or debug a bounded task flow with input parameters defined, the Set Run Configuration dialog appears, as shown in Figure 20-16. You enter values that you want to pass to the bounded task flow in this dialog and click OK. For more information about how to define input parameters for a bounded task flow, see Chapter 22, "Using Parameters in Task Flows."

Figure 20-16 Set Run Configuration dialog

Set Run Configuration dialog.

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 20.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 20.1.5, "Additional Functionality for ADF Task Flows."

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

  1. In the diagram for the bounded task flow, right-click the task flow and choose either Run or Debug.

  2. In the Input Parameters list of the Set Run Configuration dialog, 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 appears with an asterisk, as shown in Figure 20-16. You must specify the parameter value as a literal string. You cannot specify an EL expression.

  3. Click OK.

20.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 Applications window 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 20.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 20.1.5, "Additional Functionality for ADF Task Flows."

You will need to complete these tasks:

  1. Create a bounded or unbounded task flow.

    For more information, see Section 20.2.1, "How to Create a Task Flow."

  2. Add a view activity to the task flow.

    For more information, see Section 20.3.1, "How to Add an Activity to a Task Flow."

To run a JSF Page with fully functioning navigation:

  1. In the Applications window, drag the JSF page you want to run and drop it onto the view activity in the task flow diagram.

    This associates the view activity with the JSF page.

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

20.5.5 How to Run an Unbounded Task Flow

To run or debug an unbounded task flow, you choose 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 20.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 20.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 choose one in the Set Run Configuration dialog.

20.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 20.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 20.1.5, "Additional Functionality for ADF Task Flows."

To define a default task flow run target:

  1. In the Applications window, right-click the project where you want to define a default task flow run target and choose Project Properties.

  2. In the Project Properties dialog, select Run/Debug and click New in the Run Configurations list.

  3. In the Create Run Configuration dialog, enter the name for the new run configuration.

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

  5. Click OK to exit the Create Run Configuration dialog.

  6. In the Run Configurations list, click Edit.

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

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

  9. In the Task Flow dropdown list, located on the right panel, choose the task flow containing the run target.

  10. If you are running the unbounded task flow, the Edit Run Configuration dialog displays the View Activity dropdown list where you choose the view activity that runs first in the application, as shown in Figure 20-17.

    Figure 20-17 Edit Run Configuration Dialog

    Edit Run Configuration Dialog
  11. Click OK.

    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 displays a section for specifying values for all input parameters defined for the bounded task flow. For more information, see Section 20.5.3, "How to Run a Bounded Task Flow That Has Parameters."

20.5.7 What Happens at Runtime: Testing Task Flows

The behavior that you observe when you test a task flow may depend on a number of factors. For example, if you attempt to run or debug a bounded task flow with input parameters defined, the Set Run Configuration dialog appears. Also, if it is the first time that you attempt to test an application in this installation of JDeveloper, the Configure Default Domain dialog appears so that you can start a new domain in Integrated WebLogic Server.

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

20.6.1 How to Extract a Bounded Task Flow from an Existing Task Flow

You can create a new bounded task flow based on activities you choose 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 20.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 20.1.5, "Additional Functionality for ADF Task Flows."

To extract a bounded task flow from an existing task flow:

  1. In the Applications window, expand the WEB-INF node and double-click the unbounded or bounded task flow containing the activities you want to extract to a new bounded 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.

  4. In the Extract Bounded Task Flow dialog, enter a file name for the new bounded task flow and enter the name of the directory that stores it.

    For more information about creating a bounded task flow, see Section 20.2, "Creating a Task Flow."

20.6.2 What Happens When You Extract a Bounded Task from an Existing Task Flow

The new bounded task flow that you extract displays in the task flow diagram. Table 20-6 describes the properties that JDeveloper automatically sets for the new bounded task flow.

Table 20-6 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.


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.

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

It may be helpful to have an understanding of the factors that affect how you refactor a task flow. For more information, see Section 20.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 20.1.5, "Additional Functionality for ADF Task Flows."

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

  1. In the Applications window, double-click 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 appears, which allows you to create a new unbounded or bounded task flow.

  4. In the Create Task Flow dialog, enter a file name and directory for the task flow. Clear the Create as Bounded Task checkbox if you want to create an unbounded task flow.

    For more information, see Section 20.2, "Creating a Task Flow."

  5. Click OK.

20.6.4 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 20-7 describes the results of each conversion.

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

It may be helpful to have an understanding of the factors that affect how you refactor a task flow. For more information, see Section 20.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 20.1.5, "Additional Functionality for ADF Task Flows."

To convert a bounded task flow:

  1. In the Applications window, expand the WEB-INF node and double-click the bounded task flow that you want to convert.

  2. In the task flow diagram, right-click anywhere other than on an activity or a control flow.

  3. Choose the appropriate menu option:

    • Convert to Unbounded Task Flow

    • Convert to Task Flow with Page Fragments

    • Convert to Task Flow with Pages