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

Part Number E16182-01
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

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

19 Working with Task Flow Activities

This chapter describes how to use activities in your task flows. The chapter contains detailed information about each task flow activity that displays in the Component Palette and its properties.

This chapter includes the following sections:

19.1 About Task Flow Activities

An activity represents a piece of work that is performed when the task flow runs. It displays in the task flow's diagram editor as a node. You can add most activities to both bounded and unbounded task flows, although some activity types can be added only to a bounded task flow.

The bounded task flow shown in Figure 19-1 contains activities that run in order to check out a user from the shopping application:

  1. A call to a method synchronizes the items a user may have chosen before logging in with those selected after logging in

  2. A page (view activity) that displays the items the user has currently selected and another page that summarizes the order

  3. An activity that causes control to return back to the calling unbounded task flow shown in Figure 19-1

Figure 19-1 Checkout Bounded Task Flow in Fusion Order Demo Application

Checkout bounded task flow.

A task flow consists of activities and control flow cases that define the transitions between activities. Table 19-1 describes the types of activities and control flows you can add to a task flow by dragging and dropping from the Component Palette.

Table 19-1 Task Flow Activities and Control Flows

Icon Component Name Description
Method call activity.

Method Call

Invokes a method, typically a method on a managed bean. A method call activity can be placed anywhere within an application's control flow to invoke application logic based on control flow rules. See Section 19.5, "Using Method Call Activities" for more information.

Wildcard control flow rule.

Parent Action

Allows a bounded task flow to generate outcomes that are passed to its parent view activity. See Section 19.9, "Using Parent Action Activities" for more information.

Router activity.

Router

Evaluates an EL expression and returns an outcome based on the value of the expression. For example, a router in a credit check task flow might evaluate the return value from a previous method call and generate success, failure, or retry outcomes based on various cases. These outcomes can then be used to route control to other activities in the task flow. See Section 19.4, "Using Router Activities" for more information.

Save Point Restore activity.

Save Point Restore

Restores a previous persistent save point, including application state and data, in an application supporting save for later functionality. See Section 22.6, "Using Save Points in Task Flows" for more information.

Task flow call activity.

Task Flow Call

Calls a bounded task flow from the unbounded task flow or another bounded task flow. See Section 19.6, "Using Task Flow Call Activities" for more information.

Task flow return activity.

Task Flow Return

Identifies when a bounded task flow completes and sends control flow back to the caller. (Available for bounded task flows only). See Section 19.7, "Using Task Flow Return Activities" for more information.

URL view activity.

URL View

Redirects the root view port (for example, a browser page) to any URL-addressable resource, even from within the context of an ADF region. See Section 19.3, "Using URL View Activities" for more information.

View activity.

View

Displays a JSF page or page fragment. Multiple view activities can represent the same page or same page fragment. See Section 19.2, "Using View Activities" for more information. See Section 24.3, "Creating a Web Page" for more information about pages and page fragments.

Control flow case.

Control Flow Case

Identifies how control passes from one activity to the next in the application. See Section 18.1.3, "About Control Flows" for more information.

Wildcard control flow rule.

Wildcard Control Flow Rule

Represents a control flow case that can originate from any activities whose IDs match a wildcard expression. For example, it can represent a control case from-activity-id containing a trailing wildcard such as foo*. See Section 18.4.2, "How to Add a Wildcard Control Flow Rule" for more information.


Table 19-2 describes the annotations (notes and attachments) you can add to a task flow.

Table 19-2 Task Flow Diagram Annotations

Icon Icon Name Description

Note.

Note

Adds a note to the task flow diagram. You can select the note in the diagram to add or edit text.

Note attachment.

Note Attachment

Attaches an existing note to an activity or a control flow case in the diagram.


19.1.1 Task Flow Activities Use Cases and Examples

Figure 19-2 shows the diagram for the customer registration task flow in the Fusion Order Demo application. This task flow uses many of the activities that a bounded task flow supports in order to register a customer. For more information about the Fusion Order Demo application, see Chapter 2, "Introduction to the ADF Sample Application."

Figure 19-2 Customer Registration Task Flow

Customer Registration Task Flow

19.1.2 Additional Functionality for Task Flow Activities

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

19.2 Using View Activities

One of the primary types of task flow activity is the view activity. A view activity displays a JSF page or page fragment. A page fragment is a JSF document that renders as content in another JSF page. Page fragments are typically used in bounded task flows that can be added to a JSF page as a region, as described in Section 21.2, "Creating an ADF Region."

Figure 19-3 shows the home view activity in the Fusion Order Demo application.

Figure 19-3 View Activity

A view activity in a task flow.

Tip:

Click the + icon in the upper-left part of the view activity to see a thumbnail preview of the referenced page or page fragment.

XML metadata in the source file of the task flow associates a view activity with a physical JSF page or page fragment. An id attribute identifies the view activity. The <page> element identifies the page or page fragment's file name. Example 19-1 shows the metadata that corresponds to the view activity in Figure 19-3:

Example 19-1 Metadata for a View Activity

<view id="home">
   <page>/home.jspx</page>
 </view>

The view activity ID and page name do not have to be the same.

The steps for adding a view activity to a task flow are the same as those for adding any activity to a task flow diagram. For more information, see Section 18.3.1, "How to Add an Activity to a Task Flow." After you add the view activity, you can double-click it to display a wizard that allows you to create a new page or page fragment. The wizard allows you to choose between one of the following two document types for the JSF page or page fragments that you create:

Use one document type only in your task flows. For example, do not use the Facelets document type for view activities in one task flow and the JSP XML document type for view activities in another task flow. For more information about the document types, see Section 1.3.7, "Implementing the User Interface with JSF."

You also use the wizard to choose the page layout for the page or page fragment that you create. For more information about page layouts, see the "Using Quick Start Layouts" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework. In addition, you can specify whether or not to automatically expose UI components on the page or page fragment in a managed bean. For more information, see Section 24.4, "Using a Managed Bean in a Fusion Web Application."

After you complete the wizard, JDeveloper automatically associates the completed page or page fragment with the view activity. As an alternative to using the wizard, you can associate a page or page fragment with a view activity by dragging an existing page or page fragment from the Application Navigator and dropping it on top of an existing view activity. If no view activity exists, drag a page or page fragment to any other location on the diagram. When you drop the page or page fragment, JDeveloper automatically creates a new view activity associated with the page or page fragment. During creation, a default id for the view activity is automatically generated (for example Home) based on the name of the page or page fragment.

19.2.1 Passing Control Between View Activities

You can configure view activities in your task flow to pass control to each other at runtime. For example, to pass control from one view activity (view activity A) to a second view activity (view activity B), you could configure a command component (a button or a link) on the page associated with view activity A. Set the command component's Action attribute to the control flow case from-outcome that corresponds to the task flow activity that you want to invoke (in our example, view activity B). At runtime, the end user initiates the control flow case by invoking the command component. You can navigate from a view activity to another activity using either a constant or dynamic value on the Action attribute of the UI component.

A constant value of the component's Action attribute is an action outcome, as shown in Figure 19-4, that always triggers the same control flow case. When an end user clicks the component, the activity specified in the control flow case is performed. There are no alternative control flows.

Figure 19-4 Edit Property dialog

Edit Property Dialog for Action Attribute

A dynamic value of the component's Action attribute is bound to a managed bean or a method. The value returned by the method binding determines the next control flow case to invoke. For example, a method might verify user input on a page and return one value if the input is valid and another value if the input is invalid. Each of these different action values trigger different navigation cases, causing the application to navigate to one of two possible target pages.

You can also write an EL expression that must evaluate to true before control passes to the target view activity. You write the EL expression as a value for the <if> child element of the control flow case in the task flow. For more information, see Section 18.4.1, "How to Add a Control Flow Rule to a Task Flow."

19.2.1.1 How to Pass Control Between View Activities

You pass control to a view activity by specifying the value of the control flow case's from-outcome attribute as the value for the action attribute of the command component.

Before you begin:

It may be helpful to have an understanding of the options that are available to you when you configure the passing of control between view activities. For more information, see Section 19.2.1, "Passing Control Between View Activities."

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

The following procedure assumes that you have already created a:

  • Target view activity to receive control after an end user invokes the command component at runtime

  • Page that hosts a command component for the end user to invoke at runtime

To pass control to a view activity:

  1. Add a UI component to the JSF page using one of the following techniques:

    • Open the JSF page. In the ADF Faces page of the Component Palette, from the General Controls panel, drag a navigation UI component, such as Button, and drop it on the page.

    • Open the JSF page. From the Data Controls panel, drag and drop an operation or a method onto the JSF page and choose Rich Command Button or Rich Command Link from the context menu.

  2. Select the UI component and open the Property Inspector.

  3. On the Common page, expand the Button Action section.

  4. From the Action dropdown menu, choose Edit.

  5. Select Action Outcome.

  6. From the Action Outcome dropdown list select a value.

    The list contains control flow case from-outcomes already defined for the view activity associated with the page.

    Tips:

    The action attribute of the UI component can be bound either to a literal string to hardcode a navigation case, or it can be bound to a method binding expression that points to a method, which takes no arguments and returns a String. It can't be bound to any other type of EL expression.
  7. Click OK.

19.2.1.2 What Happens When You Pass Control Between View Activities

Example 19-2 contains an example of a control flow case defined in the XML source file for a bounded or unbounded task flow.

Example 19-2 Control Flow Case Defined in XML Source File

<control-flow-rule>
    <from-activity-id>Start</from-activity-id>
       <control-flow-case>
          <from-outcome>toOffices</from-outcome>
          <to-activity-id>WesternOffices</to-activity-id>
       </control-flow-case>
</control-flow-rule>

As shown in Example 19-3, a button on a JSF page associated with the Start view activity specifies toOffices as the action attribute. When the user clicks the button, control flow passes to the WesternOffices activity specified as the to-activity-id in the control flow metadata.

Example 19-3 Static Navigation Button Defined in a View Activity

<af:commandButton text="Go" action="toOffices">

19.2.2 Bookmarking View Activities

Bookmarking is available only for view activities within unbounded task flows.

When an end user bookmarks a page associated with a view activity, the URL that displays in the browser's address field for the view is saved as the bookmark. In most cases, this URL cannot be used to redisplay the page associated with the view. For example, the URL may contain Microsoft OS Windows state information that cannot be used to redisplay the page.

The bookmark URL should contain information that enables dynamic content on the page to be reproduced. For example, if an end user bookmarks a page displaying a customer's contact information, the bookmark URL needs to contain not only the page but also some identifier for the customer. This will enable contact information for the same customer to display when he returns to the page using the bookmark.

To ensure that the URL for a page displayed in a browser can be used as a bookmark, identify the view activity associated with the page as bookmarkable.

At runtime, you can identify if a view activity within the unbounded task flow has been designated as bookmarkable using the ViewBookmarkable() method. The method is located off the view port context.

After you designate a view activity as bookmarkable, you can optionally specify one or more URL parameters. The value of url-parameter is an EL expression. The EL expression specifies where the parameters that will be included in the URL are retrieved when the bookmarkable URL is generated. The EL expression also stores a value from the URL when the bookmarkable URL is dereferenced. The converter option identifies a method that performs conversion and validation when parameters are passed via bookmarkable view activity URLs.

In addition, you can specify an optional method that is invoked after updating the application model with submitted URL parameter values and before rendering the view activity. You can use this method to retrieve additional information based on URL parameter key values.

Example 19-4 contains the URL syntax for a bookmarked view activity.

Example 19-4 Unbounded Task Flow View Activity URL Syntax

<server root>/<app_context>/faces/<view activity id>?<param name>=<param value>&... 

The syntax of the URL for the bookmarked view activity is:

  • <server root>: Provided by customization at site or admin level, for example, http://mycompany.com/internalApp.

  • <app context>: The web application context root, for example, myapp. The context root is the base path of a web application. For example, <app_context> maps to the physical location of the WEB-INF node on the server.

  • faces: The faces servlet mapping. The value in faces points to the node containing the faces-config.xml configuration file.

  • <view activity id>: The identifier for the bookmarked view activity, for example, edit-customers.

  • <param name>: The name of the bookmarked view activity URL parameter, for example, customer-id.

  • <param value>: The parameter value, derived from an EL expression, for example, #{pageFlowScope.employee.id}. The value of the EL expression must be capable of being represented as a string.

Example 19-5 contains a sample URL for a bookmarkable view activity in an unbounded task flow.

Example 19-5 Sample URL for Bookmarkable View Activity

http://mycompany.com/internalApp/MyApp/faces/edit-customers?customer-id=1234&...  

19.2.2.1 How to Create a Bookmarkable View Activity

To create a bookmarkable view activity, designate a view activity as bookmarkable, specify a URL parameter in the bookmark, and specify a method that is executed after the bookmark is dereferenced.

Before you begin:

It may be helpful to have an understanding of the syntax required to create a bookmarkable view activity. For more information, see Section 19.2.2, "Bookmarking View Activities."

You may also find it helpful to understand functionality that uses other task flow features. Section 19.1.2, "Additional Functionality for Task Flow Activities."

To designate a view activity as bookmarkable:

  1. In the unbounded task flow diagram, select the view activity.

  2. In the Property Inspector, click Bookmark.

  3. In the bookmark dropdown list, select true.

  4. Expand the URL Parameters section to add optional URL parameters that will be included in the URL for the bookmarked view activity:

    • name: A name for the parameter.

    • value: A settable EL expression that, when evaluated, specifies the parameter value, for example, #{pageFlowScope.employeeID}. The value must be capable of being represented as a string.

    • converter: (optional): An EL expression to an object that implements oracle.adf.controller.URLParameterConverter.

    The value is where the parameters that will be included in the URL are retrieved from when the bookmarkable URL is generated. In addition, parameters are stored here when the bookmarkable URL is dereferenced.

    If the EL expression entered in value returns NULL, the parameter is omitted from the bookmarked view activity URL.

    The name and value are used to append a bookmark parameter to the view activity URL, as shown in Example 19-5.

  5. In the converter field, you can enter an optional value binding to use for each bookmark URL parameter value, for example, #{pageFlowScope.employee.idConverter}.

    A URL parameter converter's getAsObject() method takes a single string value as its input parameter and returns an object of the appropriate type. ADF Controller invokes the converter method on the URL parameters before applying the parameter value to the application's model objects. Similarly, the converter's getAsString() method takes an object as its input parameter and returns a string representation that is used on the URL.

    In a JSF application, data values are converted and validated using the converters and validators specified with the UI components on the submitting page. In a Fusion web application using a bookmark URL, there is no submitting page to handle the conversion and validation. Therefore, you have the option of designating a converter to use for each URL parameter.

19.2.2.2 What Happens When You Designate a View as Bookmarkable

When you designate a view activity as bookmarkable, a bookmark element is added to the metadata for the view activity, as shown in Example 19-6. The bookmark element can optionally contain metadata specifying URL parameters and a method that is executed after the bookmark is dereferenced.

Example 19-6 Sample Metadata for a Bookmarkable View Activity

<view id="employee-view">
  <page>/folderA/folderB/display-employee-info.jspx</page>    
     <bookmark>
        <url-parameter>
          <name>employee-id</name>
          <value>#{pageFlowScope.employee.id}</value>
          <converter>#{pageFlowScope.employee.validateId}</converter>
        </url-parameter>
       <method>#{pageFlowScope.employee.queryData}</method>
     </bookmark>
</view>

19.2.3 Specifying HTTP Redirect for a View Activity

You can configure a view activity so that it redirects at runtime to a URL in response to a client request. This causes ADF Controller to create a new browser URL for the view activity. The original URL for the view activity is no longer used. You cannot configure HTTP redirect for a view activity if you have already made the view activity bookmarkable, as described in Section 19.2.2, "Bookmarking View Activities."

19.2.3.1 How to Specify HTTP Redirect for a View Activity

You set a view activity's redirect property to true.

Before you begin:

It may be helpful to have an understanding of the affect of setting a view activity's redirect property to true. For more information, see Section 19.2.3, "Specifying HTTP Redirect for a View Activity."

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

To specify HTTP redirect for a view activity:

  1. In the task flow diagram, select the view activity.

  2. In the Property Inspector, expand the General section.

  3. In the Redirect dropdown list, select true.

19.2.3.2 What Happens When You Specify HTTP Redirect for a View Activity

The ADF Controller issues an HTTP redirect in response to a view activity request. The redirected request creates a new browser URL for the view activity. The original view URL is no longer used.

When specified, a HTTP redirect occurs in response to a client GET request. For a client GET, the #{bindings} EL scope is invalid until the ADF Controller and ADF Model layer set up a new bindings context for the page. Therefore, you cannot use EL expressions, such as the following, for view activities for which you specified HTTP redirect:

#{bindings.foo}

Note:

If you want http://www.mycompany.org/x.html to instead display what is at http://www.mycompany.org/y.html, do not use refresh techniques such as:

<META HTTP-EQUIV=REFRESH CONTENT="1; URL=http://www.example.org/bar">

This technique could adversely affect back button behavior. If an end user clicks a browser back button, the refresh occurs again, and navigation is forward, not backward as expected.

In this situation, use HTTP redirect instead.

19.3 Using URL View Activities

You can use a URL view activity to redirect the root view port (for example, a browser page) to any URL-addressable resource, even from within the context of an ADF region. URL addressable resources include:

To display the resource, you specify an EL expression that evaluates at runtime to generate the URL to the resource. In addition, you can specify EL expressions that, when evaluated, are added as parameters and parameter values to the URL.

A URL view activity redirects the client regardless of the view port (root view port or an ADF region) from which it is executed. The <redirect> element of a view activity performs in a similar way, except that it can be used only if the view activity is within the root view port. The <redirect> element is ignored within the context of an ADF region. For more information, see Section 19.2.3, "Specifying HTTP Redirect for a View Activity".

Redirecting elsewhere within the same application using URL view activities (not the <redirect> element) is handled similarly to back button navigation since the task flow stack is cleaned up. Redirecting out of the web application is handled like dereferencing a URL to a site external to the application.

19.3.1 How to Add a URL View Activity to a Task Flow

You can add a URL view activity to a bounded or unbounded task flow.

Before you begin:

It may be helpful to have an understanding of the affect of adding a URL view to the functionality of a task flow. For more information, see Section 19.3, "Using URL View Activities."

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

To add a URL view activity to a task flow:

  1. In the ADF Task Flow page of the Component Palette, from the Component panel, drag and drop a URL view activity onto the diagram.

  2. In the task flow diagram, select the URL view activity.

  3. On the General page of the Property Inspector, in the Activity ID field, enter an ID that identifies the URL view activity.

  4. Click the button next to the URL field to invoke the Expression Builder and write an EL expression that renders a URL at runtime.

    For example, Figure 19-5 shows a URL activity (register) in the Fusion Order Demo application's myorders-task-flow.xml bounded task flow with an EL expression (#{myOrdersBean.registerNav}) that retrieves a URL at runtime.

    Figure 19-5 URL View Activity

    URL View Activity
  5. Expand the URL Parameters section to add optional URL parameters that will be included in the URL:

    • name: A name for the parameter.

    • value: An EL expression that, when evaluated, generates the parameter value.

    • converter: A settable EL expression that, when evaluated, specifies a method to perform conversion and validation when parameters are passed via bookmarkable view activity URLs. For more information, see Section 35.3, "Enabling ADF Security".

19.3.2 What You May Need to Know About URL View Activities

Task flow URL view activities can be used within JSF portlets. Create the URL using one of the following options if you configure a task flow URL view activity for use within a JSF portlet:

  • Invoke one of the following methods from the ControllerContext class in the oracle.adf.controller package:

    • getLocalViewActivityURL()

    • getGlobalViewActivityURL()

    Do not invoke the encodeActionURL() method from the ADFPortletContainerExternalContext class with the response from the getLocalViewActivityURL() or getGlobalViewActivityURL() methods before you invoke the redirect() method from the ADFPortletContainerExternalContext class. The getLocalViewActivityURL() and getGlobalViewActivityURL() methods both perform the necessary encoding of the URL.

  • Supply a fully-qualified absolute URL.

  • Supply a context path relative URL.

  • Supply a URL relative to the current view.

A task flow URL view activity in a JSF portlet behaves as follows:

  • If the redirect URL refers to a location in the JSF portlet application and does not contain a queryString parameter named x_DirectLink with a value of true, the portlet in the containing page navigates to the URL specified in the URL view activity.

  • Otherwise, the client redirects to the URL specified in the URL view activity.

For more information about using a task flow's URL view activity, see Section 19.3, "Using URL View Activities."

For information about the methods that you can use to get a URL, see the following reference documents:

  • Oracle Fusion Middleware Java API Reference for Oracle ADF Controller

19.4 Using Router Activities

Use a router activity to route control to activities based on the runtime evaluation of EL expressions. Figure 19-6 shows a router activity (isCreateEmployee) can branch to different control flows leading from it to different activities.

Figure 19-6 Router for Alternate Control Flow Cases

Router for alternate control flow cases.

Each control flow corresponds to a different router case. Each router case uses the following elements to choose the activity to which control is next routed:

For example, if you want to configure control flow on whether a user clicks the Create a New Customer or Create a New Employee button on the welcomeUserRegistration page fragment view activity in Figure 19-6. You add a router case where the EL expression evaluates if the user entered a new customer in the input text field on the welcomeUserRegistration page fragment and an outcome (for example, newCustomer) for the router activity to return if the EL expression returns true (the user entered a new customer)

In Figure 19-6, if the EL expression to determine if a user entered a new customer evaluates to true, control passes to the customer-registration-task-flow task flow call activity, based on the control flow case from-outcome.

Best Practice:

Use a router activity if your routing condition can be expressed in an EL expression.

Using a router activity allows you to do more when you are designing the task flow that contains it. The router activity allows you to show more information about the condition on the task flow. This makes it more readable and useful to someone who looks at the diagram for your task flow.

Using a router activity also makes it easier to modify your application later. For example, you may want to modify or add a routing condition later.

19.4.1 How to Configure Control Flow Using a Router Activity

You define a control flow by dragging a router activity from the Component Palette to the diagram for the task flow. You configure the properties of the router activity (Activity ID and Default Outcome) and add router cases to the router activity.

Before you begin:

It may be helpful to have an understanding of the properties of a router activity that can affect functionality. For more information, see Section 19.4, "Using Router Activities."

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

To configure control flow using the router activity:

  1. In the ADF Task Flow page of the Component Palette, drag and drop a router activity onto the diagram.

  2. In the task flow diagram, select the router activity.

  3. From JDeveloper's main menu, choose View > Property Inspector.

  4. In the Property Inspector, expand the General category and set values for the following properties:

    • Activity ID: write a value that identifies the router activity in the task flow's source file.

    • Default Outcome: specify an activity that the router activity passes control to if no control flow cases evaluate to true or if no control flow case is specified.

  5. Click the Add icon next to Cases and specify values for each router case that you add, as described in the following list:

    • Expression: An EL expression that evaluates to true or false at runtime.

      For example, to reference the value in an input text field of a view activity, write an EL expression similar to the following:

      #{pageFlowScope.value=='view2'}

      If this EL expression returns true, the router activity invokes the outcome that you specify in the Outcome field.

    • Outcome: the outcome the router activity invokes if the EL expression specified by Expression returns true.

      Create a control flow case or a wildcard control flow rule for each outcome in the diagram of your task flow. For example, for each outcome in a control flow case, make sure that there is a corresponding from-outcome. In Figure 19-6, the value for both the case outcome and the control flow case element from-outcome is newCustomer. This makes sure that control flow passes to the newCustomer activity, the target of the control flow element.

19.4.2 What Happens When You Configure Control Flow Using a Router Activity

JDeveloper writes values to the source file of the task flow based on the values that you specify for the properties of the router activity. Example 19-7 shows the values that JDeveloper writes where values are specified for the router activity as follows:

  • The value of Default Outcome is toRegion3.

  • Two control flow cases are specified. If the input value is 1, the outcome is toRegion1 and if input value is 2, the outcome is toRegion2.

At runtime, the router activity passes control to the outcome in the control flow case where the EL expression returned true.

Example 19-7 Router Activity Metadata in a Task Flow Source File

<default-activity id="__3">Router1</default-activity>
    <router id="Router1">
      <case>
        <expression>#{binding.Region.InputValue='1'}</expression>
        <outcome id="__4">toRegion1</outcome>
      </case>
      <case>
        <expression>#{binding.Region.InputValue='2'}</expression>
        <outcome id="__5">toRegion2</outcome>
      </case>
      <default-outcome>toRegion3</default-outcome>
    </router>

19.5 Using Method Call Activities

A method call activity allows you to call a custom or built-in method that invokes application logic from anywhere within an application's control flow. You can specify methods to perform tasks such as initialization before displaying a page, cleanup after exiting a page, exception handling, and so on.

Figure 19-7 shows where the Fusion Order Demo application uses a method call activity in the Employee Registration bounded task flow. The activity calls userRegistrationCreate, a method exposed on the StoreServiceAM data control.

Figure 19-7 Method Call Activity in employee-registration-task-flow

Method call activity in Fusion Order Demo.

You can set an outcome for the method that specifies a control flow case to pass control to after the method finishes. You can specify the outcome as either:

As shown in Example 19-8, the method outcome and the method result are two different values. The <return-value> element specifies where to put the result of the calculateSalesTax method. The <outcome> element indicates which control flow case to use after the method finishes.

Example 19-8 Method Call Activity Metadata with Return and Outcome Elements

<method-call id="calculateSalesTax">
      <method>#{pageFlowScope.taxService.calculateSalesTax}</method>
      <return-value>#{pageFlowScope.result}</return-value>
      <outcome>
         <fixed-outcome>gotoError</fixed-outcome>
       </outcome>
 </method-call

For more information about control flows, see Section 18.1.3, "About Control Flows."

Best Practice:

You can use a method call on a task flow to invoke a method before a page renders, or you can use an invokeAction on a page definition.

If you want your method to execute before the application renders the page, it is usually best to use a method call activity in the task flow rather than an invokeAction in the page definition file. By adding your method as a method activity on a task flow, it is easier to invoke logic between pages. This allows you to do more at the time you're designing the task flow. You can also show more information on the task flow, thus making it more readable and useful to someone else who looks at your diagram.

You might want to use an invokeAction instead of a method call for one of the following reasons:

  • You want the method to be executed in more than one phase of the page's lifecycle.

  • You plan to reuse the page and page definition file, and want the method to be tied to the page.

  • You are not using ADF Controller.

19.5.1 How to Add a Method Call Activity

Drag a method call activity from the Component Palette to the task flow diagram. You can associate the method call activity with an existing method by dropping a data control operation from the Data Controls panel directly onto the method call activity in the task flow diagram.

In the Fusion Order Demo application, for example, you could drag a setCurrentRowWithKey or setCurrentRowWithKeyValues operation to the diagram from the Data Control Iterator to display or select the current row in a table.

Note:

Parameters for data control method parameters are defined in the page definition for the corresponding page rather than within ADF Controller metadata.

You can also drag methods and operations directly to the task flow diagram. A new method call activity is created automatically after you drop it on the diagram. You can specify an EL expression and other options for the method.

Tip:

To identify the method that a method call activity invokes, right-click the method call activity in the diagram of the task flow and choose Go to Method. JDeveloper navigates to the method that the method call activity invokes.

Before you begin:

Create a bounded or unbounded task flow. For more information, see Section 18.2, "Creating a Task Flow."

It may be helpful to have an understanding of how the properties of a method call activity affect the functionality of a task flow. For more information, see Section 19.5, "Using Method Call Activities."

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

To add a method call activity to a task flow:

  1. In the ADF Task Flow page of the Component Palette, from the Component panel, drag and drop a method call activity onto the diagram.

    The method call activity optionally displays a default ID, methodCalln, and a warning icon that indicates that a method EL expression has not yet been specified.

    Warning icon for method call activity.

    For more information about turning on the warning icons, see Section 18.3.1, "How to Add an Activity to a Task Flow".

  2. If you want to change the default ID, click the text that appears under the method call activity in the task flow diagram.

    You can enter a name for the method call, for example, addItemToCart.

  3. In the task flow diagram, select the method call activity.

  4. On the General page of the Property Inspector, enter an EL expression for the method in the Method field.

    For example, enter an EL binding expression similar to the following:

    #{bindings.addItemstoCart.execute}

    Note:

    The bindings variable in the EL expression references an ADF Model binding from the current binding container. In order to specify the bindings variable, you must specify a binding container definition or page definition. For more information, see Section 13.7, "Working with Page Definition Files".

    You can also use the Edit Property dialog box shown in Figure 19-8 to build the EL expression for the method:

    1. In the General page of the Property Inspector, from the Method dropdown menu, choose Expression Builder.

    2. In the Expression Builder dialog, expand a node, for example, ADF Bindings and choose a method. Or, under the ADF Managed Beans node, navigate to the managed bean containing the method you want to call and select the method.

    3. Click Insert Into Expression.

      The Expression Builder dialog should look similar to Figure 19-8. In Figure 19-8, for example, the addItemToCart method and shoppingCartBean combine to form the EL expression shown at the top of the Expression Builder.

      Figure 19-8 EL Expression for Method in Expression Builder Dialog

      Selected method in Edit Property dialog.
    4. Click OK.

      Tip:

      If the method call activity is going to invoke a managed bean method, double-click the method call activity in the diagram for the task flow. This invokes a dialog where you can specify the managed bean method you want to invoke.
  5. In the General page of the Property Inspector, specify one of the following in the Outcome section:

    • Fixed Outcome: On successful completion, the method always returns this single outcome, for example, success. If the method does not complete successfully, an outcome is not returned. If the method type is void, you must specify a value for Fixed Outcome rather than for to-string.

    • tostring(): If you select true, the outcome is based on calling the toString() method on the Java object returned by the method.

19.5.2 How to Specify Method Parameters and Return Values

You can specify parameters and return values for a method. Figure 19-9 shows a single parameter defined for a method called calculateSalesTax. The Value field contains an EL expression that evaluates to the parameter value at runtime.

Figure 19-9 Method Parameters in Property Inspector

Method parameters in Property Inspector

If parameters have not already been created by associating the method call activity to an existing method, add the parameters yourself.

Before you begin:

It may be helpful to have an understanding of how the properties of a method call activity affect the functionality of a task flow. For more information, see Section 19.5, "Using Method Call Activities."

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

To add method parameters:

  1. Add a method call activity to the task flow diagram.

    For more information, see Section 19.5.1, "How to Add a Method Call Activity."

  2. In the task flow diagram, select the method call activity.

  3. In the Property Inspector, click Parameters.

  4. On the Parameter page, expand the Parameters section.

  5. Click the plus Add icon.

  6. In the class field, enter the parameter class, for example, java.lang.Double.

  7. In the value field, enter an EL expression indicating where the value for the parameter will be retrieved, for example, #{pageFlowScope.shoppingCart.totalPurchasePrice}.

    Tip:

    You can click the icon next to the value field and choose Expression Builder to search for the method parameters.
  8. In the return-value field, enter an EL expression indicating where to store the method return value, for example, #{pageFlowScope.Return}.

  9. Click OK.

  10. Repeat the above steps to add additional parameters.

19.5.3 What Happens When You Add a Method Call Activity

After you specify parameters and return values for a method, the XML source file is updated. Example 19-9 shows how a method call to userRegistrationCreate appears in the XML source file for a bounded task flow.

Example 19-9 Call to userRegistrationCreate method

<method-call id="userRegistrationCreate">
     <method>#{bindings.userRegistrationCreate.execute}</method>
     <outcome>
        <fixed-outcome>editBasicInfo</fixed-outcome>
     </outcome>    
<method-call>

19.6 Using Task Flow Call Activities

You can use a task flow call activity to call a bounded task flow from either the unbounded task flow or a bounded task flow. A task flow call activity allows you to call a bounded task flow located within the same or a different application.

The called bounded task flow executes its default activity first. There is no limit to the number of bounded task flows that can be called. For example, a called bounded task flow can call another bounded task flow, which can call another, and so on.

To pass parameters into a bounded task flow, you must specify input parameter values on the task flow call activity. These values must correspond to the input parameter definitions on the called bounded task flow. For more information, see Section 19.6.3, "How to Specify Input Parameters on a Task Flow Call Activity".

Also note the following:

Tip:

When a bounded task flow is associated with a task flow call activity, input parameters are automatically inserted on the task flow call activity based on the input parameter definitions defined on the bounded task flow. Therefore, the application developer needs only to assign values to the task flow call activity input parameters.

By default, all objects are passed by reference. Primitive types (for example, int, long, or boolean) are always passed by value.

The technique for passing return values out of the bounded task flow to the caller is similar to the way that input parameters are passed. See Section 20.5, "Specifying a Return Value from a Bounded Task Flow" for more information.

19.6.1 How to Call a Bounded Task Flow Using a Task Flow Call Activity

Add a task flow call activity to the calling bounded or unbounded task flow to call a bounded task flow.

Before you begin:

It may be helpful to have an understanding of how a task flow call activity interacts with a task flow. For more information, see Section 19.6, "Using Task Flow Call Activities."

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

To call a bounded task flow:

  1. Open the calling task flow in the diagram editor.

  2. In the ADF Task Flow page of the Component Palette, from the Component panel, drag and drop a Task Flow Call activity onto the diagram.

  3. Identify the called task flow using one of the following techniques:

    • In the task flow diagram, double-click the task flow call activity.

      The Create Bounded Task Flow dialog displays, where you specify options for creating a new bounded task flow.

    • Drag an existing bounded task flow from the Application Navigator and drop it on the task flow call activity.

      Tips:

      You can drop a bounded task flow on a page or page fragment. If the bounded task flow consists of pages (not page fragments), you can choose to add a Go Link or Go Button UI component on the page where you drop the task flow. An end user can click the button or link to call the task flow. This may in turn automatically generate the task flow call activity if the page is already associated with an existing view activity in a task flow.

      You cannot drop a bounded task flow from one application to a task flow diagram contained in another application using the Application Navigator, even though both applications appear in the navigator. In addition, you cannot drop a bounded task flow contained in one project onto a task flow diagram contained in another project.

      Instead, you can package the bounded task flow in an ADF library, then reuse it in your current application or project. You can then drag the bounded task flow from the Resource Catalog or from the Component Palette page that is created when you import the library. For more information, see Section 38.2.2, "Using the Resource Palette".

    • If you know the name of the bounded task flow that you want to invoke, carry out the following steps:

      1. In the task flow diagram, select the task flow call activity.

      2. On the General page of the Property Inspector, select Static from the Task Flow Reference dropdown list.

      3. In the Document field, enter the name of the source file for the bounded task flow to call. For example, called-task-flow-definition.xml.

      4. In the ID field, enter the bounded task flow ID contained in the XML source file for the called bounded task flow, for example, targetTaskFlow.

    • If you do not know the name of the bounded task flow to invoke and it is dependent on an end user selection at runtime, carry out the following steps:

      1. In the task flow diagram, select the task flow call activity.

      2. On the General page of the Property Inspector, select Dynamic from the Task Flow Reference dropdown list.

      3. Select Expression Builder from the Dynamic Task Flow Reference dropdown menu.

      4. Write an EL expression that identifies the ID of the bounded task flow to invoke at runtime.

      Figure 19-10 shows the checkout-task-flow task flow call activity in an unbounded task flow of the Fusion Order Demo application. This task flow call activity invokes the checkout-task-flow located in the checkout-task-flow.xml file.

      Figure 19-10 Task Flow Call Activity That Invokes a Bounded Task Flow

      Task Flow Call Activity That Invokes a Bounded Task Flow

19.6.2 What Happens When You Call a Bounded Task Flow Using a Task Flow Call Activity

JDeveloper generates metadata entries in the source file for the task flow that calls the bounded task flow. Example 19-10 shows an example from the Fusion Order Demo application's adfc-config.xml that references the checkout bounded task flow (checkout-task-flow.xml). At runtime, the task flow call activity calls the checkout bounded task flow.

Example 19-10 Task Flow Call Activity in Fusion Order Demo Application's adfc-config.xml File

<task-flow-call id="checkout-task-flow">
    <task-flow-reference>
      <document>/WEB-INF/checkout-task-flow.xml</document>
      <id>checkout-task-flow</id>
    </task-flow-reference>
  </task-flow-call>

19.6.3 How to Specify Input Parameters on a Task Flow Call Activity

The suggested method for mapping parameters between a task flow call activity and its called bounded task flow is to first specify input parameter definitions for the called bounded task flow. Then you can drag the bounded task flow from the Application Navigator and drop it on the task flow call activity. The task flow call activity input parameters will be created automatically based on the bounded task flow's input parameter definition. For more information, see Section 20.3, "Passing Parameters to a Bounded Task Flow".

You can, of course, first specify input parameters on the task flow call activity. Even if you have defined them first, they will automatically be replaced based on the input parameter definitions of the called bounded task flow, once it is associated with the task flow call activity.

If you haven't yet created the called bounded task flow, you may still find it useful to specify input parameters on the task flow call activity. Doing so at this point allows you to identify any input parameters you expect the task flow call activity to eventually map when calling a bounded task flow.

Before you begin:

It may be helpful to have an understanding of how a task flow call activity interacts with a task flow. For more information, see Section 19.6, "Using Task Flow Call Activities."

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

To specify input parameters on a task flow call activity:

  1. Select the task flow call activity in the diagram for the task flow.

  2. In the Property Inspector, expand the Parameters section and click the Add icon to enter a name for the parameter.

    Tip:

    Dropping a bounded task flow on a task flow call activity in a diagram automatically populates the name field.
  3. Enter a parameter value, for example, #{pageFlowScope.callingTaskflowParm}.

    The value specifies where the parameter value will be taken from within the calling task flow.

    By default, all objects are passed by reference. Primitive types (for example, int, long, or boolean) are always passed by value.

  4. After you have specified an input parameter, you can specify a corresponding input parameter definition for the called bounded task flow. For more information, see Section 20.3, "Passing Parameters to a Bounded Task Flow".

19.6.4 How to Call a Bounded Task Flow Using a URL

You can call a bounded task flow that does not use page fragments (.jsff) in another web application using a URL. You use a task flow call activity to call the bounded task flow that you want to invoke. You write an EL expression for the task flow call activity's remote-app-url property that, when evaluated, returns a URL.

In addition to writing a value for the remote-app-url property, you specify values for task flow reference properties that identify the bounded task flow to call. The task flow reference and the remote-app-url property are combined at runtime to generate a URL to the called bounded task flow in the remote web application.

You also need to set visibility properties for the bounded task flow in the remote web application that you want to call so that it invokes when it receives the URL generated from the task flow call activity in the calling task flow.

Be aware that JSF portlets provide all content from the same web application. As a result, do not configure your web application to invoke a remote task flow using a URL if plan to use your web application in a JSF portlet.

Note:

If, in JDeveloper's Application Navigator, you right-click the bounded task flow that you want to call using a URL and select Run from the context menu, the bounded task flow executes as if it were called using a URL at runtime. For this reason, make sure to set the visibility properties for the bounded task flow even if you want to execute it as part of testing in JDeveloper.

Before you begin:

It may be helpful to have an understanding of how a task flow call activity interacts with a task flow. For more information, see Section 19.6, "Using Task Flow Call Activities."

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

To call a bounded task flow using a URL:

  1. Open the task flow in your web application that you want to configure to invoke a bounded task flow in a remote web application.

  2. In the ADF Task Flow page of the Component Palette, from the Component panel, drag a Task Flow Call activity and drop it on the diagram for the task flow.

  3. In the Property Inspector, expand the General section and write values for the properties to invoke a bounded task flow.

    For more information, see Section 19.6.1, "How to Call a Bounded Task Flow Using a Task Flow Call Activity".

  4. For the Remote Application URL property, use the Expression Builder to write an EL expression that, when evaluated, returns a string with the parts required to construct a URL of the remote web application.

    For example, the following example EL expression invokes a managed bean method that returns a string with the parts required to construct a URL:

    #{myOrdersBean.createOrder}

  5. Open the bounded task flow that you specified values for in step 3.

    Note:

    The bounded task flow you specify cannot use page fragments (.jsff).
  6. In the Structure window, right-click the node for the bounded task flow (task flow definition) and choose Go to Properties.

  7. In the Property Inspector, expand the General category and set values for the following properties:

    • URL Invoke: select url-invoke-allowed from the dropdown list if you want to allow a URL to invoke the bounded task flow. Select url-invoke-disallowed if you do not want to allow a URL to invoke the bounded task flow. Selecting this value returns a HTTP 403 status code if a URL attempts to invoke the bounded task flow. The default value (calculated) allows a URL to invoke the bounded task flow if the bounded task flow does not specify an initializer and it has a view activity as its default activity. If the bounded task flow does not meet these conditions, a HTTP 403 status code is returned. Selecting url-invoke-allowed or url-invoke-disallowed overrides the default behavior.

    • Library Internal: set to true if you want the bounded task flow to be internal when you package it in an ADF Library JAR. The default value is false.

      For more information about packaging a bounded task flow in an ADF Library JAR, see Section 38.3, "Packaging a Reusable ADF Component into an ADF Library".

  8. Save and close the bounded task flow.

19.6.5 What Happens When You Configure a Bounded Task Flow to be Invoked by a URL

JDeveloper generates metadata entries in the source file of the task flow that invokes the task flow call activity to the bounded task flow in a remote web application. Example 19-11 shows an example entries for a task flow call activity.

Example 19-11 Metadata Entries for a Task Flow Call Activity to a Bounded Task Flow

<task-flow-call id="createOrder">
    <task-flow-reference>
      <document id="__6">myorders-task-flow.xml</document>
      <id id="__5">myorders-task-flow</id>
    </task-flow-reference>
    <remote-app-url id="__7">#{myOrdersBean.createOrder}</remote-app-url>
  </task-flow-call>

The createOrder method in Example 19-11 returns a string with the URL syntax required to invoke a bounded task flow. For more information about the URL syntax, including descriptions of the required parts in the returned string and an example URL, see Section 19.6.6, "What You May Need to Know About Calling a Bounded Task Flow Using a URL."

JDeveloper also generates entries in the source file for the bounded task flow to invoke when you configure it so it can be called by a URL. Example 19-12 shows sample metadata entries that allow a bounded task flow to be invoked by a URL.

Example 19-12 Metadata Entries to Allow a URL Invoke a Bounded Task Flow

<task-flow-definition id="task-flow-definition3">
    <visibility id="__2">
      <url-invoke-allowed/>
      <library-internal/>
    </visibility>
  </task-flow-definition>

19.6.6 What You May Need to Know About Calling a Bounded Task Flow Using a URL

Adding a context parameter in your local application´s deployment descriptor may ease the administration of interaction with a remote web application.

Context Parameter for Remote Web Application

Consider adding a context parameter to the deployment descriptor (web.xml) for your Fusion web application (local application) if you use a URL to invoke a bounded task flow in another Fusion web application (remote application). Set the value of the context parameter to the URL of the remote application. Use the context parameter name when writing EL expressions in the local application, as shown in the following example where remoteAppUrl is the name of the context parameter:

#{initParam.remoteAppUrl}

If the URL of the remote application changes, you can update the context parameter to reference the changed URL.

URL Syntax to Invoke a Bounded Task Flow

Typically, you write an EL expression that references a managed bean method which, in turn, retrieves the required parts of the URL or you could write an EL expression that renders the URL directly, as shown in Example 19-13.

Example 19-13 Example URL to Invoke a Bounded Task Flow

http://somecompany.com/internalApp/MyApp/faces/adf.task-flow?adf.tfId=displayHelp&
adf.tfDoc=%2FWEB-INF%2Fdisplayhelp.xml&topic=createPurchaseOrder

Example 19-14 describes the parts of the URL syntax to invoke a bounded task flow.

Example 19-14 URL Syntax for a Call to a Bounded Task Flow Using Named Parameters

<server root>/<app_context>/faces/adf.task-flow?adf.tfid=<task flow definition ID>&adf.tfDoc=<document name>&<named parameter>=<named parameter value>

The following list describes each part of the URL syntax in Example 19-14:

  • <server root>: Provided by customization at site or admin level. For example:

    http://mycompany.com/internalApp

    The <server root> value depends on the application server where you deploy the bound task flow. The bounded task flow URL is a resource within the JSF servlet's URL path.

  • <app context>: The Web application context root, for example, MyApp. The context root is the base path of a Web application.

  • faces: Faces servlet mapping.

  • adf.task-flow: A reserved keyword that identifies the ADF Controller for the remote web application.

  • adf.tfId: A URL parameter that supplies the task flow ID to call.

  • <task flow ID>: The identifier of the bounded task flow to call, for example, displayHelp. This is the same task flow ID that is used when calling locally. Note that this identifier is not the same as the task flow call activity instance ID. The parameter value must be represented as a string.

  • adf.tfDoc: A URL parameter that supplies the document name containing the bounded task flow ID to be called.

  • <document name>: A document name containing the bounded task flow ID to be called, for example,%2FWEB-INF%2FtoUppercase%2FdisplayHelp.xml. If you are handcrafting the bounded task flow URL, you are responsible for the appropriate encoding.

  • <named parameter>: (optional) The name of an input parameter definition for the called bounded task flow, for example, topic. You must supply all required input parameter definitions.

  • <named parameter value>: (optional) The value of the input parameter.

Note:

URL parameter names that begin with an underscore ('_') are intended for internal use only and should not be used. Although you may see these names on URLs generated by ADF Controller, you should not attempt to use or depend on them.

Object Type for Parameter Converters

Parameter converters, if specified, can be used to convert task flow parameter values to and from the string representations used in a URL. A parameter converter is an EL expression that evaluates to an object of the following type:

oracle.adf.controller.UrlParameterConverter

If you do not specify a parameter converter, a default converter checks the parameters for cross-site-scripting (XSS) attacks. If you know that the parameter values used in your application contain special characters, you should create your own implementation of UrlParameterConverter and use it to perform conversion of the task flow parameter values.

19.6.7 How to Specify Before and After Listeners

Task flow call activity before and after listeners are used to identify the start and end of a bounded task flow. Specifying a listener in the task flow call activity means that the listener executes on that specific usage of the called bounded task flow.

You specify the listener as an EL expression for a method that will be called upon entry or exit of a bounded task flow, for example, <before-listener>#{global.showState}</before-listener}>. The method cannot have parameters.

  • Before listener: An EL expression for a Java method called before a bounded task flow is entered. It is used when the caller needs to know when a bounded task flow is being initiated.

  • After listener: An EL expression for a Java method called after a bounded task flow returns. It is used when the caller needs to know when a bounded task flow exits and control flow returns to the caller.

If multiple before listeners or multiple after listeners are specified, they are called in the order in which they appear in the source document for the unbounded or bounded task flow. A task flow call activity can have only have before listener and one after listener.

In order for the task flow call after listeners to be called, control flow must return from the bounded task flow using a control flow rule. If an end user leaves a bounded task flow using the browser back button or other URL, task flow call after listeners will not be called. You must use a bounded task flow finalizer to release all acquired resources and perform cleanup of a bounded task flow that the end user left by clicking a browser back button.

Before you begin:

It may be helpful to have an understanding of how a task flow call activity interacts with a task flow. For more information, see Section 19.6, "Using Task Flow Call Activities."

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

To specify a before or after listener on a task flow call activity:

  1. In the diagram of the calling bounded task flow, select the task flow call activity.

  2. In the Property Inspector, click Listeners.

  3. Click the button next to either before-listener or after-listener.

  4. In the Expression Builder dialog, drill down to the Java class containing the method for the listener.

  5. Open the class node and select the listener method.

    When you are done, your EL expression might look like #{pageFlowscope.managedBean.methodListener}.

  6. Click OK.

19.6.8 What Happens When You Add a Task Flow Call Activity

After you add a task flow call activity to a task flow diagram, you must specify a reference to the called bounded task flow using one of the methods described in Section 19.6.1, "How to Call a Bounded Task Flow Using a Task Flow Call Activity". For example, if you drop an existing bounded task flow on the task flow call activity, JDeveloper generates the task flow reference automatically. The task flow reference is used to invoke the called bounded task flow.

If the task flow reference is static, each task flow reference consists of:

  • id: The bounded task flow id contained in the XML source file for the called bounded task flow. For example, a called task flow might have an ID called targetFlow. The same XML source file can contain multiple bounded task flows, each bounded task flow identified by a unique ID.

    Note:

    If you use JDeveloper to create the bounded task flow, there is only one bounded task flow per document.
  • document: The name of the XML source file containing the ID of the called bounded task flow. If document is not specified, adfc-config.xml is assumed.

    The document is a physical XML file and must be accessible via MDS.

Example 19-15 contains an example static task flow reference within a task flow call activity. In order to invoke a bounded task flow, you need to know its id and name of the file containing the id.

Example 19-15 Static Task Flow Reference

<adfc-config xmlns="http://xmlns.oracle.com/adf/controller" version="1.2" id="__1">
...
  <task-flow-definition id="task-flow-definition">
    <default-activity>view1</default-activity>
    <task-flow-call id="taskFlowCall">
      <task-flow-reference>
        <document>/WEB-INF/called-task-flow-definition.xml</document>
        <id>called-task-flow-definition</id>
      </task-flow-reference>
    </task-flow-call>
  </task-flow-definition>
...
</adfc-config>

Example 19-16 shows the metadata that JDeveloper generates for a dynamic task flow reference within a task flow call activity.

Example 19-16 Dynamic Task Flow Reference

<?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="bounded_tf">
    <default-activity id="__2">taskFlowCall1</default-activity>
    <task-flow-call id="taskFlowCall1">
      <dynamic-task-flow-reference id="__3">#{EL_Expression_Retrieve_
                            TaskflowID}</dynamic-task-flow-reference>
    </task-flow-call>
  </task-flow-definition>
</adfc-config>

19.6.9 What Happens at Runtime When a Task Flow Call Activity Invokes a Task Flow

The ADF Controller performs the following steps when a bounded task flow is called using a task flow call activity:

  1. Verifies that the user is authorized to call the bounded task flow.

  2. Invokes task flow call activity before listener or listeners, if specified (see Section 19.6.7, "How to Specify Before and After Listeners").

  3. Evaluates the input parameter values on the bounded task flow.

  4. Pushes the called bounded task flow onto the stack and initializes its page flow scope.

  5. Sets input parameter values in the called bounded task flow's context.

  6. Invokes a bounded task flow initializer method, if one is specified.

  7. Executes the bounded task flow's default activity.

19.7 Using Task Flow Return Activities

A task flow return activity identifies the point in an application's control flow where a bounded task flow completes and sends control flow back to the caller. You can use a task flow return activity only within a bounded task flow.

A gray circle around a task flow return activity icon indicates that the activity is an exit point for a bounded task flow. A bounded task flow can have zero to many task flow return activities. Figure 19-11 shows a bounded task flow with task flow return activities named Login and addNewCust.

Figure 19-11 Multiple Task Flow Return Activities

Multiple task flow return activities.

Each task flow return activity specifies an outcome that is returned to the calling task flow. For example, the outcome for the rollbackReturn task flow return activity in the Fusion Order Demo application customer registration bounded task flow is cancelCreateCust.

Figure 19-12 shows an extract of the customer registration bounded task flow (customer-registration-task-flow.xml). This task flow contains two task flow return activities (rollbackReturn and commitReturn). The rollbackReturn task flow return activity's outcome is cancelCreateCust. In contrast, the commitReturn task flow return activity's outcome returns globalhome.

Figure 19-12 Task Flow Return Activities Specifying Different Outcomes

Task Flow Return Activities

The outcome returned to the task flow that invokes the customer registration task flow depends on the end user action. You can configure control flow cases in the invoking task flow to determine the next action by the invoking task flow. Set the from-outcome element of a control flow case to the value returned by the task flow return activity's outcome to invoke an action based on that outcome. This determines control flow upon return from the customer registration task flow.

Set a value for the Restore Save Point property to specify if model changes made in a bounded task flow are saved or discarded when the bounded task flow exits by using a task flow return activity. Set to true to roll back transactions to the ADF Model save point that was created when the Fusion web application first entered the bounded task flow. The default value is false. You can specify a value for this property only if the bounded task flow on which the task flow return activity is located was entered without starting a new transaction. For more information, see Section 22.2.1, "How to Enable Transactions in a Bounded Task Flow".

Before you begin:

It may be helpful to have an understanding of how a task flow return activity interacts with a task flow. For more information, see Section 19.7, "Using Task Flow Return Activities."

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

To add a task flow return activity to a bounded task flow:

  1. In the ADF Task Flow page of the Component Palette, from the Component panel, drag and drop a task flow return activity onto the diagram for the bounded task flow.

  2. In the task flow diagram, select the task flow return activity.

  3. On the Common page of the Property Inspector, expand the Outcome section.

  4. In the Name field, enter an outcome, for example, preferredCustomer.

    Specifying this returns an outcome to the caller when the bounded task flow exits. You can specify only one outcome per task flow return activity. The calling task flow should define control flow rules to handle control flow upon return. See Section 18.4.1, "How to Add a Control Flow Rule to a Task Flow" for more information.

  5. In the Property Inspector, expand the Behavior section.

  6. In the Reentry dropdown list, choose one of the following options:

    • reentry-allowed: Reentry is allowed on any view activity within the bounded task flow.

    • reentry-not-allowed: Reentry of the bounded task flow is not allowed.

      If you specify reentry-not-allowed on a bounded task flow, an end user can still click the browser back button and return to a page within the bounded task flow. However, if the user does anything on the page such as clicking a button, an exception (for example, InvalidTaskFlowReentry) is thrown indicating the bounded task flow was reentered improperly. The actual reentry condition is identified upon the submit of the reentered page.

    Your selection defines the default behavior when the bounded task flow is reentered by an end user clicking a browser's Back button. This selection applies only if reentry-outcome-dependent has been set on the bounded task flow where the task flow return activity is located. For more information, see Section 22.3, "Reentering Bounded Task Flows".

  7. In the End Transaction dropdown list, choose one of the following options:

    • commit: Select to commit the existing transaction to the database.

    • rollback: Select to roll back the transaction to what it was on entry of the called task flow. This has the same effect as canceling the transaction, since it rolls back a new transaction to its initial state when it was started on entry of the bounded task flow.

      If you do not specify commit or rollback, the transaction is left open to be closed by calling bounded task flow.

  8. In the Restore Save Point dropdown list, select true when either of the following conditions apply:

    • If Always Begin New Transaction (new-transaction) is not selected on the bounded task flow on which the task flow return activity is located

    • ADF model changes made within a bounded task flow should be discarded when exiting using the task flow call activity. The transaction is rolled back to the save point created on entry of the bounded task flow.

    For more information, see Section 22.2.1, "How to Enable Transactions in a Bounded Task Flow".

19.8 Using Save Point Restore Activities

The save point restore activity allows you to restore a previous persistent save point in an application supporting save for later functionality. A save point captures a snapshot of the Fusion web application at a specific instance. Save point restore enables the application to restore whatever was captured when the save point was originally created.

When a save point is restored, ADF Controller terminates the saved application and restarts the application that was executing when the end user performed a save. The end user's original location in the application is displayed. Once the save-point-id is restored, it is deleted from its method of persistence (database or Java object cache).

A save point restore activity is not required within every individual application supporting save for later capabilities. It is only required within the applications responsible for restoring the previously persistent save-point-ids. For example, a save point restore activity would not be required within a Create Expense Report application, but would be within the application used to select previously saved expense reports for further updates.

Section 22.6, "Using Save Points in Task Flows" contains detailed information about enabling save for later capabilities in a task flow and provides an example of how to use the save point restore activity to retrieve the saved application state and data.

19.9 Using Parent Action Activities

A bounded task flow running in an ADF region may need to trigger navigation of its parent view activity. The parent action activity allows a bounded task flow running in an ADF region to generate outcomes that it passes to the parent view activity. The outcomes are used to navigate the task flow containing the parent view activity rather than navigating the task flow of the ADF region.

For more information, see Section 21.7.1, "How to Trigger Navigation Outside of an ADF Region's Task Flow."

19.10 Using Task Flow Activities with Page Definition Files

Page definition files define the binding objects that populate data at runtime. They are typically used in a Fusion web application to bind page UI components to data controls. A number of task flow activities can also use page definition files to bind to data controls. These are:

If you right-click any of the above task flow activities (except view activity) in the diagrammer for a task flow, JDeveloper displays an option on the context menu that enables you to create a page definition file (Create Page Definition) if one does not yet exist. If a page definition file does exist, JDeveloper displays a context menu option for all task flow activities to go to the page definition file (Go to Page Definition). JDeveloper also displays a context menu option (Edit Binding) when you right-click a method call activity that is associated with a page definition file.

A task flow activity that is associated with a page definition file displays an icon in the lower-right section of the task flow activity icon. Figure 19-13 shows an example for each of the task flow activities.

Figure 19-13 Task Flow Activities Associated with Page Definition Files

Task Flow Activities with Page Definition Files

19.10.1 How to Associate a Page Definition File with a Task Flow Activity

JDeveloper provides a context menu option that you can access from the task flow activity. You use this context menu option to associate the task flow activity with a page definition file.

Before you begin:

It may be helpful to have an understanding of how task flow activities use page definition files. For more information, see Section 19.10, "Using Task Flow Activities with Page Definition Files."

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

To associate a page definition file with a task flow activity

  1. In the diagrammer for the task flow, right-click the task flow activity for which you want to create a page definition file.

  2. Choose Create Page Definition from the context menu that appears.

  3. In the resulting page definition file, add the bindings that you want your task flow activity to reference at runtime.

    For more information about page definition files, see Section 13.7, "Working with Page Definition Files".

19.10.2 What Happens When You Associate a Page Definition File with a Task Flow Activity

At design time, JDeveloper generates a page definition file for the task flow activity. The filename of the page definition file comprises the originating task flow and either the name of the task flow activity or the data control operation to invoke. For example, taskflowName_taskflowName_methodCall1PageDef.xml or taskflowName_taskflowName_CreateInsertPageDef.xml.

JDeveloper also generates an EL expression from the task flow activity to the binding in the created page definition file. Example 19-17 shows a method call activity that references a CreateInsert action binding.

Example 19-17 Task Flow Activity Referencing an Action Binding

<method-call id="CreateInsert">
      <method>#{bindings.CreateInsert.execute}</method>
      <outcome>
        <fixed-outcome>CreateInsert</fixed-outcome>
      </outcome>
    </method-call>

At runtime, a binding container makes sure that a task flow activities' EL expressions reference the correct value.