As Published In
Oracle Magazine
July/August 2014

TECHNOLOGY: Oracle ADF

  

Region Extreme: Multi-Task-Flow Binding

By Frank Nimphius

 

Render an unknown number of task flows in page or dashboard regions.

Oracle Application Development Framework (Oracle ADF) regions display the contents of bounded task flows in designated areas on a page. Each region uses a special binding configuration—the task flow binding—in the Executables section of the parent page’s PageDef.xml file to populate the region content with data from the Oracle ADF binding layer.

In use cases such as analytic dashboards, the contents of an unknown number of task flows must be displayed as regions at runtime. However, Oracle ADF regions cannot be created at runtime. Multi-task-flow binding in Oracle JDeveloper 11g Release 2 and Oracle JDeveloper 12c addresses this limitation. Using a hands-on exercise, this article shows developers how to use multi-task-flow binding in Oracle ADF applications. Parts of the sample application have been prebuilt to give you a head start. In addition to performing the hands-on steps, you can learn more by examining the source files.

To begin, download the sample application and unzip the o44adf-2197040.zip file to a local folder on your computer. Do not use spaces in the folder name. Ensure that you’re using the studio edition of Oracle JDeveloper 12c (12.1.2.0.0) or later, available as a free download on Oracle Technology Network.

Static, Dynamic, Multiple

The multi-task-flow binding feature is a combination of the static and dynamic task-flow-binding types used in Oracle JDeveloper to associate region content with the Oracle ADF binding layer and lifecycle.

A static region uses a dedicated task flow binding added to the PageDef.xml file of the parent page to associate the region content with a bounded task flow. The task flow binding contains a static reference to the bounded task flow to be exposed in the region.

Dynamic regions also use a dedicated task flow binding, which uses a property reference to a managed bean in view scope to provide the task flow reference information. The managed bean is accessible from Java code and through expression language (EL). The task flow reference returned by the managed bean property can be changed at runtime for the region to display the contents of different task flows sequentially.

In multi-task-flow binding, the multi-TaskFlow binding element provides the region component model for multiple Oracle ADF region instances that are created at runtime with the af:forEach loop tag of the Oracle ADF Faces feature of Oracle ADF. Each region obtains its bounded task flow configuration reference from a managed bean. As with dynamic regions, the content of the managed bean can be changed at runtime, thereby enabling the display at runtime of an unknown-at-design-time number of task flows in regions. The region binding is appropriate for uses such as dashboards that display varying numbers of bounded task flows on a page.

o44adf-f1

Figure 1: Sample application

Sample Application Overview 

The sample application is a dynamic dashboard that displays information for departments the user selects, as shown in Figure 1. Each department is exposed in a region with a read-only view shown first. An Edit button navigates the bounded task flow associated with each region to an edit page so the user can change the department data.

The user selects which departments to display on the dashboard by using the select-many checkboxes on the right-hand side and clicking the Update Dashboard button. The Reset Dashboard button sets the dashboard to the none-selected state and shows a single panel with instructions for the user.

The application uses Oracle ADF adaptive bindings to create multiple instances of a bounded task flow that share the Oracle ADF data control with the parent view for best performance. With this technique, the sample application can use a single task flow definition to simulate an unknown number of Oracle ADF regions to be displayed in an Oracle ADF view.

Sample Application Architecture

Figure 2 illustrates the architecture of the sample application. A managed bean instance holds a list of bounded task flow configurations that specify the number of region instances and the department information to display. The bounded task flow takes two input parameters and creates a new view object instance on the server to display the department data, identified by department ID.

o44adf-f2

Figure 2: Sample application architecture

The Home.jsf file contains a panel dashboard component that shows a variable list of Oracle ADF regions based on the configuration in the managed bean. The page accesses the task flow definition in the bean indirectly through the multi-task-flow binding added to the Oracle ADF page’s binding file, the PageDef.xml file.

An af:forEach iterator on the page references the task flow binding and creates an instance of af:region for each task flow configuration.

Getting Ready

The RegionExtreme workspace in the sample application download contains a completed Oracle ADF Business Components model (Oracle ADF Business Components is a feature of Oracle ADF) and a view-controller project with prebuilt artifacts such as managed beans, page fragments, and a bounded task flow.

To prepare this workspace for your environment, you must configure the database connection that the workspace is dependent on to access your HR database schema:
  1. In Oracle JDeveloper, select File -> Open, and navigate to the directory containing the unpacked zip file content.
  2. Open the oramag070814/RegionExtreme folder, and select the RegionExtrem.jws file. Click Open to load the workspace.
  3. Select Window -> Database -> Databases, and expand the RegionExtreme node to display the contained hrconn node.
  4. Right-click hrconn, and select Properties from the menu. Edit the database connection information to work with your setup. Test the changes, and click OK when the connection succeeds.
Next, start the Oracle WebLogic Server instance that’s integrated with Oracle JDeveloper, by selecting Run -> Start Server Instance.

 

If you are running the integrated Oracle WebLogic Server for the first time, a Create Default Domain dialog box will open. Create a password for the default Oracle WebLogic Server domain. To ensure that the integrated Oracle WebLogic Server listens for the localhost and the IP address of your computer, do not select an address from Listen Address.

Click OK to save the changes and to create and configure the default domain for Oracle ADF. Oracle WebLogic Server creates a default domain and then starts the server. Wait for the IntegratedWebLogicServer started. message on the Running: IntegratedWebLogicServer panel before proceeding to the steps in the next section.

Creating the Bounded Task Flow

The sample application uses a single parameterized bounded task flow to populate all region instances with different data content. For this technique to work correctly, the Oracle ADF bindings used in the task flow must be made configurable with the adaptive bindings technique:
  1. With the RegionExtreme workspace open in Oracle JDeveloper, click the Applications tab.
  2. Expand the ViewController -> Web Content -> WEB-INF -> btf node, and double-click the departments-flow.xml file to open the task flow diagram.
  3. On the Applications tab, expand the Data Controls panel and its AppModuleDataControl node.
  4. Drag the createNewDepartmentVO Instance() method entry onto the task flow diagram editor.
  5. In the Edit Action Binding dialog box, enter #{pageFlowScope.departments TaskFlowBean.departmentsId} as the departmentId value and #{pageFlow Scope.departmentsTaskFlowBean .voinstance} as the instanceName value. Click OK. A new method activity is created for you.
  6. Choose Window -> Components to open the Components window.
  7. Drag the View activity from the Components section of the Components window onto the diagram editor. Change the name of the view activity from view1 to Browse.
  8. Repeat step 11, but this time name the view activity Edit.
  9. In sequence, click Control Flow Case in the Components window, the method call activity in the diagram, and the Browse view activity in the diagram to create a navigation case. Keep the default name for the navigation case.
  10. Create a navigation case from the Browse view to the Edit view, and enter edit as the name of the navigation case.
  11. Create a navigation case from the Edit view activity to the Browse view activity, and name it return.
  12. Save your work.
What you just did: The method call activity you created references a method in the Oracle ADF Business Components application module that creates new instances of the DepartmentsView view object. The name of the new instance is saved in a prebuilt managed bean property. At runtime, the navigation cases you created are used to navigate between the department read-only view and the editable form.
  1. In the task flow diagram editor, double-click the Browse view activity to open the Create ADF Page Fragment dialog box.
  2. Click the magnifying glass icon next to the Directory field.
  3. In the Choose Directory dialog box, click the Create new subdirectory icon next to the Location field and create a new btf folder under the public_html folder. Under the btf folder you just created, create a departments folder. Click Select.
  4. Ensure that the Facelets and Create Blank Page options are selected in the Create ADF Page Fragment dialog box, and click OK to create the new page fragment.
  5. With the Browse page open in the visual editor, expand the Data Controls panel on the Applications tab and click the allDepartments collection.
  6. Drag the allDepartments collection to the page, and drop it as an Oracle ADF Form.
  7. In the Create Form dialog box, click the Read-Only Form and Submit checkboxes to create a read-only form and a button (which you’ll configure next) for navigating to the editable page. Click OK.
  8. Click Submit in the visual editor, and choose Window -> Properties.
  9. In the Properties inspector, change the Text property value to Edit and select edit as the value of the Action property.
  10. Click the Bindings tab at the bottom of the visual editor. In the bindings editor, select allDepartmentsIterator in the Executables section.
  11. In the Properties inspector, change the value of the Binds property to ${page FlowScope.departmentsTaskFlow Bean.voinstance}. Do not be concerned that a border now surrounds the Binds field.
  12. Save your work.
What you just did: You created a read-only view to display department data in the regions. Because the sample application uses a single bounded task flow definition to display department information for multiple regions, you used adaptive binding in the allDepartmentsIterator to dynamically determine which ViewObject instance to query data from.
  1. Click the departments-flow.xml tab to switch back to the task flow diagram editor.
  2. Double-click the Edit view activity, and use the magnifying glass icon next to the Directory field to select the departments folder in public_html/btf. Click Select, and then click OK.
  3. Drag the allDepartments collection from the Applications tab’s Data Controls panel to the page, and drop it on the Edit page as an ADF Form.
  4. In the Create Form dialog box, click the ADF Input Text w/Label value next to the DepartmentId value binding entry and change it to ADF Output Text w/Label. Then click the Submit checkbox and OK.
  5. Click Submit in the visual editor for the Edit page, and choose Window -> Structure.
  6. Right-click Submit in the Structure window, and choose Surround With.
  7. In the Surround With dialog box, select Panel Group Layout and click OK.
  8. In the Structure window, right-click af:panelGroupLayout and select Insert Inside Panel Group -> Spacer.
  9. Repeat step 36, except select Button instead of Spacer.
  10. In the visual editor, click the Submit button and change its Action property to #{backingBeanScope.edit DepartmentBacking.onSubmit} in the Properties inspector.
  11. Click the button 1 button. Using the Properties inspector, change the Text attribute to Cancel, the Action attribute to return, and the Immediate attribute to true.
  12. Save your work.
  13. Select the Bindings tab at the bottom of the visual editor for the Edit page.
  14. In the bindings editor, select allDepartmentsIterator in the Executables section.
  15. In the Properties inspector, change the value of the Binds property to ${page FlowScope.departmentsTaskFlow Bean.voinstance}.
  16. Save your work, and close all open page tabs. The bounded task flow is complete.
What you just did: You created an Oracle ADF bound input form in which users can edit department information in a region at runtime. The DepartmentId field in the form is configured to be read-only, and the Submit button action property references a prebuilt managed bean method to commit data changes before returning to the Browse page. The Cancel> button uses immediate=”true” so the Oracle ADF model is not updated with any changed data when the button is clicked. Like the Browse page, the Edit page uses adaptive binding to connect to the server-side ViewObject instance. 

 

Creating the Multi-Task-Flow Binding

Now create and configure the multi-task-flow binding:
  1. On the Applications tab, double-click the Home.jsf file in the ViewController -> Web Content -> utf node to open the page in the visual editor.
  2. Click the Bindings tab at the bottom of the visual editor.
  3. In the binding editor, click the green plus (+) icon in the Executables header.
  4. In the Insert Item dialog box, change the selection from Generic Bindings to ADF Task Flow Bindings.
  5. Select the multiTaskFlow, item, and click OK.
  6. In the Insert multiTaskFlow dialog box, add mtb1 as the value of the id attribute and ${viewScope.multiTaskFlowList Bean.multiTaskFlowBindings} as the value of the taskFlowList attribute. (You must use these exact values for the configuration to work with the prebuilt code the workspace uses.) Click OK.
  7. Save your work.
What you just did: You created and configured the multi-task-flow binding in the ADF PageDef file of the Home.jsf page. The task flow binding references the multiTaskFlowBindings property in the multiTaskFlowList Bean managed bean to obtain the list of task flows to render in regions. 

The managed bean reference is required immediately when the page renders, which is why the EL expression used starts with a $ character instead of the # deferral prefix.

The referenced managed bean is defined in the MultiTaskFlowListBean.java file, located in the oramag.sample.seven.eight.fourteen.view.utf.beans package hierarchy in the ViewController -> Application Sources folder. The managed bean class is documented with Java comments to help you understand how the multi-task-flow binding implementation works and how EL can be used in Java to provide individual input parameters for each task flow. 

Building the Region Dashboard

Next Steps 

 

DOWNLOAD
Oracle JDeveloper 12c
 the sample application for this article 

READ more about Oracle ADF
 oracle.com/technetwork/developer-tools/adf
 Using Task Flows as Regions
 Towards Ultra-Reusability for ADF - Adaptive Bindings
 A Template with Behavior

 

Next (with the help of prebuilt code segments), add an af:forEach component that adds the task flow binding instances defined in the multi-task-flow binding as regions to the Home.jsf page:
  1. On the Applications tab, double-click the forEachCodeSnippet.txt file in the ViewController -> Web Content -> utf node.
  2. Select all of the file’s contents (Ctrl+A), and copy them to the clipboard (Ctrl+C).
  3. Switch back to the Home.jsf page, and click the Source tab at the bottom of the editor window to show the page in source view.
  4. Select Window -> Structure to open the structure panel if it’s not already open.
  5. On the Structure panel, expand the f:view -> af:document -> af:form -> af:pageTemplate -> f:facet –> center node.
  6. Select af:panelDashBoard.
  7. In the page source, change (without using copy/paste) the af:panelDashBoard component definition (now highlighted) from
    
    <af:panelDashboard id="pd1" rowHeight="150px" />
    


    to

    <af:panelDashboard id="pd1" rowHeight="150px"> 
    </af:panelDashboard>
    

     

  8. Click between the opening and closing tags of the af:panelDashboard component, and paste (Ctrl+V) the code from the clipboard.
  9. Right-click in the source window, and choose Reformat to improve the code alignment.
Note: The af:panelDashBoard component expects af:panelBox or af:region as its child components. Because af:forEach is used to create the panelBox instances at runtime, you see that Oracle JDeveloper flags the af:forEach tag as an error. However, this is a false positive in the integrated development environment (IDE). It is not considered an error at runtime, and you can ignore it.
  1. Close all tabs, and save your work.
What you just did: You added a prebuilt code snippet to the panel dashboard component on the Home.jsf page that reads the number and definitions of task flows to display in a region from the multi-task-flow binding you configured earlier. In addition, the code you pasted contains a panel box that is shown whenever no department is selected for display as a region on the dashboard. 

 

Running the Application 

  1. On the Applications tab, navigate to ViewController -> Web Content -> WEB-INF and double-click the adfc-config.xml file.

  2. In the task flow diagram, right-click the Home view activity and choose Run. (You must run the page from the adfc-config.xml file—not from the Applications tab—so that the task flow context is set when the page displays.)
  3. When the page displays in your browser, use the checkboxes on the right to select the departments to display on the dashboard. Click the Update Dashboard button to update the dashboard view, and try out the other dashboard features.

Conclusion

Dynamic regions are a frequent user requirement. Oracle JDeveloper 11g Release 2 and Oracle JDeveloper 12c address this requirement with multi-task-flow binding. This article showed how to add dynamic bindings for a dynamic dashboard that uses a single bounded task flow to render an unlimited number of regions, with each region sharing the Oracle ADF data control scope for best performance.

Task flows in regions execute sequentially. When you use the multi-task-flow binding feature, minimize the number of flows added to a page. Each task flow comes with a performance overhead determined by the data query and the initialization tasks it performs.

Also note that when an application uses dynamic regions, users might switch between bounded task flows while task flows have pending transactions. The risks associated with premature termination of bounded task flows through dynamic regions and how to handle such a case are documented in the “Oracle ADF Task Flow Transaction Fundamentals” white paper.


Frank Nimphius is a senior principal product manager for Oracle JDeveloper and Oracle ADF. He is a coauthor of Oracle Fusion Developer Guide: Building Rich Internet Applications with Oracle ADF Business Components and Oracle ADF Faces (McGraw-Hill). 

Send us your comments