TECHNOLOGY: Oracle ADF
Calling HomeBy Frank Nimphius
Here’s a bean reference technique to enable Oracle Application Development Framework regions to make callbacks to their parent pages.
One of the core architecture patterns in Oracle Application Development Framework (Oracle ADF) that promotes modular software design is the ability to expose bounded task flows in regions on a page. For a region to make callbacks to the owning page or view at runtime, developers typically use one of the following techniques:
Using contextual events, covered in two previous Oracle Magazine articles (see “Implement Contextual Events” and “Master and Commander”), is the most powerful technique for page-to-region and region-to-region interaction, and it also enables communication with nested regions. However, setting up contextual events is complex, and many developers balk at the unnecessary overhead for simple region communication use cases.
The bean reference technique explained in this article is easy to implement and well suited for many region communication use cases, making it an important part of the everyday toolbox of an Oracle ADF developer. This article explains how to configure and use a managed bean reference as a communication channel between a region and its parent page or view and includes a hands-on tutorial for you to walk through, using a provided sample application.
Note that for the rest of this article, the parent page task flow is referred to as the parent task flow. The page or page fragment (view) containing the region is referred to as the parent page.
As shown in Figure 1, the bean reference technique involves two managed beans. The first managed bean is defined in view scope of the parent task flow, and the other bean is defined in pageFlowScope of the bounded task flow that is exposed in the region.
Figure 1: Bean reference technique design-time architecture
The managed bean of the parent task flow is passed as a reference to an input parameter that is defined on the bounded task flow exposed through the region. The bounded task flow saves the bean reference in a variable of its pageFlowScope bean. Using the reference to the managed bean in the parent task flow, the bounded task flow can then invoke methods on the bean or pass information to the parent task flow.
To understand why this technique works, it is important to review bean scopes and lifecycles. A managed bean configured in view scope lives as long as the page from which it is referenced remains active. The lifecycle of a task flow exposed in a region starts during the rendering of the parent page (unless the activation property is set to deferred). The task flow is dismissed when the application navigates away from the parent page, at which time the bounded task flow managed bean also becomes available for garbage collection.
As a result, both managed beans in our bean reference design—the managed bean in view scope of the parent task flow and the managed bean in page flow scope of the bounded task flow in the region—exist for as long as the parent view is shown. Because both beans live at the same time, it is safe to pass a bean reference from the parent task flow to the bounded task flow in the region without risking a null pointer exception or losing state.
Sample Application Overview
Figure 2 shows the runtime view of the application you will build by following the tutorial. The browser page contains two tables: one with department data and one with employee data. It also contains a read-only form showing data in the most recently selected table row.
Figure 2: Updating the parent page form by selecting a row in a region
The page fragments that contain the departments table and the employees table are exposed by two separate regions. Whenever a user selects a new row in either the departments table or the employees table, the selected row data is sent from the bounded task flow in the region to the parent page for display.
Configuring the Sample Application
To follow the steps in this article, you need the studio edition of Oracle JDeveloper 11g Release 2 (126.96.36.199), available as a free download on Oracle Technology Network. You also need access to an Oracle Database instance with an unlocked HR schema. Get started by downloading the o33adf-1916752.zip sample application file and unzipping the file.The first task is to change the database connection to point to your HR database schema:
Next, start the Oracle WebLogic Server instance integrated with Oracle JDeveloper. To do so, select Start Server Instance from the Run menu.
If this is the first time you’ve run the integrated Oracle WebLogic Server, a Create Default Domain dialog box will open. Create a password for the default Oracle WebLogic Server domain, and select an address from those listed for Listen Address. For example, choose localhost rather than leaving the address empty.
Click OK to save the changes and to create and configure the Oracle ADF default domain.
The RegionParentCommunication.jws workspace you opened in Oracle JDeveloper 11g Release 2 is the starting point for the following hands-on instructions. All the task flows, page fragments, and implementation code have already been prepared, so you can focus on configuration of the region-to-parent-page communication.
You will perform the following tasks in this tutorial:
Because parts of the sample application have already been created, it is important that you follow the hands-on instructions closely. A completed sample, for which you need only to configure database access, is provided in the download.
Setting Up the Department Task FlowFor the departments task flow to hold a reference to a managed bean defined in the parent task flow, you need to create a managed bean in the bounded task flow to store the bean reference. You also need an input parameter that receives the reference at runtime. Follow the steps below to complete those tasks:
In this section, you created a managed bean you will reference as the value target of a new bounded task flow input parameter.
Overriding the Departments Table Selection ListenerNow that the departments task flow is configured, the next step is to wire up the table with the managed bean in pageFlow scope. This step will enable selected row data to pass to the parent page whenever a user selects a table row in the user interface. To perform this task, you need to override the SelectionListener of the table, as shown below.
In this section, you changed the default row selection behavior, and by doing so, you synchronized the table selection with the Oracle ADF binding layer to invoke a method on the managed bean superclass. The onRowSelect method of the superclass does two things: it synchronizes the user row selection with the binding layer, and it notifies the parent task flow bean about the selection change. To handle these tasks, it uses the parentHandle variable you passed in as an argument.
Configuring the Parent Task Flow BeanIn this sample application, the managed bean that dispatches the messages sent from the regions to the parent page is configured in the unbounded task flow definition (adfc-config.xml). To build and configure the managed bean, follow these steps:
Adding the Regions to the Parent Page
Almost there! The next step is to add the departments task flow (departments-task-flow.xml) and the employees task flow (employees-task-flow.xml) to the ParentPage.jsf file as a region. Note that the employees task flow has been fully precreated for this tutorial, so there is no need for you to build it first.To perform this task, you need to pass the ParentPageBean managed bean reference as an input argument to the region to set up the communication link.
Running the Sample
The ParentPage.jsf page contains an output text box for displaying the region ID of an incoming message as well as an af:forEach Oracle ADF Faces tag to print the message sent from the bounded task flow. Both UI components of the Oracle ADF Faces feature of Oracle ADF reference the ParentPageBean managed bean, which is why it was important that you used the names suggested in this tutorial.Run the page by following the steps below:
This article explained a technique for establishing region-to-parent-page communication by using a managed bean reference. Although the article doesn’t cover it, you can also extend this technique by using the parent task flow as a dispatcher to implement bidirectional region-to-region interaction—a testament to the power of this approach. By using bounded task flow templates to define the bounded task flow input parameter and managed bean, you can make the bean reference technique a part of your overall task flow design strategy. This approach adds a powerful new tool to your Oracle ADF toolbox.
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, 2010).