16 Using Parameters in Task Flows

This chapter describes how to specify parameters in view activities and in ADF bounded task flows.

This chapter includes the following sections:

Section 16.1, "Introduction to Parameters in Task Flows"
Section 16.2, "Passing Parameters to a View Activity"
Section 16.3, "How to Pass Parameters to an ADF Bounded Task Flow"
Section 16.4, "Sharing Data Control Instances"
Section 16.5, "Specifying Return Values"
Section 16.6, "Specifying EL Binding Expressions"

16.1 Introduction to Parameters in Task Flows

You can use view activity input page parameters as aliases. The alias allows you to map bounded task flow input parameters to page parameters. The view activity input page parameters map managed beans and any information available to the calling task flow to a managed bean on the page itself. To pass values out of view activities, store values in page flow scope or managed beans. For information about using view activities in a task flow, see Section 15.2, "Using View Activities".

For example, the page might specify #{pageFlowScope.empno} as a page parameter and a bounded task flow might specify #{pageFlowScope.employeeID} as the value of an input parameter definition.

The from-value on the view activity input page parameter would be #{pageFlowScope.employeeID} and the to-value would be #{pageFlowScope.empno}. This enables reuse of both the page definition and bounded task flow because you don't have to redefine parameters for every context in which each is used.

Other values contained within the task flow can be mapped to input page parameters, not just bounded task flow input parameter definition values.

16.2 Passing Parameters to a View Activity

Figure 16-1 illustrates how to specify an input page parameter mapping. You can pass a parameter to the Employee activity as a pageFlowScope value or a value on a managed bean. The Employee activity can pass a value to the Target activity by placing it within pageFlowScope or a managed bean to the Target activity, based on the EL expression you specified in the to-value.

Figure 16-1 Task Flow with Two Activities

To set an input page parameter value and retrieve it:

In the editor, open the task flow diagram.
In the task flow diagram, select the view activity.
In the Property Inspector, click Page Parameters.
In the Input Page Parameter section, click the Add icon.
Enter a from-value using an EL expression that, when evaluated, specifies where the input page parameter value will be passed from, for example, #{pageFlowScope.EmployeeID}.

The task flow shown in Figure 16-1 can set an input parameter definition value that the view activity can retrieve. To retrieve the parameter value, you can specify a from-value on the view activity that matches the Value specified for the ADF bounded task flow input parameter definition.
Enter a to-value using an EL expression that, when evaluated, specifies where the page associated with the view activity can retrieve the value of the input page parameter, for example, #{pageFlowScope.EmployeeNo}.

The to-value is the second part of the view activity input page parameter. It specifies where the page associated with the view can retrieve the value of the view parameter.

16.3 How to Pass Parameters to an ADF Bounded Task Flow

A called ADF bounded task flow can accept input parameters and can pass return values to the caller upon exit. See Section 16.5, "Specifying Return Values" for more information.

Note:

Instead of explicitly passing a data controls as parameters between task flows, you can simply share them by specifying the data-control-scope option on the called bounded task flow. For more information, see Section 16.4, "Sharing Data Control Instances".

To pass an input parameter to a bounded task flow, you must specify one or more:

Input parameters on the task flow call activity. These specify where the calling task flow will store parameter values.
Input parameter definitions on the called bounded task flow. These specify where the called bounded task flow can retrieve parameter values.

If you call a bounded task flow using a URL rather than a task flow call activity, you pass parameters and values on the URL itself. For more information, see Section 15.6.4, "How to Call a Bounded Task Flow Using a URL".

The input parameter name specified for each option will be the same in order to map input parameter values back into the called bounded task flow. The value for each corresponds to the mapping between where the value will be retrieved within the caller and the called task flow.

If you don't specify a value for the input parameter, the value defaults to #{pageFlowScope.parmname}, where parmname is the name of your parameter.

You can specify on the input parameter definition for the called bounded task flow whether an input parameter is required. If a required input parameter is not received, an error occurs (these are flagged at design time as well as at runtime). An input parameter definition that is identified as not required can be ignored during task flow call activity creation.

By default, all objects are passed by reference. Task flow call activity input parameters can be passed by reference only if managed bean objects are passed, not individual values. By default, primitive types (for example, int, long, or boolean) are passed by value.

The pass by value checkbox applies only to objects, not primitives and is used to override the default setting of passing by reference. Mixing the two, however, can lead to unexpected behavior in cases where parameters reference each other. If input parameter A on the task flow call activity is passed by value and if input parameter B on the task flow call activity is passed by reference, and B has a reference to A, the result can be two different instances of A and B.

Example 16-1 shows an input parameter definition specified on a a bounded task flow.

Example 16-1 Input Parameter Definition

<task-flow-definition id="sourceTaskflow">
.
.
.
   <input-parameter-definition>
      <name>inputParameter1</name>
      <value>#{pageFlowScope.parmValue1}</value>
      <class>java.lang.String</class>
   </input-parameter-definition>
.
.
.
</task-flow-definition>

Example 16-2 shows the input parameter metadata that would be specified on the task flow call activity that called the bounded task flow shown in Example 16-1.

Example 16-2 Input Parameter on Task Flow Call Activity

<task-flow-call id="taskFlowCall1">
.
.
.
    <input-parameter>
      <name>inputParameter1</name>
      <value>#{pageFlowScope.newCustomer}</value>
      <pass-by-value/>
    </input-parameter> 
.
.
.   
</task-flow-call>

Tip:

You can set parameters for a page using an ADF task flow rather than dropping a parameterized form from the data control panel or using a form with a method which takes parameters that are invoked using an invoke action. The first technique is a way of passing parameters to a page. The others are ways of consuming parameters on a page. If a page needs parameters, you should pass them by using task flow parameters or by setting scope variables.

The following steps describe passing an input parameter from a source task flow to a target bounded task flow using a task flow call activity. Although you can pass parameter values from any activity on the source task flow, the passed parameter in the steps below will contain the value of an input text field on a page in the source task flow.

Before you begin:

Create a calling and called task flow (see Section 14.2, "Creating a Task Flow" for more information). The caller can be a bounded or unbounded task flow. The called task flow must be a bounded task flow.
On the calling task flow, add the activities shown in Figure 16-2. The page associated with the view on the calling task flow should contain an input text field and a button. When an end user clicks the button on the JSF page, control should pass to the task flow call activity.

Figure 16-2 Calling Task Flow

To pass an input parameter to an ADF bounded task flow:

Select the input text component on the JSF page.
In the Property Inspector, enter a value for the input text component.

You can specify the value as an EL expression, for example #{pageFlowScope.inputValue}.
In the Application Navigator, double-click the name of the called task flow to open its diagram.
Click the Overview tab for the called task flow.
Click Parameters and expand the Input Parameter Definition node.
Click the Add icon next to Input Parameter Definition.
In the Name field, enter a name for the parameter, for example, inputParm1.
In the Value field, enter an EL expression where the parameter value is stored and referenced, for example, #{pageFlowScope.inputValue}.

In the Class field, enter a Java class for the input parameter definition. If you leave the Class field empty, its value is by default implicitly set to java.lang.String.

Best Practice:

Always specify a value in the Class field explicitly even when the value is java.lang.String.

This ensures that a value or object of the correct type is passed to the input parameter. If the bounded task flow is implemented using a task flow call activity, as an ADF region or an ADF dynamic region, input parameter values accept #{bindings.bindingId.inputValue} binding EL expression syntax. For more information, see Section 16.6, "Specifying EL Binding Expressions".

If Class is implicitly set to java.lang.String and the #{bindings.bindingId} EL expression syntax is used, the parameter values that are passed are the actual binding objects instead of the values of the bindings. As a result, the bindings are evaluated within the wrong context: the context of the task flow call, ADF region, or ADF dynamic region, instead of the context of the page. Multiple data control instances are created, eventually setting the wrong data control context in the frame.

In the editor, open the diagram for the calling task flow.
In the Application Navigator, drag the called ADF bounded task flow and drop it on top of the task flow call activity that is located on the calling task flow.

Dropping a bounded task flow on top of a task flow call activity in a diagram automatically creates a task flow reference to the bounded task flow. As shown in Figure 16-3, the task flow reference contains the bounded task flow ID and a document name. The document name points to the XML source file that contains the ID.

Figure 16-3 Task Flow Reference in Property Inspector
In the Property Inspector for the task flow call activity, click Parameters and expand the Input Parameters section.
Enter a name that identifies the input parameter.

Because you dropped the bounded task flow on a task flow call activity having defined input parameters, the name should be already be specified. You must keep the same input parameter name.
Enter a parameter value, for example, #{pageFlowScope.parm1}.

The value on the task flow call activity input parameter specifies where the calling task flow will store parameter values.

The value on the input parameter definition for the called task flow specifies where the value will be retrieved from for use within the called bounded task flow once it is passed.
At runtime, the called task flow is able to use the input parameter. Since you specified pageFlowScope as the value in the input parameter definition for the called task flow, you can use the parameter value anywhere in the called ADF bounded task flow. For example, you can pass it to a view activity on the called bounded task flow. For more information, see Section 15.2.2.2, "What Happens When You Transition Between Activities".

16.4 Sharing Data Control Instances

You can share data control instances between task flows. For more information about data controls, see Section 12.2, "Exposing Application Modules with Oracle ADF Data Controls". A called bounded task flow can reference and modify the value of the data control owned by its calling task flow. This allows the called task flow to share the same data control instance as its parent. Both task flows look in the same place, the data control frame, to get the data control instance.

In the Fusion Order Demo application, for example, you may have a value that is used to display a row in a product table on an ADF page. Clicking a button on the page updates a shopping cart form in an ADF region. The form updates with the product name, based on the selected value in the table.

A data control frame is the container associated with a task flow that contains data control instances. A bounded task flow's transactions operate on data control instances in the data control frame. A new DataControlFrame is created for each task flow that is entered. This results in each ADF task flow having its own unique instance of any data control it uses.

To specify whether data control instances are shared between the calling and called task flows, you must set a data-control-scope value of either shared or isolated on the called bounded task flow. shared is the default value.

If a shared data control scope is specified on both the calling and called bounded task flow, the data control frame used will be the one for whoever called the calling task flow. In Example 16-3, the data control frame for Bounded Task Flow A would be also used by both B and C.If an isolated data control scope is specified on both the calling and called bounded task flow, they will both use their own data control frames.

Example 16-3

Bounded Task Flow A - isolated
  Bounded Task Flow B - shared
    Bounded Task Flow C - shared

Note:

An ADF bounded task flow with a shared data-control-scope that is called using a URL cannot share data control instances with the calling task flow. If the called bounded task flow specifies shared as the data-control-scope, ADF Controller will throw an exception.

A caller of a bounded task flow can share its caller's data control instances to any depth. For example, task flow A can share data control instances with called bounded task flow B. Called bounded task flow C can share the same data control instances.

An ADF bounded task flow specifying a shared data control scope used within an ADF region shares the data control instances of the task flow in the parent view port For more information, see Section 17.1.10.2, "View Port".

A new data control frame is created for the ADF unbounded task flow in each RootViewPort's call stack. Each browser window is isolated from all other browser windows within the same HTTP session. The browser windows do not share data control instances. However, if an end user uses the Ctrl+N keys to open a new browser window, the two windows have the same server-side state and share data control instances.

For performance reasons, data controls are not instantiated until needed.

Before you begin:

Create a calling and called task flow

To share a data control between task flows:

In the Property Inspector for the called task flow, select Behavior.

In the data-control-scope list, select shared.

The called task flow will share all data control instances with its caller.

Note:

After you set the data-control-scope, you may also need to check the transaction option for the bounded task flow to determine if there are any interactions between the options. For more information, see, Section 16.4.1, "What You May Need to Know About Managing Transactions".

The data-control-scope on the calling bounded task flow should be set to isolated if you don't want it to be dependent on any bounded task flow above it. By default, the data-control-scope for all bounded task flows is shared.

16.4.1 What You May Need to Know About Managing Transactions

Data control instances cannot be shared across more than one transaction at the same time. If your task flow is involved in managing transactions, the value you select for the data-control-scope option may affect the transaction option settings for a bounded task flow. Table 16-1 describes how these options interact.

Table 16-1 Interaction of transaction and data-control-scope option settings

transaction Option	data-control-scope Isolated Option	data-control-scope shared Option
`requires-existing-transaction`	Invalid.	If a transaction is not already open, an exception is thrown. The existing transaction is never committed.
`requires-transaction`	Always begins a new transaction.	Begins a new transaction if one is not already open.
`new-transaction`	Always begins a new transaction.	Begins a new transaction if one is not already open. If one is already open, an exception is thrown.
`<default> (none)`	A new data control frame is created without an open transaction.	NA

16.5 Specifying Return Values

As shown in Figure 16-4, a task flow return activity causes the ADF bounded task flow to return to the task flow that called it. The called bounded task flow can pass return values back to the calling task flow.

Figure 16-4 ADF Bounded Task Flow Returning to a Calling Task Flow

A bounded task flow returning to its caller.

As shown in Figure 16-5, the values are returned to the calling task flow.

Figure 16-5 ADF Unbounded Task Flow Calling a Bounded Task

An unbounded task flow calling a bounded task flow.

To return a value, you must specify:

Return value definitions on the called bounded task flow. These specify where the return value is to be taken from upon exit of the called bounded task flow.
Return values on the task flow call activity in the calling task flow. These specify where the calling task flow can find return values

The caller of the bounded task flow can choose to ignore return value definition values by not identifying any task flow call activity return values back to the caller.

Return values on the task flow call activity are passed back by reference. Nothing inside the ADF bounded task flow will still reference them, so there is no need to pass by value and make a copy.

Before you begin the following steps:

Create a calling task flow (can be either bounded or unbounded) and a target bounded task flow

To specify a return value for a called ADF bounded task flow:

Open the ADF bounded task flow that will be called in the overview editor.
Click Parameters and expand the Return Value Definitions section.
Click the Add icon next to Return Value Definitions.
In the Name field, enter a name to identify the return value, for example, Return1.
In the Value field, enter an EL expression that specifies where the return value is to be taken from upon exit of the called bounded task flow, for example, #{pageFlowScope.ReturnValueDefinition}.
In the task flow overview editor, open the calling ADF task flow.
In the Component Palette, drag the task flow call activity from the ADF Task Flow list and drop it on the diagram for the ADF calling task flow.
In the task flow diagram, select the task flow call activity.
In the Property Inspector, click Parameters and expand the Return Values section.

In the name field, enter a name to identify the return value, for example, Return1.

The name of the return value must match the name of the return value definition on the called bounded task flow.

Tip:

If you drop the bounded task flow that you intend to call on the task flow call activity, the name field will already be specified. Therefore, the name field for the return value will automatically match the name of the return value definition on the called bounded task flow.

In the value field, enter an EL expression that specifies where the calling task flow can find return values, for example, #{pageFlowScope.ReturnValue}.

16.6 Specifying EL Binding Expressions

If a bounded task flow is implemented using a task flow call activity, as an ADF region or as an ADF dynamic region, you can specify parameter values using standard EL expression syntax. For example, you can specify parameters using #{bindings.bindingId.inputValue} or #{bindings.bindingId} or simply #{inputValue} syntax.

Example 16-4 shows an example of a task flow binding for an ADF region.

Example 16-4 ADF Region taskFlow Binding

<taskFlow id="Department1" taskFlowId="/WEB-INF/Department.xml#Department"
              xmlns="http://xmlns.oracle.com/adf/Controller/binding"
              Refresh="ifNeeded">
    <parameters>
        <parameter id="DepartmentId" value="#{bindings.DepartmentId.inputValue}"
                   xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
     </parameters>
</taskFlow>

Appending inputValue to the parameter value binding EL expression ensures that the parameter is assigned the value of the binding rather than the actual binding object.

If you use the syntax in Example 16-4 without appending inputValue #{bindings.bindingId}, the binding object (not the value of the binding) is passed. Therefore, the binding will end up being evaluated within the wrong context (the context of the task flow call, ADF region, or ADF dynamic region instead of the context of the page) and multiple data control instances will be created, eventually setting the wrong data control context in the frame.