Application Development

Implement Contextual Events

Use Oracle Application Development Framework’s Contextual Events feature for interregion communication.

By Frank Nimphius

May/June 2011

Oracle Application Development Framework (Oracle ADF) views (pages or page fragments) can host multiple bounded task flows exposed in regions, with each region optionally containing nested regions. Contextual Events is an Oracle ADF feature that enables developers to implement view-to-region, region-to-view, and region-to-region communication.

Among the options for passing information to and from regions, Contextual Events is the most powerful and the option that does not make regions refresh or require the referenced bounded task flow to restart. If you plan to build reusable bounded task flows or to use the UI Shell pattern template for desktop-like application user interfaces, the Contextual Events feature is the solution of choice for establishing region interaction. This column explains contextual events and shows how to use them.

As an exercise, you’ll augment an existing application by adding contextual events to it. The application uses the HR schema, available by default in Oracle Database. You’ll associate a value change event with a text input field and an action event with a button. At runtime, whenever a user changes certain data values in a form, the associated contextual events will cause the new values to display automatically in multiple regions on the same page.

To begin, download the workspace and ensure that you’re using the Oracle JDeveloper 11g ( production release, available as a free download on Oracle Technology Network at Extract the contents of the file. Note that it contains both starter-app and completed-app folders.

About Contextual Events

Contextual events have two parts:

  • A publisher (or producer), such as a button that raises a named event, with or without a custom payload

  • A handler (or consumer) that listens for a specifically named event or a wildcard event, to process that event

The Contextual Events feature leverages the Oracle ADF binding layer, passing event notifications and payloads to registered event handlers in a bounded task flow or a parent view. Payloads are passed as arguments to the method that processes events on the handler. The payload content is customizable. By default, the payload for a contextual event is a JavaServer Faces, an Oracle ADF Faces, or an Oracle ADF binding event object.

A view containing regions defines a task flow binding in the executables section of its page definition file. The binding hierarchically connects all binding containers that are initialized at a given time for a current browser page. The event notification is published to event mappings defined in an initialized binding container. Events are passed to the local binding container first and then published to parent and sibling containers.

Events are first handled by event mappings that specify the event and the producer name in their configuration. Event maps that contain only the event name but specify a wildcard character (an asterisk) for the producer name are notified last. You can suppress wildcard event handling through a configuration change in the page definition file or the adf-config.xml file.

Defining the Event Handler

You’ll start this column’s exercise by creating a contextual event consumer and deploying it to an Oracle ADF library. Launch Oracle JDeveloper and open the OraMagMirrorTaskFlow.jws workspace in the starter-app folder. In the Application Sources zone of the MirrorTaskFlow project in the Application Navigator, select the file in the data control package so you can examine the source code. The file contains two public methods—handleEventObjectPayload() and handleEventStringPayload()—for handling contextual events. In response to an event, the code uses a javax.el.ValueExpression to access a managed bean that updates a read-only input text field in the project’s page fragment.

Because Contextual Events is a feature of the binding layer, all event handlers must be exposed as action or method bindings in the page definition file of the view that is supposed to change in response to an event.

Right-click in the Application Navigator and choose Create Data Control. This step exposes the event handler methods in a JavaBean data control. Next select the DataChangeDisplayPageDef.xml file entry in the adf.sample.oramag pageDefs package and select View -> Structure from the main menu. In the Structure window, right-click the bindings node and choose Insert Inside Bindings -> Generic Bindings -> methodAction. In the Create Action Binding dialog box, select the EventHandler data collection and choose one of the two event handler methods in the Operation list. Click OK, and repeat the same steps for the other method. In the Structure window, expand the two method bindings you’ve just inserted and note that each has a customPayLoad argument, as shown in Figure 1.

o31adf figure 1

Figure 1: Method bindings with customPayLoad arguments

Next you’ll deploy the contextual event consumer in an Oracle ADF library. In the Application Navigator, right-click the MirrorTaskFlow project and choose Deploy -> OraMagMirrorTaskFlow. Then click Finish in the Deployment Action dialog box. The Oracle ADF library JAR file is created in the project’s Deploy folder.

Creating Producer Events

Now you’ll switch to a different project and create two contextual event producers. Open the OraMagMirrorTaskFlowConsumerApp.jws workspace, located in the starter-app folder.

First you’ll create a producer event without a custom payload, so that the event object will become the payload by default. In the Application Navigator, double-click the DepartmentsView.jspx file in the View Controller project. In the visual editor, select the DepartmentName field and open the Property Inspector. In the Property Inspector, open the Behavior node, scroll to Contextual Events, and click the green plus (+) icon under the Published Events header.

Select Create New Event, and enter departmentNameChange for Name. You’ll use this name later to identify the producer event when mapping it to the event handler. The Raise Condition tab enables you to enter an expression language (EL) expression defining a condition under which an event is propagated. On the Documentation tab, you can enter a text description of the event producer; the description is visible when you map the producer to event handlers. Leave the Raise Condition and Documentation tabs unchanged, and click OK.

DCBindingContainerValueChangeEvent is the event object class that is passed for Oracle ADF–bound value changes. (If an input field is not Oracle ADF bound, the payload object will be javax.faces.event.ValueChangeEvent.)

In the Application Navigator, select the DepartmentsViewPageDef.xml file in the adf.sample.oramag.view.pageDefs package and open the Structure window. Expand the bindings -> DepartmentName node to see the event definition you created for this attribute.

Now you’ll create a second producer event—one with a custom payload. In the visual editor for the DepartmentsView.jspx file, click the Submit Custom Payload button and create a new contextual event from the Contextual Events category in the Property Inspector’s Behavior section. Enter commandActionCustPayLoad for Name. Check the Pass Custom Value from box. Choose the Page Data option, and select the ManagerId entry, as shown in Figure 2. By doing so, you’re overriding the default payload object (javax.faces .event.ActionEvent) and replacing it with the ManagerId value. Click OK to create a new eventBinding definition of type javax.faces.event.ActionListener in the DepartmentsViewPageDef.xml file. This contextual event will fire when a user clicks the application’s Submit Custom Payload button.

o31adf figure 2

Figure 2: Creating a contextual event producer with a custom payload

The eventBinding is referenced from the button’s ActionListener property with expression language: #{bindings.eventBinding .listener.processAction}. Developers can also invoke contextual events from Java code in a managed bean by casting the eventBinding reference to JUEventBinding and calling the getListener method.


Adding Regions from the Oracle ADF Library to the Application

Now you’ll add the event handler regions to the sample application. The first step is to create a Resource Catalog file connection to the Deploy folder holding the Oracle ADF library JAR file you created earlier. Choose View -> Resource Palette from the main menu, and click the folder icon at the top. Choose New Connection -> File System, create a connection with the name OramagTaskFlow, and then browse to the starterapp/mirrortaskflow/deploy folder to fill in the directory path. In the Application Navigator, select the ViewController project. Then, in the Resource Palette, expand the file connection and select the OraMagMirrorTaskFlow.jar library, making sure the ViewController project is still selected in the Application Navigator. Right-click the library and choose Add to Project. In the Confirm Add ADF Library dialog box, click Add Library.

With the DepartmentsView.jspx file open in the visual editor, open the Component Palette and select OraMagMirrorTaskFlow.jar from the list at the top. Refresh the Regions accordion by clicking it.

Drag the OraMagazineMirror task flow entry from the Component Palette onto each of the four named panel boxes on the right side of the visual editor. For each drag, select Region from the menu that appears when you release the mouse button.

Mapping Event Handlers to Events

Producer events and event handlers are mapped to one another in page definition files. If the event mapping page definition file does not own the producer event or have a binding reference to it, an asterisk wildcard character will need to be used as the producer name.

To start mapping contextual events for the four regions you created in the preceding section, click the Bindings tab in the DepartmentsView.jspx page visual editor. Select the Contextual Events tab and click the Subscribers tab.

Click the green + icon under the Event Subscribers heading to open the Subscribe to Contextual Event dialog box. Click the magnifier icon next to the Event field, and select the departmentNameChange event as the event to subscribe to. Click OK.

Choose DepartmentsViewPageDef.DepartmentName from the Publisher list, and click the magnifier icon next to the Handler list.

In the Select Handler dialog box, expand the OracleMagazineMirror1 task flow binding and select handleEventObjectPayload. Click OK. On the Parameters tab of the Subscribe to Contextual Event dialog box, click the green + icon.

Double-click the parameter Name field, and type customPayLoad (the name of the argument defined in the event handler method). Type ${payLoad} (note the uppercase L) in the Value field to reference the event object.

Add three more subscribers, as outlined in Table 1, to create event mappings for all Oracle ADF regions in the panel boxes. For all subscribers you create, use the customPayLoad parameter name and the ${payLoad} value for referencing the event object.


Event Publisher Handler
commandActionCustPayload DepartmentsViewPageDef .eventBinding OraMagazineMirror2 … handleEventStringPayload
departmentNameChange < Any > OraMagazineMirror3 … handleEventObjectPayload
commandActionCustPayload < Any > OraMagazineMirror4 … handleEventStringPayload
Table 1: Values for mapping the remaining three subscribers

Choosing < Any > for Publisher sets the asterisk wildcard character to be the producer name. You can use < Any > to listen to multiple event producers and also when the event producer cannot be referenced directly from the page definition file of the event map. The Handle Condition tab of the event map can be used to make event dispatching conditional.

Running the Application

Select View -> Database -> Database Navigator and edit the hrconn connection properties to connect to a local HR schema. Return to the Application Navigator, right-click the DepartmentsView.jspx file, and choose Run. In the page that appears in your browser, change the DepartmentName field value and click the Submit Default Payload button. This broadcasts the contextual event to the event handlers that are configured to consume the value change event. As you can see, Mirror Value changes accordingly in the two ValueChange Event Object Payload regions. Provide a new value for ManagerId and click the Submit Custom Payload button to notify the event handlers that are configured to consume the action event. Note that Mirror Value changes accordingly in the two Command Button Custom Payload regions.

If you change both the DepartmentName value and the ManagerId value and then click the Submit Custom Payload button, all the mirror values will be updated, because the value change event and the command action event will both be published.

If you have not successfully completed the exercise, you can examine the finished application and see it in action by opening the OraMagMirrorTaskFlowConsumerApp.jws workspace from the completed-app folder and running DepartmentsView.jspx.


The Oracle ADF Contextual Events feature provides a powerful mechanism for passing parameters to share information among pages and regions. To learn more about contextual events, see section 28.7, “Creating Contextual Events,” in Oracle Fusion Middleware Fusion Developer’s Guide for Oracle Application Development Framework 11g Release 1 (

Next Steps

LEARN more about  Oracle Fusion Middleware Fusion Developer’s Guide for Oracle Application Development Framework 11g Release 1 (  Oracle Fusion Developer Guide: Building Rich Internet Applications with Oracle ADF Business Components and Oracle ADF Faces (McGraw-Hill, 2010)  Oracle ADF Insider seminar series

READ more Nimphius
 Oracle ADF Code Corner
 Oracle Technology Network Harvest blog

DISCUSS Oracle JDeveloper and Oracle ADF
 Oracle JDeveloper forum

 DOWNLOAD the sample application for this column


Photography by Stefan Stefancik, Unsplash