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

15.1 Introduction to Activity Types

An activity represents a piece of work that is performed when the task flow runs. It displays in the task flow's overview 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 15-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 15-1

Figure 15-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 15-1 describes the types of activities and control flows you can add to a task flow.

Table 15-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 15.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 15.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 15.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 18.7, "Adding Save Points to a Task Flow" for more information.

Task flow call activity.

Task Flow Call

Calls a bounded task flow from an unbounded task flow or another bounded task flow. See Section 15.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 15.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 15.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 15.2, "Using View Activities" for more information. See Section 20.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 14.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 14.3.4, "How to Add a Wildcard Control Flow Rule" for more information.


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

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


15.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 17.1, "Introduction to Using Task Flows in ADF Regions".

Figure 15-2 shows the home view activity in the Fusion Order Demo application.

Figure 15-2 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.

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>

15.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. For more information, see Section 14.3.1, "How to Add Additional Activities 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.

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

  • Constant: The value of the Action attribute of the component is an action outcome, as shown in Figure 15-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.

    Figure 15-3 Edit Property dialog

    Edit Property Dialog for Action Attribute
  • Dynamic: The 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 operations, see Section 28.2, "Creating Command Components to Execute Methods".

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

    • 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 dropdown menu next to Action, 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.

15.2.2.2 What Happens When You Transition Between Activities

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

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

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

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

Instead of designating the view activity as bookmarkable, you can specify the redirect option. redirect causes 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 15.2.3.2, "How to Specify HTTP Redirect" for more information.

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

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

Example 15-4 Sample URL for Bookmarkable View Activity

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

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

15.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 ADF Controller and 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.

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

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

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

  • Bounded task flows

  • View activities in an unbounded task flow

  • Addresses external to the current web application (for example, http://www.oracle.com)

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

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

To add a URL view activity to a task flow:

  1. Drag a URL view activity from the ADF Task Flow page in the Component Palette 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 15-4 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 15-4 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 30.3, "Enabling Oracle ADF Security".

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

15.4 Using Router Activities

You can use a router activity to declaratively route control to activities based on logic specified in an EL expression. Figure 15-5 shows how a router might be used to branch to multiple control flows leading from it to different activities.

Figure 15-5 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:

  • expression: An EL expression evaluating to either true or false, for example, #{(pageFlowScope.welcomeUserRegistrationBean.userSelection eq 'Customer')}

    The first expression that evaluates to true is used to determine the corresponding outcome.

  • outcome: A value returned by the router activity if the EL expression evaluates to true, for example, newCustomer.

    If the router outcome matches a from-outcome on a control flow case, control passes to the activity that the control flow case points to. If none of the cases for the router activity evaluates to true, or if no cases are specified, the outcome specified in the router default outcome field (if any) is used.

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

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 15-5, 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 task flow that contains it. The router activity allows you to show more information about the condition on the 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 or add a routing condition later.

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 15-5, 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 to true, or if no cases are specified.

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

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

15.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 15-6, 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 15-6 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 14.1.3, "Control Flows". You can specify the outcome as either:

  • 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 specified as true, the outcome is based on calling the toString() method on the Java object returned by the method. For example, if toString() returns editBasicInfo, navigation goes to the editBasicInfo control flow case shown in Figure 15-6.

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

15.5.1 How to Add a Method Call Activity

Before you begin, you should have already created a bounded or unbounded task flow. For more information, see Section 14.2, "Creating a Task Flow". 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. For more information, see Section 28.3, "Setting Parameter Values Using a Command Component".

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.

To add a method call activity to a task flow:

  1. In the Component Palette, drag a method call activity from the ADF Task Flow page to the diagram for the 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 14.3.1, "How to Add Additional Activities 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 General 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, you must specify a binding container definition or page definition. See Section 12.6, "Working with Page Definition Files".

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

    1. In the General page of the Property Inspector, from the dropdown 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.

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

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

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

15.5.2 How to Specify Method Parameters and Return Values

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

Figure 15-8 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, add the parameters yourself.

To add method parameters:

  1. Follow the steps in Section 15.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 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.

15.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 15-8 shows how a method call to userRegistrationCreate appears in the XML source file for a bounded task flow.

Example 15-8 Call to userRegistrationCreate method

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

15.6 Using Task Flow Call Activities

You can use a task flow call activity to call a bounded task flow from either an unbounded or 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 flow 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 15.6.3, "How to Specify Input Parameters on a Task Flow Call Activity".

  • The value on the task flow call activity Input Parameter specifies where the value will be taken from within the calling task flow.

  • The value on the Input Parameter Definition for the called task flow specifies where the value will be stored within the called bounded task flow once it is passed.

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 16.5, "Specifying Return Values" for more information.

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

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, drag a Task Flow Call activity and drop it on the calling task flow.

  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 33.1.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 dropdown menu displayed to the right of the Dynamic Task Flow Reference property.

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

      Figure 15-9 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 15-9 Task Flow Call Activity That Invokes a Bounded Task Flow

      Task Flow Call Activity That Invokes a Bounded Task Flow

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

15.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 16.3, "How to Pass 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 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.

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 16.3, "How to Pass Parameters to an ADF Bounded Task Flow".

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

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 Activities 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 15.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 the URL of the remote web application.

    For example, the following example EL expression invokes a managed bean method that retrieves the server root and the application context:

    #{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 33.2, "Packaging a Reusable ADF Component into an ADF Library".

  8. Save and close the bounded task flow.

15.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 15-10 shows an example entries for a task flow call activity.

Example 15-10 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>

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 15-11 shows sample metadata entries that allow a bounded task flow to be invoked by a URL.

Example 15-11 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>

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

Example 15-12 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 15-13 describes the parts of the URL syntax to invoke a bounded task flow.

Example 15-13 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 15-13:

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

15.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. See Section 18.2, "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 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.

15.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 15.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 15-14 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 15-14 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 15-15 shows the metadata that JDeveloper generates for a dynamic task flow reference within a task flow call activity.

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

15.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 15.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 (see Section 18.2, "Using Initializers and Finalizers" for more information).

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

15.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 15-10 shows a bounded task flow with task flow return activities named Login and addNewCust.

Figure 15-10 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 15-11 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 15-11 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 18.3.1, "How to Enable Transactions in a Bounded Task Flow".

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

  1. Drag a task flow return activity from the ADF Task Flow page in the Component Palette to 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 14.3.3, "How to Add Control Flows" 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 18.4, "Reentering a Bounded Task Flow".

  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 18.3.1, "How to Enable Transactions in a Bounded Task Flow".

15.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 18.7, "Adding Save Points to a Task Flow" 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.

15.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 to generate outcomes that are passed to its 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.

  • Parent Outcome: Specifies a value passed to the parent viewport to navigate the enclosing view's task flow rather than navigating the region's task flow where the parent action activity is defined.

  • Outcome: Specifies a control flow outcome within the region after the parent outcome is queued to the parent.

    This is useful in cases where the parent does not navigate as a result of the parent outcome sent by the region and the region does not want to continue displaying the same view. If you do not specify a value for outcome, the region's viewId remains unchanged.

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

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

  • Method call

    You can drag and drop a data control operation from the Data Control panel onto a task flow to create a method call activity or onto an existing method call activity. In both cases, the method call activity binds to the data control operation.

  • Router

    Associating a page definition file with a router activity creates a binding container. At runtime, this binding container makes sure that the router activity references the correct binding values when it evaluates the router activity cases' EL expressions. Each router activity case specifies an outcome to return if its EL expression evaluates to true. For this reason, only add data control operations to the page definition file that evaluate to true or false.

  • Task flow call

    Associating a page definition file with a task flow call activity creates a binding container. At runtime, the binding container is in context when the task flow call activity passes input parameters. The binding container makes sure that the task flow call activity references the correct values if it references binding values when passing input parameters from a calling task flow to a called task flow.

  • View

    You cannot directly associate a view activity with a page definition file. Instead, you associate the page that the view activity references.

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 15-12 shows an example for each of the task flow activities.

Figure 15-12 Task Flow Activities Associated with Page Definition Files

Task Flow Activities with Page Definition Files

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

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 12.6, "Working with Page Definition Files".

15.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 15-16 shows a method call activity that references a CreateInsert action binding.

Example 15-16 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.