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

• Section 15.1, "Introduction to Activity Types"

• Section 15.2, "Using View Activities"

• Section 15.3, "Using URL View Activities"

• Section 15.4, "Using Router Activities"

• Section 15.5, "Using Method Call Activities"

• Section 15.6, "Using Task Flow Call Activities"

• Section 15.7, "Using Task Flow Return Activities"

• Section 15.8, "Using Save Point Restore Activities"

• Section 15.9, "Using Parent Action Activities"

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 the ADF task flow overview 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 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

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 ADF Task Flow Activities and Control Flows

Icon	Component Name	Description
	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.
	Parent Action	Allows an ADF 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	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	Restores a previous persistent save point, including application state and data, in an application supporting save for later functionality. See Section 18.6, "Saving for Later" for more information.
	Task Flow Call	Calls an ADF bounded task flow from an ADF unbounded task flow or another bounded task flow. See Section 15.6, "Using Task Flow Call Activities" for more information.
	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 15.7, "Using Task Flow Return Activities" for more information.
	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	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 19.3, "Creating a Web Page" for more information about pages and page fragments.
	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	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.2.5, "How to Add a Wildcard Control Flow Rule" for more information.

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

Table 15-2 ADF Task Flow Diagram Annotations

Icon	Icon Name	Description
	Note	Adds a note to the task flow diagram. You can select the note in the diagram to add or edit text.
	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 ADF Regions".

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

Figure 15-2 View Activity

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

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

  
  

• 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 methods, see Section 27.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 an ADF 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 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 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 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 15-4 contains a sample URL for a bookmarkable view activity in an ADF 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:

• ADF bounded task flows

• View activities in an ADF unbounded task flow

• Addresses external to the current web application (for example, Google)

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.

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

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 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 29.3, "Enabling Oracle ADF Security".

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

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-4 shows how a router might be used to branch to multiple control flows leading from it to different activities.

Figure 15-4 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-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 15-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 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-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 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-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 15-5 Method Call Activity in employee-registration-task-flow

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

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

15.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 14.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 application, 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 27.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.

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.

   
   

   For more information about turning on the warning icons, see Section 14.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, 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-6 to build the EL expression for the method:

   1. In the Common 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-6. In Figure 15-6, for example, the addtoCart method and homeBean combine to form the EL expression shown at the top of the Expression Builder.

      Figure 15-6 EL Expression for Method in Expression Builder 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.

15.5.2 How to Specify Method Parameters and Return Values

You can specify parameters and return values for a method. Figure 15-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 15-7 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 an ADF 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 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 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 15.6.2, "How to Specify Input Parameters on a Task Flow Call Activity" for more information).

• 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 task flow definition once it is passed.

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

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

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

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

Example 15-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 15-10 contains the syntax for a URL to an ADF bounded task flow.

Example 15-10 URL Syntax for a 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.

15.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 and from the string representation used in a URL.

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

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

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

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

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

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

15.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 15-8, the ADF bounded task flow contains two task flow return activities.

Figure 15-8 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 15-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 15-9 Control Flow Case Specified on Calling 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 ADF Model 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 18.3.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 page 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 14.2.4, "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 18.4, "Reentering an ADF Bounded Task Flow".

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

   • 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 ADF bounded task flow.

8. In the restore-save-point dropdown list, select true when eith of the conditions holds:

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

   • ADF 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 18.3.1, "How to Enable Transactions in an ADF 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). See Section 18.14.1, "How to Specify 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 18.6, "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.

15.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'rather than navigating the ADF task flow of the ADF region.

• Parent outcome: Specifies a value passed to the parent viewport to navigate t he 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 doesn't navigate as a result of the parent outcome sent by the region and the region doesn't want to continue displaying the same view. If outcome is not specified, the region's viewId will remain unchanged.