26 Using Task Flows as Regions

This chapter describes how to render ADF task flows in pages or page fragments using ADF regions in your Fusion web application. Key features such as the ability to specify parameters, how to refresh or activate an ADF region, navigate to a parent page, and create dynamic ADF regions are also described.

This chapter includes the following sections:

• About Using Task Flows in ADF Regions

• Creating an ADF Region

• Specifying Parameters for an ADF Region

• Specifying Parameters for ADF Regions Using Parameter Maps

• Configuring an ADF Region to Refresh

• Configuring Activation of an ADF Region

• Navigating Outside an ADF Region's Task Flow

• Configuring Transaction Management in an ADF Region

• Creating ADF Dynamic Regions

• Adding Additional Task Flows to an ADF Dynamic Region

• Configuring a Page To Render an Unknown Number of Regions

• Handling Access to Secured Task Flows by Unauthorized Users

• Creating Remote Regions in a Fusion Web Application

About Using Task Flows in ADF Regions

An ADF page fragment or a JSF page with af:region tag is the ADF region where you can execute a bounded task flow. You can use these ADF regions to add pieces of application functionality in the bounded task flow and reuse this packaged functionality throughout the application. The ADF regions are not dependent on a parent page.

You can execute a bounded task flow in a JSF page or page fragment (.jsff) by using an ADF region. A primary reason for executing a bounded task flow as an ADF region is reuse. You can isolate specific pieces of application functionality in a bounded task flow and an ADF region in order to reuse it throughout the application. You can extract, configure, and package application functionality within a bounded task flow so that it can be added to other pages using an ADF region. ADF regions can be reused wherever needed, which means they are not dependent on a parent page. This also means that you can isolate the presentation of the parent pages from the ADF region; menus, buttons, and navigation areas are not affected by what is displayed in the ADF region. If you modify a bounded task flow, the changes apply to any ADF region that uses the task flow.

An ADF region comprises the following:

• An af:region tag that appears in the page or page fragment where you render the region

• An instance object that implements RegionModel from the following package:

  oracle.adf.view.rich.model

  For more information about RegionModel, see the Java API Reference for Oracle ADF Faces

• One or other of the following:

  • A task flow binding (taskFlow) in the page definition that identifies the bounded task flow to use in the ADF region

  • A multi task flow binding (multiTaskFlow) in the page definition that identifies a list of bounded task flows to use in the ADF region

When first rendered, the ADF region's content is that of the first view activity in the bounded task flow. The view activities used in the bounded task flow must be associated with page fragments, not pages.

You can pass values to the ADF region using task flow binding input parameters or contextual events. In addition, you can configure the task flow binding's parametersMap property to determine what input parameters the task flow binding passes from the bounded task flow to the ADF region.

ADF regions can be configured so that you determine when the region activates or refreshes. You can also configure an ADF region and a bounded task flow so that navigation control stops in the bounded task flow and passes to the page that contains the ADF region. Finally, you can create dynamic regions (ADF dynamic regions) where the task flow binding determines at runtime what bounded task flow renders in the region and configure a dynamic region link so that end users can change the bounded task flow that renders in the ADF dynamic region at runtime.

Figure 26-1 shows how an ADF region references a bounded task flow using a task flow binding in the page definition file of the page that hosts the ADF region.

Figure 26-1 ADF Region Referencing a Bounded Task Flow

Description of "Figure 26-1 ADF Region Referencing a Bounded Task Flow"

About Page Fragments and ADF Regions

A page fragment is a JSF document (file extension is .jsff) that renders as content in another JSF page. A page fragment should not have more than one root component. Wrapping multiple root components in a single root component helps you to optimize the display performance of the page fragment. In addition, if a page fragment has only one visual root component and a popup component (which is invisible to end users until invoked), consider wrapping these components in a single root component. For example, place the popup component in a panelStretchLayout component's bottom facet with the bottomHeight attribute set to 0 pixels.

If a page fragment has more than one root component, the Fusion web application logs a message at runtime, as shown in the following example, where r1 identifies the ADF region that renders the page fragment.

<RegionRenderer> <encodeAll> The region component with id: r1 has detected a page
 fragment with multiple root components. Fragments with more than one root
 component may not display correctly in a region and may have a negative impact
 on performance. It is recommended that you restructure the page fragment to have
 a single root component.

Apart from having only one root component element, a page fragment must not contain any of the following tags:

• <af:document>

• <f:view>

• <f:form>

• <html>

• <head>

• <body>

These tags can only appear once in a document and do not support nesting in a JSF page. For example, a page fragment embedded in a page cannot have an <html> tag because the JSF page already has one.

The following example shows a simple page fragment. Unlike a JSF page, it contains no <f:view> or <f:form> tags.

<?xml version='1.0' encoding='UTF-8'?>
<ui:composition xmlns:ui="http://java.sun.com/jsf/facelets"
                     xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
  <af:button text="button 1" id="b1"/>
</ui:composition>

You must nest a page fragment that you include in another JSF page within a region (af:region tag). A bounded task flow that you add to a JSF page as a region cannot call pages; it must call page fragments.

About View Ports and ADF Regions

A view port is a display area capable of navigating independently of other view ports. A browser window and an ADF region are both examples of view ports. The root view port displays the main page in a browser window. The root view port may have child view ports, for example, regions on the page, but does not have a parent view port.

Java classes that implement the ViewPortContext interface in the oracle.adf.controller package get you more information about view ports. For more information, see the Java API Reference for Oracle ADF Controller.

Task Flows and ADF Region Use Cases and Examples

Figure 26-2 shows the General Information page fragment (GeneralInfo.jsff) from the edit-customer-task-flow-definition.xml task flow in the Summit sample application for ADF task flows. This task flow renders in an ADF region and displays information about customers in a series of page fragments that authenticated users can navigate through and edit using the provided controls. For more information about creating this type of region, see Creating an ADF Region.

Figure 26-2 ADF Region in the Summit ADF Task Flow Sample Application

Figure 26-2 also shows links (labeled Register as Employee and Register as Customer) that invoke different task flows in the ADF dynamic region that the showDetailItem component labeled Welcome renders. For more information about creating this type of region, see Creating ADF Dynamic Regions.

Figure 26-3 shows the edit-customer-task-flow-definition.xml task flow in JDeveloper. It contains three view activities to display information about customers to end users.

Figure 26-3 Edit Customer Task Flow in ADF Summit Application for ADF Task Flows

Additional Functionality for Task Flows that Render in ADF Regions

You may find it helpful to understand how a task flow that renders in an ADF region interacts with other task flow and ADF functionality. Following are links to other functionality that may be of interest.

• You can set security on a bounded task flow that displays in an ADF region and associated page definitions. If an end user displays a page that contains an ADF region that the user is not authorized to view, the contents of the ADF region do not display. No authentication mechanism is triggered. For more information, see Enabling ADF Security in a Fusion Web Application.

• Task flows can invoke managed beans. For more information about managed beans, see Using a Managed Bean in a Fusion Web Application.

• You can use contextual events to exchange information with a bounded task flow. For more information, see Using Contextual Events.

Creating an ADF Region

You can create an ADF region in a JSF Page or an ADF page fragment by adding af:region tag. The ADF region must contain at least one view activity or one task flow call activity to the page where you want to render the ADF region.

You create an ADF region by dragging and dropping a bounded task flow that contains at least one view activity or one task flow call activity to the page where you want to render the ADF region. This makes sure that the ADF region you create has content to display at runtime.

The bounded task flow's view activities must be associated with page fragments (.jsff). If you attempt to drag and drop a bounded task flow that is associated with pages rather than page fragments, JDeveloper does not display the context menu that allows you to create an ADF region. You can convert a bound task flow that uses pages to use page fragments. See How to Convert Bounded Task Flows .

The context menu that appears to create an ADF region presents options to create a nondynamic and a dynamic region. A dynamic region (ADF dynamic region) determines the bounded task flow that it renders at runtime. For information about creating an ADF dynamic region, see Creating ADF Dynamic Regions. You determine at design time the bounded task flow that a nondynamic region (ADF region) displays.

How to Create an ADF Region

Drag a bounded task flow from the Applications window to the page where you want to render an ADF region.

Before you begin:

It may be helpful to have an understanding of the requirements for a bounded task flow that you use in an ADF region. For more information, see Creating an ADF Region.

You may also find it helpful to understand functionality that can be added using other task flow features and ADF region features. For more information, see Additional Functionality for Task Flows that Render in ADF Regions.

You will need to complete these tasks:

• Create a bounded task flow with one or more view activities associated with page fragments or one task flow call activity to a task flow with view activities.

  For more information, see Creating a Task Flow.

• Create a JSF page to host the ADF region.

  For more information, see the "How to Create JSF Pages" section of Developing Web User Interfaces with Oracle ADF Faces.

To create an ADF region:

1. In the Applications window, double-click the JSF page where you want to locate the ADF region.
2. From the Applications window, drag and drop the bounded task flow onto the JSF page, and from the context menu, choose Create > Region.
3. If the Edit Task Flow Binding dialog appears, click OK.

   The Edit Task Flow Binding dialog appears if the bounded task flow that you drop on the JSF page has an input parameter defined, as described in How to Pass an Input Parameter to a Bounded Task Flow.

   For more information about specifying parameters for an ADF region, see Specifying Parameters for an ADF Region.

   Figure 26-4 Edit Task Flow Binding Dialog for an ADF Region

   
   Description of "Figure 26-4 Edit Task Flow Binding Dialog for an ADF Region"
4. In the Structure window, right-click the node for the ADF region that you added (af:region) and choose Go to Properties.
5. Review or modify (as appropriate) the following fields which JDeveloper automatically populates with default values in the Properties window for the ADF region:

   • Id: An ID that the JSF page uses to reference the ADF region, for example, r1.

   • Value: An EL reference to the ADF region model, for example, #{bindings.region1.regionModel}. This is the region model that describes the behavior of the region.

   • Rendered: If true (the default value), the ADF region renders when the JSF page renders.

6. For information about how to map parameters between the view activity associated with the JSF page and the ADF region, see Specifying Parameters for an ADF Region.

What Happens When You Create an ADF Region

When you drop a bounded task flow onto a JSF page to create an ADF region, JDeveloper adds an af:region tag to the page. The af:region tag references an object that implements RegionModel. The following example shows the af:region tag that appears in the Customers.jsff page fragment of the Summit ADF task flow sample application.

<af:region value="#{bindings.editcustomertaskflowdefinition1.regionModel}"
                   id="r2"/>

JDeveloper also adds a task flow binding to the page definition file of the page that hosts the ADF region. The following example shows a sample of the metadata that JDeveloper adds. The task flow binding provides a bridge between the ADF region and the bounded task flow. It binds a specific instance of an ADF region to its associated bounded task flow and maintains all information specific to the bounded task flow. The taskFlowId attribute specifies the directory path and the name of the source file for the bounded task flow.

<taskFlow id="editcustomertaskflowdefinition1"
    taskFlowId="/WEB-INF/flows/edit-customer-task-flow-definition.xml#edit
    -customer-task-flow-definition"
    activation="deferred" 
    xmlns="http://xmlns.oracle.com/adf/controller/binding"/>

The bounded task flow preserves all of the data bindings when you drop it on the JSF page. At runtime, a request for a JSF page containing an ADF region initially handles like any other request for a JSF page. As the JSF page definition executes, data loads in to the JSF page. When the component tree for the parent JSF page encounters the <af:region> tag, it executes it in order to determine the first page fragment of content to display. Once it determine the first page fragment of content, it adds the appropriate UI components from the page fragment to the component tree for the parent JSF page.

The task flow binding creates an object for its task flow that implements the following interface in order to get the current view activity:

oracle.adf.controller.ViewPortContext

The task flow binding's taskFlowId attribute can also reference an EL expression that evaluates to one of the following:

• java.lang.String

• oracle.adf.controller.TaskFlowId

You use this capability if you create an ADF dynamic region. For more information, see Creating ADF Dynamic Regions.

Specifying Parameters for an ADF Region

You may need to transfer values to the ADF region for the input parameters defined for a bounded task flow in that region. For this, you can the input parameters (defined in the ADF region) to the task flow binding the ADF region. You can also access the input parameters in the memory scopes, managed beans, or the ADF binding layer by using EL expressions in the ADF region.

You can make input parameters that you defined for a bounded task flow available to an ADF region by adding them to the task flow binding that the ADF region references. Use EL expressions to reference input parameters available in memory scopes, managed beans, or the ADF binding layer.

Specifying input parameters is one method of providing information to an ADF region. An alternative method is to use contextual events. The nature of the information that you want to provide to the ADF region determines the method you choose to provide the information. For example, choose:

• Input parameters if the required information is at the beginning of the task flow and a change in the value of this information requires a restart of the task flow.

  For example, you have a page that contains a table of employees. An ADF region on that page contains a task flow to enroll a selected employee in a benefits program. A change in the selected employee requires that you restart the benefits enrollment task flow from the beginning for the newly selected employee. Using input parameters to the task flow is the right decision for this use case.

  You can pass input parameters by reference or by value. If you pass by reference, an update on the main page for the selected employee's information, such as last name, is automatically reflected in the task flow running in the ADF region without restarting the task flow.

• Contextual events if you can only determine the information to exchange after the start of a task flow and a change in the information does not require a restart of the task flow. For example, the Inventory Control tab in the Summit ADF task flow sample application uses contextual events to display the appropriate chart for product inventory in one region in response to the product that a user selects in another region. For more information, see Using Contextual Events.

For information about creating an ADF region and adding task flow bindings, see Creating an ADF Region. For information about how to define an input parameter for a bounded task flow, see Passing Parameters to a Bounded Task Flow.

How to Specify Parameters for an ADF Region

Use EL expressions to specify parameters available in memory scopes, managed beans, or the ADF binding layer as input for the ADF region.

Before you begin:

It may be helpful to have an understanding of the requirements for specifying parameters for an ADF region. For more information, see Specifying Parameters for an ADF Region.

You may also find it helpful to understand functionality that can be added using other task flow features and ADF region features. For more information, see Additional Functionality for Task Flows that Render in ADF Regions.

To specify input parameters for an ADF region:

1. In the Applications window, right-click the JSF page that holds the ADF region and choose Go to Page Definition.
2. In the overview editor, click the Bindings and Executables navigation tab, select the task flow binding for which you want to specify parameters and click the Edit icon.
3. In the Edit Task Flow Binding dialog, write EL expressions that retrieve the values of each input parameter you want to specify for the ADF region. Note that you must write an EL expression for parameters that you defined as required. For example, write an EL expression similar to the following:

   #{pageFlowScope.inputParameter1}

   Figure 26-5 shows the Edit Task Flow Binding dialog where the Input Parameters section lists a number of input parameters that were defined for the bounded task, as described in Passing Parameters to a Bounded Task Flow.

   Note:

   You can write an EL expression that references a list of input parameters specified in a managed bean using the Input Parameters Map field of the Edit Task Flow Binding dialog. For more information about implementing this functionality, see Specifying Parameters for ADF Regions Using Parameter Maps.

   Figure 26-5 Edit Task Flow Binding Dialog

   
   Description of "Figure 26-5 Edit Task Flow Binding Dialog"
4. Click OK.

What Happens When You Specify Parameters for an ADF Region

JDeveloper writes entries that are child elements of the taskFlow element in the page definition of the JSF page, as illustrated in the following example.

<taskFlow id="tflow_tf11"
   taskFlowId="/WEB-INF/tflow_tf1.xml#tflow_tf1"
   activation="deferred" 
   xmlns="http://xmlns.oracle.com/adf/controller/binding">
  <parameters>
    <parameter id="inputParameter1"
      value="#{pageFlowScope.inputParameter1}"/>
    <parameter id="inputParameter2"
      value="#{pageFlowScope.inputParameter2}"/>
  </parameters>
</taskFlow>

At runtime, the values specified by the EL expression in the value attribute are passed to the ADF region.

Specifying Parameters for ADF Regions Using Parameter Maps

A parameter map object on a managed bean specifies the keys mapping to the values that you want to input to the ADF region. As you define the parameters in the parameter maps, the space required to specify them in the task flow binding element or to specify them in multiple task flow bindings in the page definition for the pages is reduced.

In addition (or as an alternative) to listing all the input parameters on the task flow binding, as described in Specifying Parameters for an ADF Region, you can use the parametersMap property of the task flow binding to specify a parameter map object on a managed bean. The parameter map object that you reference must be of a type that implements the following interface:

java.util.Map

The parameter map object that you reference specifies keys that map to the values you want to input to the ADF region. Using this approach reduces the number of parameter child elements that appear under the task flow binding (taskFlow) element or the multi task flow binding (multiTaskFlow) in the page definition for the page. This approach also allows you more flexibility in determining what input parameters pass to the ADF region. In particular, it provides a way to pass parameters to ADF dynamic regions as the number of input parameters can differ between the different task flow bindings in an ADF dynamic region. See Creating ADF Dynamic Regions.

You can configure an ADF region or an ADF dynamic region's task flow binding to reference a parameter map. You can also configure a multi task flow binding to reference a parameter map. Make sure that the name of an input parameter you define for a bounded task flow matches the name of a key that you define in the parameter map object.

If you specify a parameter with the same id attribute in a <parameter> element and in a <parametersMap> element, the <parametersMap> element always takes precedence. This is because the <parametersMap> element may need to override the static value of the parameter if you create an ADF dynamic region, as described in Creating ADF Dynamic Regions.

How to Create a Parameter Map to Specify Input Parameters for an ADF Region

You configure the task flow binding's parametersMap property to reference the parameter map object that defines the key-value pairs you want to pass to the ADF region.

Before you begin:

It may be helpful to have an understanding of the configuration options available to you when passing input parameters to an ADF region. For more information, see Specifying Parameters for ADF Regions Using Parameter Maps.

You may also find it helpful to understand functionality that can be added using other task flow and ADF region features. For more information, see Additional Functionality for Task Flows that Render in ADF Regions.

You will need to complete this task:

• Create a managed bean or edit an existing managed bean so that it returns an object that implements the java.util.Map interface. Configure the managed bean so the object returns key-value pairs with the values that you want to pass to the ADF region. For more information about managed beans, see Using a Managed Bean in a Fusion Web Application.

To create a parameter map to specify input parameters for an ADF region:

1. In the Applications window, right-click the JSF page that holds the ADF region and choose Go to Page Definition.
2. In the overview editor, click the Bindings and Executables navigation tab, select the task flow binding or multi task flow binding for which you want to specify a parameter map, and then click the Edit icon.

   The type of task flow binding that you select determines the dialog that appears.

3. In the Edit Task Flow Binding dialog or the Edit Multi Task Flow Binding dialog, select Expression Builder from the Input Parameters Map dropdown menu.
4. Write or build an EL expression that references a parameter map. For example, write an EL expression similar to the following:

   #{pageFlowScope.userInfoBean.parameterMap}

5. Click OK.

What Happens When You Create a Parameter Map to Specify Input Parameters

At runtime, the task flow binding or multi task flow binding evaluates the EL expression specified for its parametersMap property. It returns values to the ADF region from the managed bean for keys that match the name of the input parameters defined for the bounded task flow that render in the ADF region.

Example 26-1 shows code snippets from a managed bean that puts two values (isLoggedIn and principalName) into a parameter map named parameterMap.

Figure 26-6 shows the Edit Task Flow Binding dialog after you close the Expression Builder dialog, having specified the parameter map object (parameterMap) shown in Example 26-1. The Input Parameters field in the Edit Task Flow Binding dialog lists the input parameters defined for the bounded task flow associated with this ADF region (checkout-flow). The task flow binding retrieves the values for these parameters from the managed bean shown in Example 26-1.

Figure 26-6 EL Expression Referencing Parameter Map on Task Flow Binding

The following example shows the metadata that appears for the task flow binding in the page definition file of the page that renders the ADF region. The metadata for the task flow binding references both the bounded task flow (taskFlowId attribute) and the managed bean (parametersMap).

<taskFlow id="checkoutflow1"
              taskFlowId="/WEB-INF/checkout-flow.xml#checkout-flow"
              activation="deferred"
              xmlns="http://xmlns.oracle.com/adf/controller/binding"
              parametersMap="#{pageFlowScope.userInfoBean.parameterMap}"/>

You specify the <parameterMap> element in the page definition.

Note:

If you specify Refresh="ifNeeded", parameters are not supported in the <parameterMap> element. The only condition that determines whether the region need to be refreshed is the boolean value returned by the evaluation of RefreshCondition. For more information, see What You May Need to Know About Configuring an ADF Region to Refresh.

Example 26-1 Managed Bean Defining a Parameter Map

import java.util.HashMap;
import java.util.Map;
 
public class UserInfoBean {
    private Map<String, Object> parameterMap = new HashMap<String, Object>();
 
    public Map getParameterMap() {
        
        parameterMap.put("isLoggedIn", getSecurity().isAuthenticated());
        parameterMap.put("principalName", getSecurity().getPrincipalName());
        return parameterMap;
    }
}

Configuring an ADF Region to Refresh

The ADF region refreshes when the parent page binding is first displayed. For future refreshes you must configure one of these task flow binding attributes: taskFlowID, Refresh or RefreshCondition, RefreshCondition="#{EL.expression}", or Refresh="ifNeeded".

You can configure when an ADF region refreshes and whether it invokes a task flow. An ADF region can only invoke a task flow when the ADF region is in an active state. An ADF region in an inactive state cannot invoke a task flow and returns a null value for the ID of the referenced task flow to the parent page.

How to Configure the Refresh of an ADF Region

You set values for the task flow binding of the task flow associated with the ADF region to determine when an ADF region switches from an inactive to an active state and to determine when an ADF region refreshes.

Before you begin:

It may be helpful to have an understanding of the requirements for a bounded task flow that you use in an ADF region. For more information, see Configuring an ADF Region to Refresh.

You may also find it helpful to understand functionality that can be added using other task flow features and ADF region features. For more information, see Additional Functionality for Task Flows that Render in ADF Regions.

To configure the refreshing of an ADF Region:

1. In the Applications window, select the page that contains the ADF region, right-click and choose Go to Page Definition.
2. In the page definition file, select the task flow binding or multi task flowing binding in the Executables section, as illustrated in Figure 26-7.

   Figure 26-7 Task Flow Binding

   
   Description of "Figure 26-7 Task Flow Binding"
3. Choose the appropriate option to refresh the ADF region.

   • Refresh if the value of a task flow binding parameter changes.

     In the Properties window, select ifNeeded from the Refresh dropdown list.

     Do not select ifNeeded if you want to set a value for the RefreshCondition property and can guarantee that the property evaluates to true only once. The RefreshCondition property will not be evaluated if you select ifNeeded for the Refresh property.

   • Refresh if a condition that you specify returns true. In the Properties window, write an EL expression that guarantees that true is returned only once and that returns a boolean in the RefreshCondition field. If the EL expression returns true, the ADF region refreshes. If the EL expression returns true more than once for each task flow refresh, page content may fail to load.

   Note:

   Use ifNeeded when possible. The usage of RefreshCondition is not recommended unless there is a good reason. For example, use RefreshCondition only when the application passes parameters to the task flow binding using a dynamic parameter map and when the application can guarantee RefreshCondition evaluates true exactly once when it refreshes the ADF task flow. For more information, see What You May Need to Know About Configuring an ADF Region to Refresh.

4. In the Properties window, select a value from the activation dropdown list, as described in the following list:

   • conditional: activates the ADF region if the EL expression set as a value for the task flow binding active property returns true.

   • deferred: select this option if your application uses Facelets XHTML pages in the view layer and you want to activate the ADF region when a Facelets XHTML page first requests a viewID. If your application uses JSP technology in the view layer, selecting this option has the same effect as selecting immediate (the ADF region activates immediately) provided that the parent component for the ADF region is not a popup or panelTabbed component that has its childCreation attribute set to deferred. If this latter scenario occurs, the parent component (popup or panelTabbed) determines behavior.

     Use this option if your application uses Facelets XHTML pages. For more information about Facelets with ADF Faces, see the "Getting Started with ADF Faces and JDeveloper" chapter in Developing Web User Interfaces with Oracle ADF Faces.

   • immediate: activates the ADF region immediately. This is the default value.

   The value that you select in the dropdown list determines when an ADF region switches from an inactive to an active state. An ADF region must have an active state before it can invoke a task flow.

5. If you selected conditional as the value for the activation property, write an EL expression that returns a boolean value at runtime for the active property. If the EL expression returns true, the ADF region invokes the task flow.
6. (Optional) For the processRegionForRefresh property, write an EL expression to determine if the region should participate in a refresh operation. If the EL expression evaluates to false, the region binding and its children will not be refreshed. This check is performed before the region activation, the RefreshCondition property, or input parameters are evaluated. If the EL expression evaluates to true or if you do not write an EL expression for the processRegionForRefresh property, the region will be included in refresh operations and the behavior that you specify for the activation dropdown list will be invoked. Writing an EL expression for the processRegionForRefresh property does not prevent the region from being rendered.

What You May Need to Know About Configuring an ADF Region to Refresh

An ADF region initially refreshes when the parent JSF page on which the region is located first displays. During the initial refresh, any ADF region task flow binding parameter values are passed in from the parent page. The parameter values are used to display the initial page fragment within the ADF region. If the bounded task flow relies on input parameter values that are not available when the page is first created, make sure that your task flow behaves correctly if the input parameter values are null by, for example, using a NullPointerException object. Alternatively (or additionally), make sure that the task flow does not activate until the input parameters become available by configuring the task flow binding's active property.

An ADF region task flow binding can be refreshed again based on one of the following task flow binding attributes:

• taskFlowId

  This attribute specifies the directory path and the name of the source file for the bounded task flow. The ADF region refreshes if this attribute value changes.

• Neither Refresh or RefreshCondition attributes are specified (default)

  If neither the Refresh or RefreshCondition task flow binding attribute is specified, the ADF region is refreshed only once at the time the parent page is first displayed unless you configure a value for the task flow binding's active property.

• RefreshCondition="#{EL.expression}"

  The RefreshCondition must evaluate to a boolean value, and the EL expression must return true just one time for each task flow refresh. This means the expression cannot be a reference to a state variable; instead, it must be a call to a method that possesses the internal check of the return value. If no check is implemented in the method call and the expression is allowed to return true more than once, then during the refresh of a dynamic region, the application will display the error "The content of this page failed to load as expected because data transmission was interrupted".

  Note:

  A dynamic region may fail to load unless the application can guarantee that the RefreshCondition expression evaluates to true only once for each task flow refresh. For example, assume you have assigned an expression to the refresh condition for the task flow definition. If the EL expression evaluates to true, the region model defined by the controller is refreshed and, as a result, the client ID index for the region is incremented. This will cause any operation that expects the original client ID for the region to fail as it does not find the expected ID. One such operations is streaming of table row data.

  At the time the RefreshCondition is evaluated, if the variable bindings is used within the EL Expression, the context refers to the binding container of the parent page, not the page fragment displayed within the ADF region. RefreshCondition is independent of the change of value of binding parameters. If the task flow binding parameters do not change, nothing within the ADF region will change. The expression is evaluated during the PrepareRender phase of the ADF page lifecycle. For more information, see Understanding the Fusion Page Lifecycle .

• Refresh="ifNeeded"

  Any change to a task flow binding parameter value causes the ADF region to refresh. If the ADF region task flow binding does not have parameters, Refresh="ifNeeded" is equivalent to not specifying the Refresh attribute.

  Refresh="ifNeeded" is not supported if you pass parameters to the task flow binding using a dynamic parameter map. You must instead use the RefreshCondition="#{EL.Expression}".

  For more information about specifying parameter values using a parameter map, see Specifying Parameters for ADF Regions Using Parameter Maps.

The Refresh="ifNeeded" property takes precedence over RefreshCondition and RefreshCondition will not be evaluated if you set Refresh="ifNeeded". When possible, use the Refresh="ifNeeded" property to control region refresh behavior and to avoid the page content loading failure that can result when RefreshCondition="#{EL.expression}" evaluates to true more than once for each task flow refresh.

The following example contains a sample task flow binding located within the page definition of a page on which an ADF region has been added.

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

You do not need to refresh an ADF region to refresh the data controls inside the ADF region. During the ADF lifecycle, the refresh events telling the iterators to update will be propagated to the binding container of the current page of the ADF region.

What You May Need to Know About Refreshing an ADF Region

When a binding container hierarchy is refreshed, the region binding code evaluates the input parameter values and compare the new values with the previous values for the region binding only if the region binding has a refresh condition set to ifNeeded. See Configuring an ADF Region to Refresh. If a parameter value is changed, the region is refreshed. For example, if a region displays the employee details of an employee and if any of the details of the employee is changed, then region refreshes and displays the details for the selected employee.

Additionally, if you have added support for childCreation attribute set to lazyUncached on various UI components, the ADF view prunes the portions of the view tree and those portions are not included in the active view tree and are not visible. During the refresh of binding container hierarchy, the ADF controller evaluates the input parameters for all the regions that were pruned and are not visible in the active view tree of the page layout. The operations on the corresponding binding containers that are not in active tree view might result in poor performance.

To avoid refreshing the regions that are not visible in the active tree view, set the oracle.adfinternal.controller.regionPruning parameter value to true. This parameter checks if the region is part of the active view tree before evaluating if the input parameter values are modified. The region will then be refreshed only if the region is part of the active view tree and one or more parameter values are modified.

This property uses the Trinidad property service, therefore, you can set this property using the Fusion Apps property mechanism. Alternatively, you can enable this property using the adf-settings.xml file.

<adf-properties-settings
xmlns="http://xmlns.oracle.com/adf/properties/settings">
      <properties>
         <property>
           <name>oracle.adfinternal.controller.regionPruning</name>
           <default-value>true</default-value>
         </property>
      </properties>
   </adf-properties-settings>

Configuring Activation of an ADF Region

The ADF regions can be configured to be activated at the appropriate time. This is helpful to optimize the performance of the task flow binding these regions. You can set the activation of the region either as conditional, deferred, or immediate based on your requirement.

You can configure when an ADF region activates. This has the effect of determining when the task flows contained in ADF regions activate. Configuring the activation of ADF regions can optimize the performance of a Fusion web application's page. For example, a page that contains 5 ADF regions may reference 5 task flows. You may not want these 5 task flows to execute simultaneously when the Fusion web application page loads so you configure an activation property to determine when a task flow executes.

How to Configure Activation of an ADF Region

You configure the activation property for the task flow binding associated with the ADF region to determine when to activate the ADF region.

Before you begin:

It may be helpful to have an understanding of the configuration options for activating an ADF region. For more information, see Configuring Activation of an ADF Region.

You may also find it helpful to understand functionality that can be added using other task flow features and ADF region features. For more information, see Additional Functionality for Task Flows that Render in ADF Regions.

To configure the activation of an ADF region:

1. In the Applications window, select the page that contains the ADF region(s), right-click and choose Go to Page Definition.
2. In the page definition file, select the task flow binding or multi task flow binding in the Executables section, as illustrated in Figure 26-8.

   Figure 26-8 Task Flow Bindings for ADF Region Configured for Activation

   
   Description of "Figure 26-8 Task Flow Bindings for ADF Region Configured for Activation"
3. In the Properties window, select a value from the activation dropdown list, as described in the following list:

   • conditional: activates the ADF region if the EL expression set as a value for the task flow binding active property returns true.

   • deferred: select this option if your application uses Facelets XHTML pages in the view layer and you want to activate the ADF region when a Facelets XHTML page first requests a viewID. If your application uses JSP technology in the view layer, selecting this option has the same effect as selecting immediate (the ADF region activates immediately).

     Use this option if your application uses Facelets XHTML pages. For more information about Facelets with ADF Faces, see the "Getting Started with ADF Faces and JDeveloper" chapter in Developing Web User Interfaces with Oracle ADF Faces.

   • immediate: activates the ADF region immediately. This is the default value.

   The value that you select in the dropdown list determines when an ADF region switches from an inactive to an active state. An ADF region must have an active state before it can invoke a task flow.

4. If you selected conditional as the value in the activation dropdown list, write an EL expression that returns a boolean value at runtime for the active property. If the EL expression returns true, the ADF region invokes the task flow. If the EL expression returns false, the ADF region deactivates a task flow that was active in the ADF region.

What Happens When You Configure Activation of an ADF Region

The behavior of the ADF region at runtime depends on the options that you set for the activation property.

Figure 26-9 shows the default behavior where all task flows in ADF regions execute when the page loads the ADF regions (Tab # 1, Tab # 2, Tab # 3).

Figure 26-9 Default Activation of ADF Regions

Description of "Figure 26-9 Default Activation of ADF Regions"

Figure 26-10 shows an example where the activation property was set to deferred and the application uses Facelets. The regions in Tab # 1 and Tab # 2 have an active state because the end user navigated to these regions. The region in Tab # 3 is inactive.

Figure 26-10 Deferred Activation of ADF Regions

Description of "Figure 26-10 Deferred Activation of ADF Regions"

Figure 26-11 shows an example where the activation property was set to conditional and the active property to an EL expression that returns a boolean value at runtime. The region in Tab # 1 is in an active state because the EL expression specified for the active property returns true. The regions in Tab # 2 and Tab # 3 are inactive because the EL expression specified for the active property returns false.

Note that the following events occur if a region deactivates a task flow (the value returned by the active property changes from true to false):

• A task flow with an active transaction rolls back the transaction.

  For more information about transaction options in task flows, see Managing Transactions in Task Flows.

• If a task flow has a data control frame with a data-control-scope value of isolated, the task flow releases the data control frame and any data controls in the data control frame.

  For more information about data controls, see Sharing Data Controls Between Task Flows and What You May Need to Know About Sharing Data Controls and Managing Transactions.

• ADF Controller releases the view port data structures for the region (including pageFlow and view scopes).

  For more information about view ports, see About View Ports and ADF Regions. For more information about memory scopes, see What You May Need to Know About Memory Scope for Task Flows.

Figure 26-11 Conditional Activation of ADF Regions

Description of "Figure 26-11 Conditional Activation of ADF Regions"

Navigating Outside an ADF Region's Task Flow

You can navigate out of the ADF region and then display the parent view activity of the task flow that binds the region, or you can display the root page of its application. To do so, you must expose the properties (parent-outcome and root-outcome) of the parent action activity that you configure.

A bounded task flow running in an ADF region may need to trigger navigation of its parent view activity or to navigate to the root page of its application. The parent action activity exposes properties (parent-outcome and root-outcome) that you configure if you want to implement either of these use cases.

For example, you might specify a value for parent-outcome if you have a page that displays employee information and an ADF region that contains an enroll button for an employee. After the enroll page completes and the ADF region returns, the employee information page refreshes with the next employee.

Note:

An ADF region does not maintain state when you navigate away from the region.

How to Trigger Navigation Outside of an ADF Region's Task Flow

You add a parent action activity to the bounded task that runs in the ADF region and configure it so that it navigates to the parent's view activity.

Before you begin:

It may be helpful to have an understanding of the configuration options for activating an ADF region. For more information, see Configuring Activation of an ADF Region.

You may also find it helpful to understand functionality that can be added using other task flow features and ADF region features. For more information, see Additional Functionality for Task Flows that Render in ADF Regions.

To trigger navigation outside of an ADF region's task flow:

1. In the Applications window, double-click the bounded task flow that runs in the ADF region.
2. In the ADF Task Flow page of the Components window, from the Component panel, in the Activities group, drag and drop a Parent Action onto the diagram for the bounded task flow.
3. Select the parent action activity in the diagram for the bounded task flow.
4. In the Properties window, choose the appropriate option:

   • Parent Outcome: enter a literal value or write an EL expression that returns an outcome so that the parent action activity navigates to the parent view activity. The outcome is then used to navigate the parent view activity's task flow rather than navigating the ADF region's bounded task flow.

     The parent view activity's task flow should contain a control flow case or wildcard control flow rule that accepts the value you specify for parent-outcome.

   • Root Outcome: enter a literal value or write an EL expression that returns an outcome so that the parent action activity navigates to the root page of the application.

     For example, to navigate from an ADF region to the home page in your application, you specify a value for Root Outcome, as illustrated in Figure 26-12.

     Figure 26-12 Navigating to Home Page

     
     Description of "Figure 26-12 Navigating to Home Page"

   Note:

   Parent Outcome and Root Outcome are mutually exclusive.

5. (Optional) In the Outcome field, enter a literal value that specifies an outcome for control flow within the ADF region after the parent action activity adds parent-outcome or root-outcome to the appropriate queue.

   Specifying an outcome element is useful in cases where the parent view activity or root page does not navigate as a result of the parent-outcome or root-outcome sent by the parent action activity. In addition, the ADF region should not continue to display the same view. If you do not specify a value for outcome, the ADF region's viewId remains unchanged.

What Happens When You Configure Navigation Outside a Task Flow

At design time, JDeveloper writes entries to the source file for the bounded task flow based on the property values you set for the parent action activity. The following example shows sample entries that JDeveloper generates when you write a literal value for the Parent Outcome and Outcome properties of the parent action activity.

<parent-action id="parentAction1">
    <parent-outcome>parent_outcome</parent-outcome>
    <outcome id="__2">outcome</outcome>
</parent-action>

The following example shows sample entries that JDeveloper generates when you write a literal value for the Root Outcome and Outcome properties of the parent action activity.

<parent-action id="parentAction1">
      <root-outcome>root_outcome</root-outcome>
      <outcome id="__2">outcome</outcome>
</parent-action>

At runtime, when navigation in an ADF region’s bounded task flow encounters a parent view activity, the parent view activity’s outcome is queued and the current navigation operation in the ADF region’s bounded task flow continues. Once the current navigation operation completes, the queued outcome triggers a new navigation operation on the parent. If, for example, the next activity in the bounded task flow of the ADF region is a method call activity and the parent action activity navigates to a task flow that also includes a method call activity, the method call activity in the bounded task flow of the ADF region executes first.

What You May Need to Know About How a Page Determines the Capabilities of an ADF Region

In some cases, a page may need to determine the capabilities currently available within one of the ADF regions that it contains. For example, the page may need to initiate control flow within the ADF region based on its current state using the queueActionEventInRegion() method. Region capabilities are used by a parent page to identify the current outcomes of one of its regions based on the region's current state. They identify to the parent page whether or not an outcome is possible within the region.

The following scenario describes how region capabilities might typically be used in an application:

1. An ADF region within a page displays its associated page fragment.

2. A user selects a button or performs some other action in the ADF region.

3. The parent page identifies the outcomes (region capabilities) for the ADF region.

4. The parent page updates its buttons based on the ADF region capabilities.

The syntax of an EL expression to determine an ADF region's capabilities is as follows:

#{bindings.[regionId].regionModel.capabilities['outcome']}

where regionId is the ID of the ADF region component on the page and outcome is the possible outcome being verified within the ADF region.

Region capabilities require the availability of the specified ADF region's regionModel through an EL expression. The EL expression should never access bindings in any other binding container other than the current binding container. Region capabilities cannot be used in some cases. For example, a nested ADF region where a regionModel cannot be reached within the current binding container. This is because a nested region's nested binding container might not yet exist or might have already been released.

Configuring Transaction Management in an ADF Region

The ADF task flow allows you to optionally choose if you want to allow a task flow to share or isolate its data controls with a calling talk flow. For this, you must set a value for the data-control-scope property of the bounded task flow. You can also rollback or commit the changes made by the calling task flow by exposing the methods by the DataControlFrame interface of the ADF Model layer.

In the ADF Controller layer, bounded task flows optionally provide their own abstract implementation of transactions over the underlying ADF Model layer, as described in Managing Transactions in Task Flows. You can choose whether a task flow shares or isolates its data controls with a calling task flow by setting a value for its data-control-scope property, as described in Sharing Data Controls Between Task Flows . Whether a task flow creates a new transaction depends on the values you choose for the transaction and data-control-scope properties, as described in What You May Need to Know About Sharing Data Controls and Managing Transactions.

If, for example, you share a task flow's data control with a calling task flow, a new transaction is created at the ADF Controller layer level if you configure the task flow's transaction option to Always Begin New Transaction (new-transaction) or to Use Existing Transaction If Possible (requires-transaction). The requires-transaction option creates a new transaction only if a transaction does not already exist. The created transaction has the same lifespan as the ADF region that renders the task flow. This may cause behavior that you do not intend when the task flow renders in an ADF region. For example, if an ADF region refreshes, it restarts the task flow that it renders and causes the following events to occur:

• Discards the current view port that the ADF region uses

  Note:

  Save points require a root view port to work. For more information about view ports, see About View Ports and ADF Regions. For more information about save points, see Using Save Points in Task Flows.

• Releases the data control that the task flow uses

  This may cause the loss of changes made in the parent page of the calling task flow because it shares the data control of the task flow that renders in the ADF region.

• Executes a commit or rollback if the End Transaction property of the task flow's task flow return activity specifies one of these actions. For more information, see Using Task Flow Return Activities .

There are a number of ways to prevent the inadvertent termination of a task flow's transaction by the refresh of an ADF region. All these options disassociate the lifespan of the transaction in the task flow that renders in an ADF region from the lifespan of the ADF region. These options make sure that the region's parent page owns the transaction and/or that the transaction starts before the region renders. Choose the most appropriate option for your application:

• Set the transaction option on the task flow that renders in the ADF region to Always Use Existing Transaction (requires-existing-transaction). This throws an exception if a transaction does not exist and prevents the ADF region from owning the transaction.

• Set the calling task flow's transaction option to Always Begin New Transaction (new-transaction) so that the lifespan of the transaction is associated with the lifespan of the parent page.

• Invoke the DataControlFrame interface's beginTransaction() method in the action that navigates to the parent page that contains the region.

• Configure a method call activity that invokes the DataControlFrame interface's beginTransaction() method from a managed bean with a request scope before navigating to the parent page of the ADF region.

  The following code begins a transaction:

    public void beginTransaction()
    {
      BindingContext context = BindingContext.getCurrent();
   
      String dcFrameName = context.getCurrentDataControlFrame();
      DataControlFrame dcFrame = context.findDataControlFrame(dcFrameName);
      dcFrame.beginTransaction(new TransactionProperties());
    }
  

If you share the data controls of a task flow with a calling task flow, use the rollback or commit options exposed by the task flow's task flow return activity to commit or rollback changes rather than programmatically use the methods exposed by the ADF Model layer's DataControlFrame interface. Using the methods exposed by the DataControlFrame interface closes the transaction and may cause the task flow that renders in the ADF region to create a new transaction.

Creating ADF Dynamic Regions

An ADF dynamic region is determined by the taskFlowId attribute of the binding task flow at runtime. This is helpful when you want to run the task flows based on the user choice at runtime. You can add additional bounded task flows to the dynamic region by creating ADF dynamic region links.

An ADF dynamic region is an ADF region where the task flow binding dynamically determines the value of its taskFlowId attribute at runtime. This allows the Fusion web application to determine which bounded task flow to execute within the ADF dynamic region based on the result of evaluation of the task flow binding's taskFlowId attribute.

Figure 26-13 shows a runtime example from the Summit ADF task flow sample application where the index.jsf page renders a different registration task flow in the showDetailItem component labeled Welcome in response to the link component that the end user clicks. For example, if the end user clicks Register as Employee, the application renders the emp-reg-task-flow-definition.xml task flow in the ADF dynamic region. If the end user clicks Register as Customer, the application renders the edit-customer-task-flow-definition.xml task flow in the ADF dynamic region.

At runtime, the ADF dynamic region swaps the task flows that it renders during the Prepare Render lifecycle phase. To give components from a previous task flow the opportunity to participate smoothly in the lifecycle phases, do not navigate off the regionModel until the JSF Invoke Application lifecycle phase. It is good practice, therefore, not to navigate a task flow in a dynamic region in response to contextual events. For information about lifecycle phases, see Understanding the Fusion Page Lifecycle , and for information about contextual events, see Using Contextual Events.

Figure 26-13 ADF Dynamic Region in the Summit ADF Task Flow Sample Application

You create an ADF dynamic region by dragging and dropping a bounded task flow to the page where you want to render the ADF dynamic region. The view activities in the bounded task flow must be associated with page fragments (.jsff).

If you attempt to drag and drop a bounded task flow that is associated with pages rather than page fragments, JDeveloper does not display the context menu that allows you to create an ADF dynamic region. You can convert a bound task flow that uses pages to use page fragments. See How to Convert Bounded Task Flows .

After you create an ADF dynamic region, you can add additional bounded task flows to the dynamic region by creating ADF dynamic region links, as described in Adding Additional Task Flows to an ADF Dynamic Region.

How to Create an ADF Dynamic Region

Drag and drop bounded task flows to the page where you want to render the ADF dynamic region.

Before you begin:

It may be helpful to have an understanding of the configuration options available to you when creating an ADF dynamic region. For more information, see Creating ADF Dynamic Regions.

You may also find it helpful to understand other functionality that can be added using other task flow and ADF region features. For more information, see Additional Functionality for Task Flows that Render in ADF Regions.

To create an ADF dynamic region:

1. In the Applications window, double-click the JSF page where you want to create the ADF dynamic region.

2. From the Applications window, drag and drop the first bounded task flow onto the JSF page, and from the context menu, choose Create > Dynamic Region.

3. Choose the appropriate option in the Choose Managed Bean for Dynamic Region dialog:

   • If you want an existing managed bean to store the bounded task flow's ID, select an existing managed bean from the Managed Bean dropdown list.

     The managed bean passes the value of the bounded task flow's ID into the task flow binding of the ADF dynamic region. Make sure that the managed bean you select is not used by another ADF dynamic region.

   • If no managed bean exists for the page, click the Add icon next to the Managed Bean dropdown list to create a new one. Enter values in the dialog that appears as follows:

   • 1. Bean Name: Enter a name for the new managed bean. For example, enter DynamicRegionBean.

     2. Class Name: Enter the name of the new managed bean class.

     3. Package: Enter the name of the package that is to contain the managed bean or browse to locate it.

     4. Extends: Enter the name of the Java class that the managed bean extends. The default value is java.lang.Object.

     5. Scope: This field is read-only and its value is set to backingBean. For more information about the memory scope for managed beans, see What You May Need to Know About Memory Scope for Task Flows.

     6. Click OK to close the dialogs where you configure the managed bean.

4. Choose the appropriate option in the Edit Task Flow Binding dialog:

   • Click OK if you do not want specify input parameters or an input parameter map for the ADF dynamic region.

   • Specify input parameters for the ADF dynamic region.

     For more information, see Specifying Parameters for an ADF Region.

   Figure 26-14 shows the Edit Task Flow Binding dialog that appears after you configure a managed bean.

   Note:

   You can write an EL expression that references a list of input parameters specified in a managed bean using the Input Parameters Map field of the Edit Task Flow Binding dialog. For more information about implementing this functionality, see Specifying Parameters for ADF Regions Using Parameter Maps.

   Figure 26-14 Edit Task Flow Binding Dialog for an ADF Dynamic Region

   

5. Click OK.

What Happens When You Create an ADF Dynamic Region

When you drop a bounded task flow onto a JSF page to create an ADF dynamic region, JDeveloper adds an af:region tag to the page. The af:region tag contains a reference to a task flow binding. The following example shows the af:region tag that renders the ADF dynamic region in the index.jsf page of the Summit ADF task flow sample application.

<af:region value="#{bindings.dynamicRegion1.regionModel}" id="r4"
                             rendered="#{WelcomePageBean.isRegistration}"/>

JDeveloper also adds a task flow binding to the page definition file of the page that hosts the ADF dynamic region. The following example shows a sample of the metadata that JDeveloper adds. The task flow binding provides a bridge between the ADF dynamic region and the bounded task flow. It binds the ADF dynamic region to the bounded task flow and maintains all information specific to the bounded task flow.

<taskFlow id="dynamicRegion1"
       taskFlowId="${WelcomePageBean.dynamicTaskFlowId}"
       activation="deferred"
       xmlns="http://xmlns.oracle.com/adf/controller/binding"/>

The taskFlowId attribute in the task flow binding metadata specifies the managed bean that determines at runtime what bounded task flow to associate with the ADF dynamic region. JDeveloper creates this managed bean or modifies an existing managed bean to store this data. The following example shows extracts of the code that JDeveloper writes to the managed bean.

import oracle.adf.controller.TaskFlowId;
 ...
    private String taskFlowId = "/directoryPath/toTaskFlow";
 ...
    public TaskFlowId getDynamicTaskFlowId() {
        return TaskFlowId.parse(taskFlowId);
    }
...

At runtime, the managed bean stores the value of the bounded task flow's ID (taskFlowId) that displays inside the ADF dynamic region. The managed bean swaps the different bounded task flows into the task flow binding of the ADF dynamic region.

When an ADF dynamic region reinitializes, the Fusion web application must reinitialize the task flow binding associated with the ADF dynamic region. This includes evaluating if there are new input parameters and input parameter values to pass to the ADF dynamic region.

Adding Additional Task Flows to an ADF Dynamic Region

The ADF dynamic region helps you to display data from different task flows without navigating away from the current display area. This action is triggered by the end user by clicking a command component. This is possible as the ADF dynamic region has the ability to swap a bounded task flow with another bounded task flow.

An ADF dynamic region link swaps a bounded task flow for another bounded task flow within an ADF dynamic region. An end user clicks a command component (a button or a link) to update the ADF dynamic region with the new bounded task flow.

For example, a bounded task flow in the ADF dynamic region displays general information about an employee such as an ID and photo. When the end user clicks a link command component labeled Details, the ADF dynamic region updates with a table containing more information about the employee from another bounded task flow. The end user's action (clicking the link) invokes a method on the ADF dynamic region's managed bean. The value of the new bounded task flow is passed to the method, and the ADF dynamic region refreshes with the new bounded task flow. The new bounded task flow now displays within the ADF dynamic region.

By default, a ADF dynamic region link swaps another bounded task flow in for the original, but cannot swap back to the original. To toggle back to the original bounded task flow, you could add a second ADF dynamic region link on the page that, when clicked, swaps the current task flow back to the original one.

You can add an ADF dynamic region link if you already have at least one ADF dynamic region on a page and are adding a new bounded task flow as an ADF dynamic region to the same page. After you drop the bounded task flow on the page and choose to create an ADF dynamic region link, a menu displays all of the dynamic regions currently on the page, as shown in Figure 26-15.

A list of the current dynamic regions in a document appears when you choose Dynamic Region Link from the menu that appears after you drag and drop a bounded task that you want to add as an option to an existing dynamic region in the document, as shown in Figure 26-15.

Figure 26-15 ADF Dynamic Region Link Menu

Use this menu to select the ADF dynamic region within which you want to display the contents of the bounded task flow.

Tip:

You can use the values in the dynamic region link in other UI components. For example, you could create a selection list in which each of the items in the list links to a different bounded task flow. All of the linked bounded task flows would display in the same dynamic region. The links perform a method in the class behind the managed bean created to swap the bounded task flow it displays.

How to Create an ADF Dynamic Region Link

You drag and drop a bounded task flow to a page that already contains an ADF dynamic region and you select Dynamic Region Link on the context menu that appears to view a list of ADF dynamic regions to which you can create a link.

Before you begin:

It may be helpful to have an understanding of the configuration required before you attempt to create an ADF dynamic region link. For more information, see Adding Additional Task Flows to an ADF Dynamic Region.

You may also find it helpful to understand functionality that can be added using other task flow and ADF region features. For more information, see Additional Functionality for Task Flows that Render in ADF Regions.

You will need to complete this task:

• Add at least one ADF dynamic region to the JSF page where you are going to create an ADF dynamic region link. For information about adding an ADF dynamic region to a JSF page, see Creating ADF Dynamic Regions.

To create an ADF dynamic region link:

1. In the Applications window, double-click the JSF page where you want to create the ADF dynamic region link.
2. From the Applications window, drag and drop a bounded task flow onto the JSF page and, from the context menu, choose Dynamic Region Link.

   Note:

   The view activities of the bounded task flow must be associated with page fragments. You can convert a bounded task flow that uses pages to use page fragments. For more information, see How to Convert Bounded Task Flows .

3. In the context menu that displays a list of the ADF dynamic regions that have already been added to the page, select the name of the ADF dynamic region in which you want to display the contents of the bounded task flow.
4. Click OK.

What Happens When You Create an ADF Dynamic Region

JDeveloper adds a link to the page, as shown in the following example. JDeveloper also updates the managed bean for the ADF dynamic region and updates the corresponding task flow binding with any new parameters.

<af:link text="region2" action="#{RegionBean.region2}"
  id="dynamicRegionLink1"/>

Configuring a Page To Render an Unknown Number of Regions

At times you may not know how many ADF regions might need to be rendered at runtime. This can be handled at design time by configuring the mutiTaskFlow element of the JSF page definition file.

You can configure a page at design time when you do not know the number of regions that render in the page at runtime. For example, you want to add or remove regions to tabs using the panelTabbed component. Each tab that you add or remove renders a region that references a bounded task flow.

To implement this functionality, you configure the JSF page definition file's multiTaskFlow element to reference a list of task flow bindings contained in a managed bean of the following type:

oracle.adf.controller.binding.TaskFlowBindingAttributes

The following example shows the code for the class of a managed bean named MultiBean that returns a list containing two task flows.

package view;
 
import java.util.ArrayList;
import java.util.List;
 
import oracle.adf.controller.TaskFlowId;
import oracle.adf.controller.binding.TaskFlowBindingAttributes;
 
public class MultiBean {
    private List<TaskFlowBindingAttributes> mTaskFlowBindingAttrs = new 
                   ArrayList<TaskFlowBindingAttributes>(5);
 
    public MultiBean() {
        TaskFlowBindingAttributes tfAttr = new TaskFlowBindingAttributes();
        tfAttr.setId("region1");
        tfAttr.setTaskFlowId(new TaskFlowId("/WEB-INF/r1.xml", "r1"));
        mTaskFlowBindingAttrs.add(tfAttr);
 
        tfAttr = new TaskFlowBindingAttributes();
        tfAttr.setId("region2");
        tfAttr.setTaskFlowId(new TaskFlowId("/WEB-INF/r2.xml", "r2"));
        mTaskFlowBindingAttrs.add(tfAttr);
 
    }
 
    public List<TaskFlowBindingAttributes> getTaskFlowList() {
        return mTaskFlowBindingAttrs;
    }
}

For more information about the TaskFlowBindingAttributes class, see the Java API Reference for Oracle ADF Controller.

At runtime, the multiTaskFlow binding references a list of one or more task flows that an end user can add or remove to the page using command components that you also expose. Figure 26-16 shows the relationships between the different parts that make up this use case.

Note:

The page fragments that the bounded task flows render must use the Facelets document type.

Figure 26-16 ADF Regions Derived from a Multi Task Flow Binding

Description of "Figure 26-16 ADF Regions Derived from a Multi Task Flow Binding "

How to Configure a Page to Render an Unknown Number of Regions

Configure the JSF page definition file's multiTaskFlow element to reference a list of bounded task flows. This list can be modified at runtime by adding or removing elements of type TaskFlowBindingAttributes.

Before you begin:

It may be helpful to have an understanding of the configuration options available to you when configuring a page to render an unknown number of ADF regions. For more information, see Configuring a Page To Render an Unknown Number of Regions.

You may also find it helpful to understand other functionality that can be added using other task flow and ADF region features. For more information, see Task Flows and ADF Region Use Cases and Examples.

You will need to complete this task:

• Create a managed bean with a pageFlow scope that returns a list of type TaskFlowBindingAttributes. For more information about how to create a managed bean, see How to Use a Managed Bean to Store Information.

To configure a page to render an unknown number of regions:

1. In the Applications window, right-click the JSF page where you want to add or remove ADF regions at runtime and choose Go to Page Definition.
2. If a confirmation dialog appears, click Yes.
3. In the overview editor, click the Binding and Executables tab, and then click the Add icon in the Executables section.
4. In the Insert Item dialog, select ADF Task Flow Bindings from the dropdown menu, then select multiTaskFlow as the item to create and click OK.
5. In the Insert multiTaskFlow dialog, enter the following values:

   • id*: Enter a unique ID for the multi task flow binding.

   • taskFlowList *: Enter an EL expression that returns the list of TaskFlowBindingAttributes to return at runtime. For example, enter an EL expression similar to the following:

     #{pageFlowScope.multiBean.taskFlowList}

6. In the Applications window, double-click the JSF page where you want end users to add or remove ADF regions at runtime.
7. In the ADF Faces page of the Components window, from the Operations panel, drag and drop a For Each onto the component in the Structure window that you want to enclose the For Each component.
8. In the Properties window for the For Each component, enter values in the following fields:

   • Items: Enter an EL expression that references the method that return the list of task flow bindings from the multi task flow binding runtime object.

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

     #{bindings.multiRegion1.taskFlowBindingList}

   • Var: Enter a value to identify the list of task flow bindings.

9. In the JSF page that contains the For Each component, insert a Region component inside the For Each component that references the Region component's region model using an EL expression, as shown in the following example.

   <af:forEach var="tf" items="#{bindings.multiRegion1.taskFlowBindingList}">
     <af:panelBox text="#{tf.name}" id="pb1">
       <f:facet name="toolbar"/>
       <af:region value="#{tf.regionModel}" id="r1"/>
     </af:panelBox>
   </af:forEach>
   

What Happens When You Configure a Page to Render an Unknown Number of Regions

Metadata similar to that shown in the following example appears in the JSF page definition file for the multi task flow binding.

<multiTaskFlow id="multiRegion1"              
    taskFlowList="${pageFlowScope.multiBean.taskFlowList}" activation="deferred"
    xmlns="http://xmlns.oracle.com/adf/controller/binding"/>

The taskFlowList attribute in the multi task flow binding metadata specifies the managed bean. The managed bean stores the list of objects describing the task flows that can be added to the page at runtime.

What You May Need to Know About Configuring a Page to Render an Unknown Number of Regions

• While there is no limit to the number of remote regions that you can render in a JSF page, use this capability with caution. For simple pages, where tabs are not used, regions may be combined in the page such that the maximum number of regions is determined by the design of the region and the view object queries it executes. Alternatively, for complex pages that use tabs, limit the use of regions to achieve best performance. For complex tabbed pages, ADF will not deactivate task flow transactions once a region is loaded. When switching tabs, the ongoing transaction must be stopped to achieve best performance. For details about the interaction between task flows and regions, see Configuring Transaction Management in an ADF Region.

• Each task flow binding inherits attributes defined for the multi task flow binding unless you override this behavior using the methods exposed by TaskFlowBindingAttributes.

• Each task flow binding inherits parameters defined in the multi task flow binding in addition to those defined using the parametersMap property, as described in Specifying Parameters for ADF Regions Using Parameter Maps.

Handling Access to Secured Task Flows by Unauthorized Users

When an ADF region is accessed by a user without access permission, a blank area is displayed. You can handle this by invoking a task flow that can display appropriate information or message to the user.

A bounded task flow does not render in an ADF region if it is invoked by a user who does not have the security permissions to access it. The region renders a blank area in place of the requested task flow when this occurs. This may confuse your users as it does not provide feedback as to why the task flow that they attempted to invoke does not appear. To improve the user experience, you can specify an alternative bounded task flow to render when a user attempts to access a bounded task for which they do not have the required security permissions. You can, for example, configure the alternative bounded task flow to display a page to inform users that they do not have the necessary security permissions. A more complex approach may be to render a bounded task flow that takes the users step-by-step through the process to request the necessary permissions from their system administrator.

Configure the level of security for the alternative bounded task flow to make sure that users can view it should they fail to access a bounded task flow for which they do not have security permissions. This may involve making the alternative bounded task flow public, as described in How to Make an ADF Resource Public. For more information about securing your Fusion web application, including bounded task flows, see Enabling ADF Security in a Fusion Web Application.

How to Handle Access to Secured Task Flows by Unauthorized Users

You configure an alternative bounded task flow with the content that you want to display to users when they cannot access a bounded task flow because of a lack of security permissions. You specify the alternative bounded task flow as the value for the Unauthorized Region Taskflow property in your Fusion web application's adf-config.xml file.

Before you begin:

It may be helpful to have an understanding of why you may need to display a message to users without security permissions for a task flow. For more information, see Handling Access to Secured Task Flows by Unauthorized Users.

You may also find it helpful to understand functionality that can be added using other Oracle ADF features. For more information, see Additional Functionality for Task Flows that Render in ADF Regions.

You will need to complete these tasks:

1. Create an alternative bounded task flow to display to users when they cannot access a bounded task flow for which they do not have security permissions.

   For more information about creating a bounded task flow, see Creating a Task Flow.

2. Configure this task flow so that users can access it.

   For more information, see How to Make an ADF Resource Public.

To display messages to users without security permissions for task flows:

1. In the Application Resources panel, expand the Descriptors and ADF META-INF nodes, and then double-click the adf-config.xml file.
2. In the overview editor, click the Controller navigation tab.
3. In the Controller page, in the Unauthorized Region Taskflow field, enter the name of the bounded task flow to invoke or click Browse to select it.

What Happens When You Handle Access to Secured Task Flows by Unauthorized Users

JDeveloper writes the name of the bounded task flow that you selected as a value for the <unauthorized-region-taskflow> element in the adf-config.xml file, as illustrated in the following example.

<?xml version="1.0" encoding="windows-1252" ?>
<adf-config xmlns="http://xmlns.oracle.com/adf/config"
    xmlns:config="http://xmlns.oracle.com/bc4j/configuration"
     xmlns:adf="http://xmlns.oracle.com/adf/config/properties">
...
<adf-controller-config xmlns="http://xmlns.oracle.com/adf/controller/config">
    <unauthorized-region-taskflow>/WEB-INF/task-flow-definition.xml
       </unauthorized-region-taskflow>
  </adf-controller-config>
...
</adf-config>

At runtime, the Fusion web application renders this alternative bounded task flow when users attempt to invoke a bounded task flow for which they do not have security permissions.

Creating Remote Regions in a Fusion Web Application

You can create an ADF remote region by invoking a task flow of a Fusion web application outside of your own application. The bounded task flow (producer) producing the remote region must have data-control-scope property set to isolated value. The task flow consuming the remote region is the consumer. A remote region can be consumed by more than one consumer task flows allowing you to reuse the remote region.

You create a remote region by invoking a task flow from another Fusion web application (the producer) in a page of your Fusion web application (the consumer). Creating a remote region allows you to reuse coarse-grained functionality in task flows that have their own data control frame rather than develop multiple task flows that implement the same functionality. It also offers performance, interactivity and ease-of-implementation advantages compared to implementing a JSF portlet in JSF pages that render ADF Faces components. At runtime, your consumer application invokes and renders a remote invocable task flow from the producer application. A remote invocable task flow may be consumed by multiple applications.

A task flow from a producer application that you configure to be invoked remotely must be a bounded task flow that renders page fragments. It must also have a value of isolated for the data-control-scope property and include the remote-invocable property. All of the transaction options that can be used when the data-control-scope property has a value of isolated can be configured for a task flow from a producer application that you configure to be invoked remotely. The producer and consumer applications do not share the transaction as the option chosen for the remote invocable task flow in the producer application determines the transaction behavior. For more information about the transaction options for task flows, see Managing Transactions in Task Flows.

Note:

The functionality described here, describing how to create a remote region to render a bounded task flow displaying JSF page fragments (.jsff) from another Fusion web application, differs to the functionality described in How to Call a Bounded Task Flow Using a URL. The latter section describes how you invoke a bounded task flow that renders JSF pages from another Fusion web application in a JSF page of your Fusion web application.

The producer and consumers application must run on the same version of Oracle ADF. That is, you cannot invoke a remote invocable task flow from a producer application that runs on one version of Oracle ADF and render it in a remote region of a consumer application that runs on a different version of ­Oracle ADF. If you attempt this type of implementation, the consumer application displays the following message to the user who attempts to launch the producer application:

Remote region error: Version of the richclient on the producer at "[producer URL]" is incompatible with this consumer.  
Consumer version: [Consumer Version] Producer version: [Producer Version]

The task flow from the producer application that you configure to be invoked remotely must not:

• Render ADF Faces components that use the Active Data Service

  For more information about the Active Data Service, see Using the Active Data Service .

• Invoke a remote invocable task flow from another application that produces remote invocable task flows. That is, you cannot configure a consumer application to invoke a remote invocable task flow from a producer application that invokes a remote invocable task flow from another producer application. A remote region cannot be nested inside another remote region.

• Invoke external dialogs, as described in:

  • Running a Bounded Task Flow in a Modal Dialog. The bounded task flows that run inside these external modal dialogs must reference pages, not page fragments.

  • Using the ADF Faces Dialog Framework Instead of Bounded Task Flows.

• Use save points, as described in Using Save Points in Task Flows.

• Implement drag and drop functionality, as described in the "Adding Drag and Drop Functionality" chapter in Developing Web User Interfaces with Oracle ADF Faces.

• Be invoked through an iFrame. Only use Oracle ADF functionality to create a remote region.

• Assume its input parameters are pass-by-reference and visible to its caller. In a remote region implementation, a copy of all parameter values is sent to the producer of the remote invocable task flow (pass-by-value) because this producer typically resides in a different web application to the consumer application.

In addition, all of the following objects associated with the remote invocable task flow must be serializable:

• Input parameters and return parameter values defined for the task flow

• Exceptions that the task flow throws

• Any payload data that a contextual event passes

Figure 26-17 illustrates an example scenario where consumer applications render remote regions that invoke remote invocable task flows from a producer application.

Figure 26-17 Applications Rendering Remote Regions

Description of "Figure 26-17 Applications Rendering Remote Regions"

Implementing the functionality described so far requires the completion of the following tasks:

• In the application that produces the task flows:

  • Configure the application's Enable Remote Region producer support property

  • Set the Remote Invocable property on the task flows that you want to render in a remote region

  • Configure the following properties for contextual events the application publishes that broadcast events to consumers in the consumer application:

    • Set dispatchMode to remote

    • Write an EL expression for customPayload that references a serializable object

    • Specify the type of the custom payload for the object

    Configuring these properties results in the following entries for the contextual event in the page definition where you publish the contextual event. For more information about contextual events, see Using Contextual Events.

    <event name="valueChangeEvent" dispatchMode="remote"  
           customPayload="<EL to a serializable object>" customPayloadType=<type of the custom payload> />

    For more information about publishing the events to a remote consumer, see How to Publish Contextual Events.

  • Consider setting session timeout to a value greater than the session timeout of the consumer application so that you prevent the display of a session timeout warning from the producer application to the consumer application's end users. For more information about configuring session timeout, see Managing the HttpSession in Fusion Web Applications.

• In the application that consumes the task flows from the producer application:

  • Configure the application's Enable Remote Region consumer support property

  • Add the remote invocable task flows to the JSF pages where you want to render remote regions

    Tip:

    While there is no limit to the number of remote regions that you can render in a JSF page, use this capability with caution. For simple pages, where tabs are not used, regions may be combined in the page such that the maximum number of regions is determined by the design of the region and the view object queries it executes. Alternatively, for complex pages that use tabs, limit the use of regions to achieve best performance. For complex tabbed pages, ADF will not deactivate task flow transactions once a region is loaded. When switching tabs, the ongoing transaction must be stopped to achieve best performance. For details about the interaction between task flows and regions, see Configuring Transaction Management in an ADF Region.

The TaskFlowProducer project in the Summit standalone sample applications for Oracle ADF contains a remote invocable task flow that can be consumed by a consumer application. Run the RemoteViewer.jsf page in the TaskFlowProducer project to deploy the sample application that contains the remote invocable task flow. Once you deploy this sample application, you can consume the remote invocable task flow, as described in How to Configure an Application to Render Remote Regions.

For more information about the Summit standalone sample applications for Oracle ADF, see Running the Standalone Samples from the SummitADF_Examples Workspace.

How to Configure an Application to Produce Task Flows for Use in Remote Regions

You configure the project in the application that produces the task flows. You also configure each task flow in the project that you want to render in a remote region so that it can be invoked remotely and does not share data control frames with calling task flows.

Before you begin:

It may be helpful to have an understanding of the configuration required before you attempt to configure an application to produce task flows for use in remote regions. For more information, see Creating Remote Regions in a Fusion Web Application.

You may also find it helpful to understand functionality that can be added using other task flow and ADF region features. For more information, see Additional Functionality for Task Flows that Render in ADF Regions.

To configure an application to produce task flows for remote regions:

1. In the Applications window, right-click the project that you want to configure to produce remote invocable task flows and choose Project Properties.
2. Click the ADF Task Flow node and select the Enable Remote Region producer support checkbox.
3. Select Allow Unauthenticated Remote Region Query servlet requests if, at runtime, you want to permit users of the consumer application to query the servlet (rtfquery) in the producer application for the list of remote invocable task flows without providing user credentials. Also select this checkbox if you want to view the list of available remote invocable task flows from the producer application while developing the consumer application in JDeveloper (design time).

   Leave this checkbox clear to add a security constraint to the producer application's web.xml file that requires users who submit requests to rtfquery be authenticated. This is the default option. For more information, see What You May Need to Know About Securing Remote Regions.

4. In the Applications window, double-click the task flow that you want to be invoked remotely.
5. In the overview editor, click the General navigation tab and expand the Visibility section.
6. Select the Remote Invocable checkbox.
7. Click the Behavior navigation tab, expand the Transaction section, and select Isolated from the Share data controls with calling task flow dropdown list.

   For more information about sharing data controls, see Sharing Data Controls Between Task Flows .

8. Repeat Steps 4 to 7 for each task flow that you want to be remote invocable so that it can render in a remote region.

What Happens When You Produce Task Flows for Use in Remote Regions

When you configure an application to produce remote invocable task flows, JDeveloper creates and/or modifies the following files:

• The application's web.xml file

• The application's policy store (the jazn-data.xml file)

• The source file of the task flow that you configure to be remote invocable

JDeveloper defines an ADF security policy in your producer application's jazn-data.xml file, as shown in the following example. JDeveloper creates this file if it does not exist in the producer application. This ADF security policy specifies a permission grant to grant access to a bootstrap page that acts as a container for the remote invocable task flow. You must define access policies for the individual remote invocable task flows that you want to appear in the bootstrap page by specifying permission grants. For more information, see How to Define Policies for ADF Bounded Task Flows. For more information about ADF Security, see Enabling ADF Security in a Fusion Web Application.

...
<jazn-policy>
  <grant>
    <grantee>
      <principals>
        <principal>
          <class>oracle.security.jps.internal.core.principals.JpsAnonymousRoleImpl</class>
          <name>anonymous-role</name>
        </principal>
      </principals>
    </grantee>
    <permissions>
      <permission>
        <class>oracle.adf.share.security.authorization.RegionPermission</class>
        <name>oracle.adfinternal.view.rich.bootstrap.remoteRegionBootstrapPageDef</name>
        <actions>view</actions>
      </permission>
    </permissions>
  </grant>
</jazn-policy>
...

JDeveloper also inserts the following properties in the source file of a task flow that you configure to be remote invocable when you set its remote-invocable property to true and the data-control-scope property to isolated, as shown in the following example. Setting the data-control-scope property to isolated means that the task flow will have its own data control frame at runtime. For more information about data controls and task flows, see Sharing Data Controls Between Task Flows .

...
<data-control-scope>
   <isolated/>
</data-control-scope>
...
<visibility>
   <remote-invocable/>
</visibility>
...

The entries that JDeveloper adds or configures in the application's web.xml file include:

• Filters (and associated filter mappings) named remoteApplication, ServletADFFilter, ADFLibraryFilter and adfBindings

• Servlets (and associated servlet mappings) named Faces Servlet, adflibResources and rtfqueryServlet

Example 26-2 shows these entries in a producer application configured to produce task flows for remote regions. In addition to the entries shown in Example 26-2, JDeveloper also generates a <security-constraint> and <login-config> element when you configure an application to produce remote invocable task flows. These elements are not shown in Example 26-2. For information about the values specified for these elements, see What You May Need to Know About Securing Remote Regions.

Note:

In the web.xml file, make sure that the remoteApplication filter appears:

• Immediately after the JpsFilter filter if this latter filter is configured.

  For more information about the JpsFilter filter, see What You May Need to Know About ADF Authentication.

• Before the ADFLibraryFilter filter, as shown in Example 26-2.

Example 26-2 Entries in the web.xml File of an Application Producing Remote Invocable Task Flows

<filter> 
   <filter-name>remoteApplication</filter-name>
   <filter-class>oracle.adfinternal.view.rich.remote.RemoteApplicationFilter</filter-class>
</filter>
...
<filter>
   <filter-name>ADFLibraryFilter</filter-name>
   <filter-class>oracle.adf.library.webapp.LibraryFilter</filter-class>
</filter>
...
<filter-mapping>
   <filter-name>remoteApplication</filter-name>
   <url-pattern>/rr/*</url-pattern>
   <dispatcher>REQUEST</dispatcher>
</filter-mapping>
...
<filter-mapping>
   <filter-name>ADFLibraryFilter</filter-name>
   <url-pattern>/*</url-pattern>
   <dispatcher>FORWARD</dispatcher>
   <dispatcher>REQUEST</dispatcher>
</filter-mapping>
...
<servlet>
    <servlet-name>Faces Servlet</servlet-name>
    <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>
...
<!-- The remote region query servlet. -->
<servlet>
   <servlet-name>rtfqueryServlet</servlet-name>
   <servlet-class>oracle.adfinternal.controller.rtfquery.RemoteTaskFlowQueryServlet</servlet-class>
   <load-on-startup>1</load-on-startup>
</servlet>
...
<!-- The servlet name here should be the same as the Faces Servlet. -->
<servlet-mapping>
   <servlet-name>Faces Servlet</servlet-name>
   <url-pattern>/rr/*</url-pattern>
</servlet-mapping>
...
<servlet-mapping>
  <servlet-name>rtfqueryServlet</servlet-name>
  <url-pattern>/rtfquery</url-pattern>
</servlet-mapping>

What You May Need to Know About Securing Remote Regions

By default, JDeveloper adds the <security-constraint> element shown in the following example when you configure an application to produce remote invocable task flows for remote regions. This security constraint restricts access to the remote region query servlet (rtfquery) to those users who have the role specified by the <role-name> element.

<security-constraint>
  <web-resource-collection>
     <web-resource-name>rtfquery</web-resource-name>
     <url-pattern>/rtfquery</url-pattern>
  </web-resource-collection>
  <auth-constraint>
     <role-name>valid-users</role-name>
  </auth-constraint>
</security-constraint>

You can remove this constraint from the web.xml file by selecting the Allow Unauthenticated Remote Region Query servlet requests checkbox when you configure an application to produce remote invocable task flows. For more information about how to access this checkbox, see How to Configure an Application to Produce Task Flows for Use in Remote Regions.

JDeveloper also generates the authentication mechanism shown in the following example when you configure an application to produce remote invocable task flows. This authentication mechanism determines if access to an ADF resource (for example, a task flow) that has been secured is permitted. The value CLIENT-CERT must appear here so that the producer application can authenticate clients that request access to a secured resource. The producer application ignores this setting if a client requests access to a non-secured resource.

<login-config>
  <auth-method>CLIENT-CERT,FORM</auth-method>
  <realm-name>Identity Assertion</realm-name>
</login-config>

In producer applications that define the security constraint (the default behavior), the value for the <auth-method> element in the associated authentication mechanism must at a minimum include CLIENT-CERT. If you make other changes that modify your web.xml file (for example, configuring ADF Security) after you configure an application to produce remote invocable task flows, you might overwrite the values required to make remote invocable task flows accessible to authenticated users. Verify the values specified for the security constraint and the authentication mechanism to make sure they are valid.

For more information about security, see Enabling ADF Security in a Fusion Web Application.

How to Configure an Application to Render Remote Regions

In the Fusion web application that you want to render remote regions, you configure a project so that it can consume remote invocable task flows from the producer application. You also create a connection to the producer application.

Once you have created this connection, you can drag a remote invocable task flow from wherever you defined the connection (Resources window or Application Resources panel) and drop it on the JSF page or page fragment where you want the remote region to render at runtime in your consumer application's page. The producer application of the remote invocable task flow that you want to invoke must be running in order for the remote invocable task flow to appear in the connection.

Before you begin:

It may be helpful to have an understanding of the configuration required before you attempt to configure an application to render remote regions. For more information, see Creating Remote Regions in a Fusion Web Application.

You may also find it helpful to understand functionality that can be added using other task flow and ADF region features. For more information, see Additional Functionality for Task Flows that Render in ADF Regions.

To configure an application to render a remote region:

1. In the Applications window, right-click the project that you want to configure to render a remote region and choose Project Properties.
2. Click the ADF Task Flow node and select the Enable Remote Region consumer support checkbox.
3. In the Resources window, click New, select New Connection and then Remote Region Producer.
4. In the Create Remote Region Connection dialog, select Application Resources if you want the connection to be available only within the application. Select Resources window if you want the connection to be available to other applications using the Resources window.
5. In the Name field, enter a name that the application will use to identify the connection to the producer application of the remote invocable task flows.
6. In the URL Endpoint field of the Query URL section, enter the URL endpoint for the Fusion web application that produces the remote invocable task flows. Typically, this URL has a format similar to the following:

   http://<host>:port/<context root>/rtfquery

   where rtfquery is the servlet that provides the list of remote invocable task flows in the producer application.

7. Click Test Connection to verify that the URL endpoint is valid.
8. In the URL Endpoint field of the Invoke URL section, enter the URL endpoint of the Fusion web application that produces the remote invocable task flows. Typically, this URL has a format similar to the following:

   http://<host>:port/<context root>/rr

   where rr is the url-pattern specified for the remoteApplication filter in the web.xml file of the Fusion web application that produces the remote invocable task flows.

9. If you know that the producer application requires user credentials before it will allow the consumer application access a remote invocable task flow, select the Always Send User Identity checkbox. This generates an identity token that the consumer application transmits to the producer application during the initial connection.

   Leave the Always Send User Identity checkbox clear if you do not know if the producer application requires user credentials. For more information, see What Happens at Runtime: How an Application Renders Remote Regions.

10. Click Test Connection to verify that the URL endpoint is valid and click OK.
11. Expand the Remote Region Producer node and drag the remote invocable task flow that you want your Fusion web application to invoke and drop it on the JSF page or page fragment where you want it to render in a remote region at runtime.
12. In the context menu that appears, select the type of region that you want to create in the page (Region or Dynamic Region).

    If you select Dynamic Region, you need to choose or create a managed bean that determines at runtime what bounded task flow to render in the ADF dynamic region. For more information, see Creating ADF Dynamic Regions.

13. In the Edit Task Flow Binding dialog, from the Remote Connection dropdown list, select the connection to the Fusion web application that produces the remote invocable task flow that you defined in Step 5.

    Typically, this is selected by default.

14. Click OK.

What Happens When You Configure an Application to Render Remote Regions

JDeveloper adds a context parameter to the application's web.xml file when you enable remote region consumer support in the project that consumes remote invocable task flows, as shown in the following example.

<context-param>
  <param-name>oracle.adf.view.rich.remote.AUTH_PROVIDER</param-name>
  <param-value>oracle.adf.view.rich.remote.security.ADFAuthorizationProvider</param-value>
</context-param>

This context parameter specifies the default authorization provider that is configured to work with ADF Security. You can add an alternative authorization provider by creating an object that implements the following interface:

oracle.adf.view.rich.remote.AuthorizationProvider

When you drag and drop a remote invocable task flow to the JSF page or page fragment in your application, JDeveloper adds an af:region tag to the JSF page and a task flow binding to the page definition file of the JSF page. These additions are similar to those generated when you drag and drop a task flow from the Applications window to a JSF page in the same application. One difference is that when you drag and drop a remote invocable task flow to a JSF page, the task flow binding that is added to the page definition file of the JSF page includes a remoteConnectionName attribute that references the connection name of the producer application, as shown in Example 26-3.

The task flow binding's remoteConnectionName attribute can also reference an EL expression that returns the name of the connection to the producer application at runtime. This is useful, for example, if the name of the producer application changes and you want to refresh the ADF region in response to this event. For more information, see Configuring an ADF Region to Refresh.

For more information about the entries that JDeveloper generates when you create an ADF region or an ADF dynamic region, see What Happens When You Create an ADF Region , and What Happens When You Create an ADF Dynamic Region.

Example 26-3 Metadata Added to Page Definition to Create a Task Flow Binding

<taskFlow id="dynamicRegion2"
      taskFlowId="${viewScope.ParentActionRegion.dynamicTaskFlowId}"
      activation="deferred" remoteConnectionName="RemoteAppProducingTFs"
      xmlns="http://xmlns.oracle.com/adf/controller/binding"/>

What Happens at Runtime: How an Application Renders Remote Regions

The initial runtime behavior of the applications that you have configured to produce remote invocable task flows and render remote regions depends on the security-related options configured for the producer application:

• It requires user credentials from the consumer application before it permits access to the rtfquery servlet to retrieve the list of task flows that can be invoked remotely.

  In this scenario, the producer application responds to the initial request with an error code. In response, the consumer application generates an encrypted identity token that it transmits to the producer application. The producer application uses this identity token to authenticate the consumer application and, if successful, serves the consumer application's request.

  If you know in advance that the producer application requires user credentials, you can make the consumer application submit the encrypted identity token with the initial connection by selecting the Always Send User Identity checkbox, as described in How to Configure an Application to Render Remote Regions. This optimizes the connection process.

• It allows unauthenticated requests to the rtfquery servlet.

  The consumer application retrieves the list of remote invocable task flows from the rtfquery servlet that the producer application configures to be invoked remotely.

After accessing the remote invocable task flow from the producer application, the consumer application renders the content from the task flow in an ADF region (the remote region) that is configured for this purpose. The appearance of this content is defined by the style properties in the ADF skin of the consumer application. The style properties in this ADF skin must match the style properties defined in the producer application's ADF skin. For more information, see What You May Need to Know About ADF Skins and Remote Regions.

If the consumer application invalidates the session that it established with the producer application, the producer application rolls back any transaction that is in progress at the time that the consumer application invalidates the session. Examples of events that can cause the consumer application to invalidate a session include:

• Reaching the time specified for session timeout in the consumer application

• An end user logging out of the consumer application

• An end user clicking the browser's back button

• Navigation to a different page that does not render the remote region

How to Add Custom Error Messages for Remote Regions

A variety of error messages appear in the consumer application if an error occurs in a remote region implementation. For example, you may see a message similar to that shown in Figure 26-18.

Figure 26-18 Error Message for Remote Region

The following examples show log messages that correspond to the message that appears in Figure 26-18.

...
<oracle.adf.view> <RegionRenderer> <_logError> <RR_HTTP_ERROR>
...
...
<oracle.adf.view> <RegionRenderer> <_logError> <Jan 29, 2014 12:50:51 PM oracle.adfinternal.view.faces.renderkit.rich.RegionRenderer _logError
ALL: Remote Region error #2: An uncaught exception was thrown on the producer at "http://127.0.0.1:7101/prod/rr/" while trying to run an ADF Taskflow.
> 
oracle.adf.controller.ControllerException: ADFC-14032: A required remote task flow input parameter value was not specified. Requested remote taskFlowId
 '/WEB-INF/task-flow-definition.xml#task-flow-definition'; requested from 'localhost.localdomain'.
	at oracle.adf.controller.internal.binding.TaskFlowRegionModelRemoteProducer.createRegionViewPortContext(TaskFlowRegionModelRemoteProducer.java:173)
	at oracle.adf.controller.internal.binding.TaskFlowRegionModelViewPort.getViewPort(TaskFlowRegionModelViewPort.java:649)
...

In many scenarios, the message in Figure 26-18 and log file entries may be sufficient to diagnose and resolve an issue with a remote region implementation. In other scenarios, you may want to present additional information to communicate to end users. Figure 26-19 shows a revised version of the consumer application page in Figure 26-18 that now displays additional information, such as the error type and the location of the producer application. Configuring your consumer application to show additional information, as in Figure 26-19, requires you to add a context parameter to the web.xml file of your consumer application and to write a Java class in the same application that extends RemoteRegionErrorListener from the following package:

oracle.adf.view.rich.model

Figure 26-19 Custom Error Message for Remote Region

To add a custom error message for a remote region:

1. In the user interface project of the consumer application, create a Java class that extends the oracle.adf.view.rich.model.RemoteRegionErrorListener class.

   The following example shows a Java class that listens for errors on a remote region and returns a string with details of the error message.

   package example;
    
   import oracle.adf.view.rich.model.RemoteRegionErrorEvent;
   import oracle.adf.view.rich.model.RemoteRegionErrorListener;
   import oracle.adf.view.rich.model.RemoteRegionHttpErrorEvent;
    
   public class MyRemoteRegionErrorListener extends RemoteRegionErrorListener {
    
       @Override
       public String getAdditionalUserInformation(RemoteRegionErrorEvent event) {
    
           RemoteRegionErrorEvent.Type type = event.getErrorType();
           StringBuilder sb =
               new StringBuilder().append("Received a(n) ").append(type);
    
           if (RemoteRegionErrorEvent.Type.HTTP_ERROR.equals(type)) {
               sb.append(" number ").append(((RemoteRegionHttpErrorEvent)event).getHttpErrorCode());
           }
    
           sb.append(" from ").append(event.getProducerURL());
    
           String viewId = event.getViewID();
           if (null != viewId) {
               sb.append(" for viewId ").append(viewId);
           }
    
           return sb.toString();
       }
   }
   
   

2. In the Applications window, in the user interface project, expand the Web Content and WEB-INF nodes, and then double-click web.xml.
3. In the overview editor for the web.xml file, click the Application navigation tab and in the Context Initialization Parameters section, click the Create icon to add a parameter that references the Java class you created in Step 1 as follows:

   Name: Enter the context parameter oracle.adf.view.rich.REMOTE_REGION_ERROR_LISTENER.

   Value: Enter the path to the Java class that you created in Step 1. For example, to reference the class in Step 1, enter example.MyRemoteRegionErrorListener.

What You May Need to Know About ADF Skins and Remote Regions

The style properties in the ADF skins of the consumer and producer applications must match in order for the remote region to render. If the ADF skins do not match, the remote region does not render its content. If the ADF skins match, the remote region renders and uses the consumer application's ADF skin to determine the look and feel.

If mismatches occur between the ADF skins for the consumer and producer applications, you need to modify one or both ADF skins so no mismatches occurs. Where mismatches occur the consumer application's client displays a message similar to the following:

Unable to retrieve content. Please see "Remote Region Error #1" in the server logs for more information.

The server logs refers to messages that appear in the log files of the application server for the consumer application. These log messages may provide information that you can use to identify mismatches between ADF skins or to diagnose issues with the ADF skin. The following list describes issues that result in the consumer application generating log messages:

• ADF_FACES-30209 identifies a mismatch between the ADF skins. It means that while the producer application can find the skin that the consumer application uses, the ADF skins are not the same. A message similar to the following appears:

  Remote Region Error #1: Producer at "http://myproducer.com/rr" does not have a skin that matches this consumer. Consumer skin information: {...} Producer skin information: {...}.

  The ADF skin information provided contains a checksum of the ADF skins and lists all of the skinning extensions (including checksum) and features employed by each ADF skin. The consumer and producer applications should have the same ADF skins and extensions. Using this data may help identify if there are differences between the two applications.

• ADF_FACES-30210 indicates that the producer application does not contain the ADF skin that the consumer application uses. A message similar to the following appears:

  Remote Region Error #1: Producer at "http://myproducer.com/rr" does not have the following skin: "simple"

• Producer application does not have a skin factory. This means that the producer application is not configured properly and cannot find an instance object that extends SkinFactory from the following package:

  org.apache.myfaces.trinidad.skin

  A message similar to the following appears:

  Remote Region Error #1: No skin factory available on the producer at "http://yourproducer.com/rr"

The consumer application logs the skin debug information using a VERBOSE setting.

Note:

The context parameter oracle.adf.view.rich.remote.PRODUCER_STYLESHEET_DEBUG_LEVEL that determines the level of log output is deprecated in release 12.2.1.4.0.

For a general overview of ADF skins, see the "Customizing the Appearance Using Styles and Skins" chapter in Developing Web User Interfaces with Oracle ADF Faces.