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

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

Go to previous page
Previous
Go to next page
Next
View PDF

14 Working with Task Flow Activities

This chapter describes how to use activities in your ADF 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:

14.1 Introduction to Activity Types

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

The bounded task flow shown in Figure 14-1 contains activities that run in order to check out of the 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 14-1

Figure 14-1 Checkout Bounded Task Flow in Fusion Order Demonstration Application

Checkout bounded task flow.

Table 14-1 describes the types of activities and control flows you can add to a task flow.

Table 14-1 ADF 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 14.5, "Using Method Call 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 14.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 17.5, "Saving for Later" for more information.

Task flow call activity.

Task Flow Call

Calls an ADF bounded task flow from an ADF unbounded task flow or another bounded task flow. See Section 14.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 ADF bounded task flows only). See Section 14.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 14.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 14.2, "Using View Activities" for more information. See Section 18.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 13.1.3, "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 13.2.4, "How to Add a Wildcard Control Flow Rule" for more information.

Wildcard control flow rule.

Parent Action

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


Table 14-2 describes the annotations (notes and attachments) you can add to an ADF task flow.

Table 14-2 ADF 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.


14.2 Using View Activities

The primary type of task flow activity is a view, which displays a JSF page or page fragment. A page fragment is a JSF JSP document that is rendered as content in another JSF page. Page fragments are typically used in bounded task flows. The bounded task flow can be added to a page as region. For more information, see Section 16.1, "Introduction to ADF Regions").

Figure 14-2 shows the Home view activity, located in the Fusion Order Demo application.

Figure 14-2 View Activity

A view activity in a task flow.

A view activity is associated in metadata with a physical JSF page or page fragment. The view activity is identified by an id attribute. The page or page fragment name is identified by a <page> element in the task flow metadata:

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

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

The file extension for a page fragment is.jsff:

<view id="Home">
   <page>WEB-INF/Home.jsff</page>
 </view>

14.2.1 Adding a View Activity

The steps for adding a view activity are similar to those for adding any activity to a task flow diagram (see Section 13.2.2, "How to Add an Activity to an ADF Task Flow". After you add the view activity, you can double-click it to display the Create JSF JSP Page wizard, which enables you to create a new page or page fragment. You also use the wizard to define characteristics for the page or page fragment. JDeveloper automatically associates the completed page or page fragment with the view activity.

You can also drag an existing page or page fragment from the Application Navigator and drop it on top of a view activity.

If you drag a page or page fragment to any other location on the diagram, a new view activity associated with the page or page fragment is automatically created. 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.

14.2.2 Transitioning Between View Activities

Transitioning refers to one view activity passing control to another view activity.For example, control flow can be initiated at runtime by selecting a UI component on a page, such as a button or link. The Action attribute of the UI component should be set to the corresponding control flow case from-outcome leading to the next task flow activity. 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.

Figure 14-3 Edit Property dialog

Edit Property Dialog for Action Attribute
  • Constant: value of the Action attribute of the component is an Action Outcome, as shown in Figure 14-3. Action Outcome is a constant value 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.

  • Dynamic: value of the Action attribute of the component is bound to a managed bean or a method. The value of the method binding determines the next control flow case that should be performed.

    For example, the 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 could trigger different navigation cases, causing the application to navigate to one of two possible target pages.

For more information about components that are bound to data control methods, see Section 26.2, "Creating Command Components to Execute Methods".

14.2.2.1 How to Transition to a View Activity

Before you begin, you should already have a target view activity, as well as a JSF page on which you will add a component. The component's action will be based on the from-outcome of the control flow case leading to the target activity.

To transition to a view activity:

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

    • Open the JSF page. From the ADF Faces Common Components list in the Component Palette, drag a navigation UI component such as a button or link onto 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 dropdown menu next to Action, and 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.

14.2.2.2 What Happens When You Transition Between Activities

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

Example 14-1 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 14-2, 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 14-2 Static Navigation Button Defined in a View Activity

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

14.2.3 Bookmarking View Activities

Bookmarking is available only for view activities within ADF 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 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 an unbounded task flow has been designated as bookmarkable using the ViewBookmarkable() method. The method is located off the ViewPortContext.

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.

Instead of designating the view activity as bookmarkable, you can specify the redirect option. redirect causes the ADF Controller to create a new browser URL for the view activity. The original URL for the view activity is no longer used. For more information, see Section 14.2.3.2, "How to Specify HTTP Redirect" for more information.

Example 14-3 contains the URL syntax for a bookmarked view activity.

Example 14-3 ADF 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 14-4 contains a sample URL for a bookmarkable view activity in an ADF unbounded task flow.

Example 14-4 Sample URL for Bookmarkable View Activity

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

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

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

  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.

14.2.3.2 How to Specify HTTP Redirect

The redirect option specified for a view activity indicates that ADF Controller should issue an HTTP redirect for 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, the redirect will occur from a client GET request. For HTTP GETs, the #{bindings} EL scope is invalid until the ADF Controller and the ADF Model layer set up a new bindings context for the page. Therefore, the redirected input parameter for the view activity cannot be mapped.

A view activity can be identified as either bookmarkable or identified with the redirect option, but not both.

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.

To specify HTTP redirect for a view activity:

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

  2. In the Property Inspector, click Common.

  3. In the redirect dropdown list, select true.

14.2.3.3 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 14-5. The bookmark element can optionally contain metadata specifying URL parameters and a method that is executed after the bookmark is dereferenced.

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

14.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 must specify an EL expression that is evaluated 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 14.2.3.2, "How to Specify HTTP Redirect".

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.

To add a URL view activity to a task flow diagram.

  1. Drag a URL view activity from the ADF Task Flow section in the Component Palette onto the diagram.

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

  3. On the Common page of the Property Inspector, enter an id, for example, externalSite.

  4. Click the button next to the url field and create an EL expression, for example, #{pageFlowScope.someBean.redirectURL}.

    The EL expression is evaluated at runtime to generate the URL to the resource.

  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 28.2.4, "How to Enable ADF Authentication and Authorization".

14.3.1 Constructing a URL for Use Within a Portlet

When constructing a URL for use in a task flow's URL view activity that may be used within the context of a portlet, construct the URL by calling one of the following:

  • ControllerContext.getLocalViewActivityURL()

  • ControllerContext.getGlobalViewActivityURL(), passing in the target viewId

or a fully qualified absolute URL, a context path relative URL, or a URL that is relative to the current view.

Note:

If you call the ControllerContext.getLocalViewActivityURL()or ControllerContext.getGlobalViewActivityURL()methods to construct the redirect URL, do not call ExternalContext.encodeActionURL() with the response before calling ExternalContext.redirect().

This is because the methods already incorporate the necessary encoding of the URL.

When a URL view activity is used within a task flow in a portlet, the following behavior occurs:

  • If the redirect URL refers to a location within the portlet application and doesn't contain a queryString parameter named x_DirectLink whose value is true, then the portlet within the containing page will navigate to this new view.

  • Otherwise, a client redirect is issued, resulting in the user being directed away from the application or containing page and to the URL.

14.4 Using Router Activities

You can use a router activity to declaratively route control to activities based on logic specified in an EL expression. As shown in Figure 14-4, a router has multiple control flows leading from it to different activities.

Figure 14-4 Router for Alternate Control Flow Cases

Router for alternate control flow cases.

Each control flow can correspond to a different router case. Each router case contains the following elements, which are used to choose the activity to which control is next routed:

For example, suppose you want to base control flow on whether a user clicks the Create a New Customer or Create a New Employee button on the welcomeUserRegistration page fragment shown in Figure 14-4.

You could add an EL expression for one of the router cases that evaluates whether the user entered in the input text field on the user registration page fragment is a new customer. You would next specify an expected outcome, for example, newCustomer. As shown in Figure 14-4, if the expression evaluates to true, control passes to the customer-registration-task-flow task flow call activity, based on the control flow case from-outcome, newCustomer.

Best Practice:

If your routing condition can be expressed in EL, use a router.

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

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

To define a control flow using the router activity:

  1. From the ADF Task Flow page of the Component Palette, drag a Router activity to the task flow diagram.

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

  3. From the main menu, choose View -> Property Inspector.

  4. On the Common page of the Property Inspector, enter an id.

    The id is an identifier that is used to reference the router activity within the metadata, for example, router1.

  5. Click the Add icon next to Cases.

  6. Specify values for each of the router's cases.

    A case is a condition that, when evaluated to true, returns an outcome. For each case, you must enter:

    • expression: An EL expression evaluating to true or false.

      The expression can reference an input text field in a view activity. For example, suppose the value of the field is #{pageFlowScope.value}. The expression could be #{pageFlowScope.value=='view2'}, meaning that the specified outcome will be returned if a user enters view2 in the field.

    • outcome: Returned by the router activity when its corresponding expression evaluates true.

      You must account for each outcome with a matching control flow case or a wildcard control flow rule in your task flow diagram. For example, for each case outcome, you can ensure there is a corresponding from-outcome specified for a control flow case element leading from the router activity in the diagram. In Figure 14-4, the value for both the case outcome and the control flow case element from-outcome is newCustomer. This ensures that control flow will pass to the newCustomer activity, the target of the control flow element.

  7. In the Property Inspector, enter a default-outcome.

    This outcome is returned if none of the cases for the router activity evaluates true, or if no cases are specified.

    Example 14-6 identifies a default outcome, toRegion3. Control flow goes to the case whose from outcome is toRegion3 is returned by the router activity when none of its cases evaluates to true.

    Example 14-6 Router Metadata Defining a Default Outcome

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

14.5 Using Method Call Activities

In a standard JSF application, application logic can be invoked only from actions specified within the JSF page markup. 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 forth.

As shown in Figure 14-5, 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 14-5 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. For more information, see Section 13.1.3, "Control Flows". You can specify the outcome as either:

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

Best Practice:

You can use a method call on an ADF 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 page is rendered, it is usually best to use a method call activity in the task flow diagram rather than an invokeAction in the page definition file. By adding your method as a method activity on a page flow diagram, 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.

14.5.1 How to Add a Method Call Activity

Before you begin, you should have already created an ADF bounded or unbounded task flow. For more information, see Section 13.2, "Creating Task Flows". 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, for example, you could drag the addItemToCart method from StorefrontModelDataControl to the diagram. Or 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. For more information, see Section 26.3, "Setting Parameter Values Using a Command Component".

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

To add a method call activity to an ADF task flow:

  1. In the Component Palette, drag a method call activity from the ADF Task Flow page to the diagram for the ADF task flow.

    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 13.2.2, "How to Add an Activity to an ADF 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 Common page of the Property Inspector, enter an EL expression for the method in the method field.

    For example, you can enter an EL binding expression such as #{bindings.addItemstoCart.execute}.

    Note:

    The bindings variable in the EL expression indicates an ADF model binding from the current binding container. In order to specify the bindings variable, a binding container definition or page definition must be specified. See Section 11.6, "Working with Page Definition Files".

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

    1. In the Common page of the Property Inspector, from the drop-down menu next to the method field, 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.

      When you are finished, the dialog should look similar to Figure 14-6.

      Figure 14-6 EL Expression for Method in Edit Property Dialog

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

  5. In the Common page of the Property Inspector, expand the Outcome section and specify one of the following:

    • fixed-outcome: On successful completion, the method always returns this single outcome, for example, success. If the method doesn't complete successfully, an outcome isn't returned. If the method type is void, you must specify a fixed-outcome, not a to-string.

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

14.5.2 How to Specify Method Parameters and Return Values

Figure 14-7 shows a single parameter defined for a method called calculateSalesTax. The value field contains an EL expression that evaluates to the parameter value.

Figure 14-7 Method Parameters in Property Inspector

Method parameters in Property Inspector

If parameters haven't already been created by associating the method call activity to an existing method, follow the steps below.

To add method parameters:

  1. Follow the steps in Section 14.5.1 to add a method call activity to a task flow diagram.

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

14.5.3 What Happens When You Add a Method Call Activity

Example 14-8 shows how a method call to userRegistrationCreate appears in the XML source file for an ADF bounded task flow.

Example 14-8 Call to userRegistrationCreate method

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

14.6 Using Task Flow Call Activities

You can use the task flow call activity to call an ADF bounded task flow from either an ADF unbounded or bounded task flow. Options on the task flow call activity allow you to call a bounded task flow located within the same application or a different application.

The called bounded task flow executes beginning with its default activity. There is no depth limit to the number of ADF bounded task flow calls. A called ADF bounded task flow can call another ADF bounded task flow, which can call another and so on.

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

Tip:

When a task flow definition 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 task flow definition. Therefore, the application developer only needs 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 ADF bounded task flow to the caller is similar to the way that input parameters are passed. See Section 15.4, "Specifying Return Values" for more information.

14.6.1 How to Call an ADF Bounded Task Flow

To call an ADF bounded task flow, add a task flow call activity to the diagram for the calling bounded or unbounded task flow.

To call an ADF bounded task flow:

  1. In the editor, open the task flow diagram for the calling ADF task flow.

  2. In the ADF Task Flow dropdown list of the Component Palette, select a task flow call activity and drop it on 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 ADF Task Flow dialog displays, where you specify options for creating a new bounded task flow.

    • Drag an existing ADF bounded task flow from either the Application Navigator or the Resource Palette and drop it on the task flow call activity in the task flow diagram.

      Tips:

      You can also drag an ADF bounded task flow from the Application Navigator and drop it directly on the task flow diagram. This automatically adds to the diagram a task flow call activity that calls the ADF bounded task flow.

      You can drop an ADF bounded task flow on a page or page fragment. If the ADF bounded task flow consists of pages (not page fragments), you can choose whether 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 definition. This may in turn automatically generate the task flow call activity if the page is already associated with an existing view activity in an ADF task flow.

      You cannot drop an ADF bounded task flow contained in one application to a 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. See Section 31.1.2, "Using the Resource Palette" for more information.

    • Associate the task flow call activity to the called task flow definition by following these steps:

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

    2. On the Common page of the Property Inspector, expand the Task Flow Reference node.

    3. Enter a document name.

      This is the name of the source file containing the id of the called ADF bounded task flow, for example, called-task-flow-definition.xml.

    4. Enter an id.

      This is the task flow definition id contained in the XML source file for the called ADF bounded task flow, for example, targetTaskFlow.

14.6.2 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 task flow definition. Then you can drag the task flow definition 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 task flow definition's input parameter definition. For more information, see Section 15.2, "Passing Parameters to an ADF 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 task flow definition, once it is associated with the task flow call activity.

If you haven't yet created the called task flow definition, 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 task flow definition.

To specify input parameters on the task flow call activity

  1. Select the task flow call activity in the task flow diagram and open the Property Inspector.

  2. Click Parameters.

  3. Click the + icon and enter a name for the parameter, for example, empno.

    Tip:

    Dropping an ADF bounded task flow on a task flow call activity in a diagram automatically populates the name field.
  4. 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.

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

14.6.3 How to Call an ADF Bounded Task Flow Located in Another Web Application

You can use the remote-app-url option on a task flow call activity to call an ADF bounded task flow located in a different web application. You specify in remote-app-url an EL expression that, when evaluated, returns the remote web application's URL. Using an EL expression allows you to configure the remote application's URL in any manner, including using context initialization parameters in web.xml, for example #{initParam.remoteAppUrl}.

In addition to the remote-app-url, you must also specify a task flow reference in the task flow call activity metadata. The task flow reference and remote application URL values are combined at runtime to generate a URL to the called task flow.

To call an ADF bounded task flow in a different web application:

  1. In the Component Palette, drag the Task Flow Call activity from the ADF Task Flow dropdown list to the task flow diagram.

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

  3. In the Property Inspector, expand the Task Flow Reference section.

  4. Enter a reference (document and id) to the bounded task flow (see Section 14.6.1, "How to Call an ADF Bounded Task Flow" for more information).

  5. In the Property Inspector, click the button next to remote-app-url.

  6. In the Expression Builder dialog, you can create an EL expression that, when evaluated, furnishes two components in the URL to the called bounded task flow, the server root and the app context. For example, you could specify the EL expression, #{pageFlowScope.managedbean.URLmethod}, where URLmethod evaluates to the string http://my.remote.com:80/myapp/faces.

14.6.4 How to Call a Bounded Task Flow with a URL

When calling by URL, you are responsible for creating the entire URL. The called bounded task flow can be in the same or a different application.

You can use an EL Expression to create the URL. For example, the EL expression could evaluate to a server root of somecompany/internalApp and an app context of MyApp as shown in Example 14-9.

Example 14-9 Sample URL for an ADF bounded task flow

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

Example 14-10 contains the syntax for a URL to an ADF bounded task flow.

Example 14-10 URL Syntax For Call to ADF 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 components of the URL syntax are:

  • <server root>: Provided by customization at site or admin level, for example, http://mycompany.com/internalApp. The root name depends on the server where the task flow definition is deployed. The ADF 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 word that identifies the ADF Controller for the remote web application.

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

  • <task flow ID>: The identifier of the task flow definition to be called, 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 task flow definition ID to be called.

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

  • <named parameter>: (optional) The name of an input parameter definition for the called ADF 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.

14.6.5 Specifying a Parameter Converter

A parameter converter is an EL value expression that evaluates to an object of type oracle.adf.controller.URLParameterConverter. If a converter is specified, it is used to convert task flow parameter values to /from the string representation used in a URL.

14.6.6 How to Specify Before and After Listeners

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

You specify the listener as an EL expression for a method that will be called upon entry or exit of an ADF 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 an ADF bounded task flow is entered. It is used when the caller needs to know when an ADF bounded task flow is being initiated.

  • After Listener: An EL expression for a Java method called after an ADF bounded task flow returns. It is used when the caller needs to know when an ADF 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 only have one before listener and one after listener.

In order for the task flow call after listeners to be called, control flow must return from the ADF bounded task flow using a control flow rule. If an end user leaves an ADF Bounded task flow using the browser Back button or other URL, task flow call after listeners will not be called. You must use a task flow definition finalizer to release all acquired resources and perform cleanup of an ADF bounded task flow that the end user left by clicking a browser back button. See Section 17.1, "Using Initializers and Finalizers" for more information.

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

  1. In the diagram of the calling ADF 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.

14.6.7 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 ADF bounded task flow using one of the methods described in Section 14.6.1, "How to Call an ADF Bounded Task Flow". 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 ADF bounded task flow. Each task flow reference consists of:

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

    Note:

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

Example 14-11 contains an example 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 14-11 Task Flow Reference

<adfc-config xmlns="http://xmlns.oracle.com/adf/Controller">
.
.
.
  <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>

14.6.8 What Happens at Runtime: Using a Task Flow Call Activity

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

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

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

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

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

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

  6. Invokes an ADF bounded task flow initializer method, if one is specified (see Section 17.1, "Using Initializers and Finalizers" for more information).

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

14.7 Using Task Flow Return Activities

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

A gray circle around an activity icon indicates that the activity is an exit point for an ADF bounded task flow. Each ADF bounded task flow can have zero to many task flow return activities. In Figure 14-8, the ADF bounded task flow contains two task flow return activities.

Figure 14-8 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 AddNewCust task flow return activity is registerCustomer. As shown in Figure 14-9, the calling task flow can match this outcome with a control flow case from-outcome. This handles control flow upon return from the called task flow.

Figure 14-9 Control Flow Case Specified on Calling Task Flow

Control Flow Case on Calliing Task Flow

The restore-save-point option specifies whether model changes made within an ADF bounded task flow should be discarded when exiting using a task flow return activity. If set to true, transactions are rolled back to the ADFm save point that was created when the ADF bounded task flow was originally entered. You can specify this option 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 17.2.1, "How to Enable Transactions in an ADF Bounded Task Flow"

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

  1. Drag a task flow return activity from the ADF Task Flow dropdown list in the Component Palette to the diagram for the ADF 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 will return an outcome to the caller when the ADF bounded task flow exits. You can specify only one outcome per task flow return activity. The calling ADF task flow should define control flow rules to handle control flow upon return. See Section 13.2.3, "How to Add Control Flows" for more information.

  5. In Property Inspector, click Behavior.

  6. In the Reentry dropdown list, choose either reentry-allowed or reentry-not-allowed.

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

    • reentry-not-allowed: Reentry of the ADF bounded task flow is not allowed. If you specify reentry-not-allowed on a task flow definition, 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 ADF bounded task flow is reentered by an end user clicking a browser back button. This selection applies only if reentry-outcome-dependent has been set on the ADF bounded task flow where the task flow return activity is located. For more information, see Section 17.3, "Reentering an ADF Bounded Task Flow".

  7. In the End Transaction dropdown, list choose either commit or rollback.

    • commit: commits the existing transaction to the database.

    • rollback: rolls back the transaction to what it was on entry of the called task flow. This has the same effect as cancelling 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 ADF bounded task flow.

  8. In the restore-save-point dropdown list, select true if:

    • if new-transaction is not selected on the bounded task flow bounded task flow on which the task flow return activity is located

    • ADFm model changes made within an ADF 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 ADF bounded task flow.

    For more information, see Section 17.2.1, "How to Enable Transactions in an ADF Bounded Task Flow".

14.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, the 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). See Section 17.11.1, "Specifying Save for Later Settings" for more information.

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 17.5, "Saving for Later" 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.

14.9 Using Parent Action Activities

An ADF bounded task flow running in an ADF region may need to trigger navigation of its enclosing view. The parent action activity allows an ADF bounded task flow to generate outcomes that are passed to its parent. The outcomes are used to navigate the ADF task flow containing the enclosing view's rather than navigating the ADF task flow of the ADF region.