12 Configuring Local Interportlet Communication

This chapter discusses IPC and describes the IPC techniques available to portlet developers.

This chapter includes these topics:

Section 12.1, "Introduction"
Section 12.2, "Overview of Interportlet Communication Techniques"
Section 12.3, "Differences Between Portal Events and Java Portlet Events"
Section 12.4, "Portlet Event Handling"
Section 12.5, "Using the Portlet Event Handlers Wizard"
Section 12.6, "Custom Event Handling"
Section 12.7, "Events in Java Portlets"
Section 12.8, "Subscribing Java Portlets to Portal Framework Events"
Section 12.9, "Public Render Parameters"
Section 12.10, "Shared Parameters"
Section 12.11, "IPC Special Considerations and Limitations"
Section 12.12, "About QNames and Aliases"

12.1 Introduction

Interportlet communication (IPC) describes a handful of technologies and features that allow portlets to share data and react to events. This chapter discusses the IPC techniques supported by WLP.

Tip:

A good way to learn about how to use IPC in WLP is to work through the comprehensive example in Chapter 13, "Interportlet Communication Example With Event Handling."

For an overview of the IPC methods supported by WLP, see Section 12.2, "Overview of Interportlet Communication Techniques." The remainder of the chapter discusses each IPC method in greater detail.

12.2 Overview of Interportlet Communication Techniques

WLP supports several types of interportlet communication. You need to determine which type of IPC works best for your application. For instance, if you simply want to make some data from one portlet available to another, public or shared render parameters might be the best, simplest approach. If your application requires a portlet to notify other portlets that it has changed, then event handling is the best approach.

Table 12-1 summarizes the IPC techniques that WLP supports and discusses the advantages or disadvantages of each one.

Table 12-1 Interportlet Communication Features of WLP

IPC Feature	Description	Support	Notes and Recommendations
Events	All WLP portlet types, including remote portlets, support event handling. The event framework allows portlets to fire and receive events. Event handling is the primary focus of this chapter. Note: For information on using event handling for remote (WSRP) portlets, see "Interportlet Communication for Remote Portlets" in the Oracle Fusion Middleware Federated Portals Guide for Oracle WebLogic Portal.	All portlet types	In general, event handling is the recommended technique for IPC. Events support complex payloads, permit chaining, support notification, and present a loose coupling between portlets.
Public Render Parameters (JSR 286 Portlets) and Shared Parameters (Other Portlet Types)	Public render parameters and shared parameters allow portlets to share simple String values with other portlets. When any portlet makes a change to a shared parameter, other portlets which share that parameter will always see the latest value set for that parameter. For details, see Section 12.9, "Public Render Parameters" and Section 9.3, "Using Shared Parameters."	All portlet types	An advantage to using public render parameters and shared parameters over event handling is that you avoid the need for an explicit event handler, because the Portal framework automatically provides the latest values of shared parameters to all portlets that subscribe to them. Unlike events, shared parameters do not provide an explicit notification when a value changes.
Custom Data Transfer (remote portlets only)	Custom data transfer provides a simple way to pass data between producers and consumers in a federated portal environment. For detailed information on custom data transfer, see "Transferring Custom Data" in the Oracle Fusion Middleware Federated Portals Guide for Oracle WebLogic Portal.	Remote portlets only	Generally, the recommended best practice is to use event handling or public render parameters / shared render parameters instead of custom data transfer for remote IPC.

IPC Feature

Description

Support

Notes and Recommendations

Events

All WLP portlet types, including remote portlets, support event handling. The event framework allows portlets to fire and receive events. Event handling is the primary focus of this chapter.

Note: For information on using event handling for remote (WSRP) portlets, see "Interportlet Communication for Remote Portlets" in the Oracle Fusion Middleware Federated Portals Guide for Oracle WebLogic Portal.

All portlet types

In general, event handling is the recommended technique for IPC. Events support complex payloads, permit chaining, support notification, and present a loose coupling between portlets.

Public Render Parameters (JSR 286 Portlets)

and

Shared Parameters (Other Portlet Types)

Public render parameters and shared parameters allow portlets to share simple String values with other portlets. When any portlet makes a change to a shared parameter, other portlets which share that parameter will always see the latest value set for that parameter.

For details, see Section 12.9, "Public Render Parameters" and Section 9.3, "Using Shared Parameters."

All portlet types

An advantage to using public render parameters and shared parameters over event handling is that you avoid the need for an explicit event handler, because the Portal framework automatically provides the latest values of shared parameters to all portlets that subscribe to them. Unlike events, shared parameters do not provide an explicit notification when a value changes.

Custom Data Transfer (remote portlets only)

Custom data transfer provides a simple way to pass data between producers and consumers in a federated portal environment. For detailed information on custom data transfer, see "Transferring Custom Data" in the Oracle Fusion Middleware Federated Portals Guide for Oracle WebLogic Portal.

Remote portlets only

Generally, the recommended best practice is to use event handling or public render parameters / shared render parameters instead of custom data transfer for remote IPC.

12.3 Differences Between Portal Events and Java Portlet Events

The Java portlet specification version 2.0 (JSR 286) provides a model for handling events that is slightly different from the event model WLP uses for other portlet types. This section describes some of the differences between the event models.

In the WLP event model, you can declare event handlers that have a variety of possible actions, such as firing another event, changing the portlet's mode or state, or invoking a method on the backing file. The Java portlet event model supports only one action when an event is received: the processEvent() method (or another method, if properly annotated) is called on the portlet. The event handling code in the Java portlet can then take whatever actions are necessary, such as firing another event or changing the portlet's mode or state.

The WLP event model allows portlet event handlers to listen to events coming only from certain portlets. The Java portlet event model does not support this behavior directly, but this can be achieved by including information about the sending portlet in the event's payload, and having the receiving portlet take appropriate action based on this information.

The WLP event model allows portlets to receive events only if they were generated for the particular portlet instance (the Self Instance Only option). For example, check the Self Instance Only checkbox if you want a portlet to receive an event when it is minimized, but not to receive an event when another portlet is minimized. The Java portlet event model does not have any corresponding concept, but by default some event types (refresh, activation, deactivation, mode change and state change events) are only delivered to Java portlets if the event was generated for the particular instance. For details, see Section 12.8, "Subscribing Java Portlets to Portal Framework Events." Note that this model does not prevent functionality available to other portlet types, but it does require a bit more code to achieve.

For example, if Portlet A wants to know when Portlet B has been minimized and both are Java portlets, only Portlet B will receive the event when it is minimized. However, in its event handler method, Portlet B can send another event to which Portlet A can subscribe to let Portlet A know that Portlet B was minimized.

The WLP event model also allows portlets to receive events only if the portlet is currently being displayed; the Java portlet event model has no equivalent concept- events are always sent to Java portlets whether or not they are being displayed.

All events sent from Java portlets are treated as custom events for other portlet types. For example, if in a Java portlet you use the following code:

actionResponse.setEvent(new QName("sampleNamespace", "sampleEvent"), null);

Other portlet types can receive this event by declaring a custom event handler with a QName consisting of the namespace sampleNamespace and local part sampleEvent.

12.4 Portlet Event Handling

Events are supported for all of the portlet types supported by WLP and are the recommended mechanism for performing IPC in WebLogic Portal. Events permit chaining, support notification, and present a loose coupling between portlets. Portlet events can optionally carry accompanying data called a payload, which is a serializable Java object.

While events are supported for all portlet types, they are surfaced to Java portlets slightly differently, to comply with the JSR 286 specification. For all portlet types, event handlers may be declared in the .portlet files, but for JSR 286 portlets to remain compatible with other Java Portlet containers, they must exclusively use Java Portlet Events. For more information, see Section 12.7, "Events in Java Portlets."

The Portlet Editor provides a Portlet Event Handlers dialog for configuring events on a portlet. Three components that must be configured for all portlet event types declared in .portlet files are:

Event Handlers – Handlers specify which type of event the portlet will listen for. Types of event handlers include portal events, custom events, faces events, and others. For a complete list and descriptions, see Table 12-2.
Actions – You specify an action to perform in response to an event. Actions include changing the window mode, changing the window state, firing a custom event, and others. For a complete list and descriptions, see Table 12-3.
Event Name – Each type of event handler requires an event name or action to be specified. The portal event handler is designed to respond to pre-defined events, such as the event fired when a portlet is minimized (onMinimize event). The custom event handler, on the other hand, responds to a named event that is typically fired programmatically from a JSP or Java class. In a similar way, the page flow handler responds to a named Action.

This section contains the following topics:

Section 12.4.1, "Event Handlers"
Section 12.4.2, "Event Actions"
Section 12.4.3, "Event Types"
Section 12.5.4, "Definition Labels and Interportlet Communication"

12.4.1 Event Handlers

Event handlers listen for events raised on subscribed portlets and fire one or more actions when a specific event is detected. An event handler element is a child of the <portlet> element, and a portlet can have any number of events associated with it. Table 12-2 lists the event handlers that are available on the Add Handler menu of the Portlet Event Handlers wizard:

Table 12-2 Event Handlers

Event	Description
Handle Generic Event	Generic event handlers respond to all kinds of events, custom events, portal events, Struts events, and so on. A generic event handler just requires the event name to process the event. For details, see Section 12.4.1.1, "Generic Event Handlers" below. Note: Generic Events are deprecated. Oracle recommends that you use another event handler.
Handle Portal Event	Portal events are fired in response to certain kinds of actions that occur within the portal. The actions include state and mode changes. An example of a state change is minimizing a portlet. When you click the minimize button, an onMinimize event is fired. Mode change events are fired when a user clicks the edit or help button on a portlet. In addition, a portal event is fired when a portlet is refreshed. Portal event handlers do something in response to a portal event.
Handle Custom Event	Custom events are fired by you, the developer. Custom events can be fired from the handlePostbackData() method of a backing file or from an event handler. See Section 12.6, "Custom Event Handling" for more information.
Handle PageFlow Event	Page flow events are sent by the framework automatically when a page flow action is triggered. You can define a page flow event handler (on that portlet) that responds to these events and performs actions, such as to notify other portlets (that is, raise a custom event) or invoke a backing file call-back method, and so on. Note: Page Flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.
Handle Struts Event	Struts events are fired automatically by the framework when a Struts action is triggered. You can define a Struts event handler (on that portlet) that responds to these events and performs actions, such as to notify other portlets (that is, raise a custom event) or invoke a backing file call-back method, and so on. Note: Apache Struts is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.
Handle Faces Event	Faces events are fired automatically by the framework when a JSF action is triggered. You can define a Faces event handler (on that portlet) that responds to these events and performs actions, such as to notify other portlets (that is, raise a custom event) or invoke a backing file call-back method, and so on.

12.4.1.1 Generic Event Handlers

The generic event handler, with an event attribute value of myEvent, will be triggered on the following conditions:

A custom event with event=myEvent is fired within the portal.
A page flow action with name myEvent is raised by a portlet within the portal.
The same conditions to which the <handlePortalEvent event=myEvent> handler would react.
A generic event (see below) with event=myEvent is fired within the portal.

Using a generic event handler allows you to more effectively decouple your portal design, because your application does not need to know the source or type of an event. You can change the portlet type (for example, from a page flow portlet to a JSP portlet, with a backing file firing custom events) without affecting how you events are processed.

Note:

Because of the non-specific way generic event handlers are triggered, it is possible that they will be triggered by an event that isn't intended. Because of this, generic events and generic event handlers have been deprecated by Oracle going forward, and it is recommended that you use the event handler for the specific type of event you wish to trap. Previous limitations regarding WSRP changing event types to generic events have been eliminated, so there is no longer any reason to use a generic event handler.

12.4.2 Event Actions

When event handlers are triggered by receiving an appropriate event, they perform a configurable action on the host portlet. Triggering events may come from another portlet in the application, or possibly from the same portlet, depending on the type of event and how the handler is configured. For example, when the user minimizes a portlet, a portal event called onMinimize is sent, which causes any event handlers listening for it to perform their actions, such as firing a custom event or calling a method on the portlet's backing file.

Table 12-3 lists the event actions available for portlets.

Table 12-3 Event Actions

This action...	Has this effect...
Change Window Mode	Changes the mode from its current mode to a user-specified mode; for example, from help mode to edit mode.
Change Window State	Changes the state from its current state to a user-specified state; for example, from maximized to delete state.
Activate Page	Opens the page on which the portlet currently resides.
Fire Generic Event	Fires a user-specified generic event. Generic events have been deprecated; Oracle recommends that you use custom events instead.
Fire Custom Event	Fires a user-defined custom event.
Invoke BackingFile Method	Runs a method in the backing file attached to the portlet. For more information on backing files, refer to Section 9.4, "Backing Files."

12.4.3 Event Types

An event action depends upon the type of event being raised. Except for portal events, all other events can be identified in the Events field on the Portlet Event Handlers Wizard, as described in Section 12.5, "Using the Portlet Event Handlers Wizard." Events available with the portal event handler are listed in Table 12-4.

Table 12-4 Events Available to a Portal Event Handler

This event...	Fires an action when the portlet...
onActivation	Becomes visible
onDeactivation	Ceases to be visible
onMinimize	Is minimized
onMaximize	Is maximized
onNormal	Returns to its normal state from either a maximized or minimized state
onDelete	Is deleted from the portal
onHelp	Enters the help mode
onEdit	Enters the edit mode
onView	Enters the view mode
onRefresh	Is refreshed
onInit	The onInit event is broadcast once per portal request. Use this event if you want to define an event handler that is always executed on every portal request.
onLookAndFeelReinit	This event is fired when a Look & Feel is re-initialized. This happens whenever the Look & Feel is dynamically changed, such as when any of the reinit() methods on a PortalLookAndFeel object are called. See the PortalLookAndFeel class in Oracle Fusion Middleware Java API Reference for Oracle WebLogic Portal for more information about the reinit() methods. For instance, if you capture information about the Look & Feel, you need to know when the Look & Feel changes so that you can refresh it with the captured information. This event provides that notification.
onModeChange	Mode changes.
onStateChange	State changes.
onCustomEvent	Receives a custom event. Refer to Section 12.4.1, "Event Handlers."

12.5 Using the Portlet Event Handlers Wizard

The Portlet Event Handlers wizard included in Oracle Enterprise Pack for Eclipse allows you to configure several types of event handlers and actions. The following steps summarize the process of setting up an event handler using the wizard:

Select a type of event handler to create.
Determine the portlets to which that handler will listen.
Select an event for which the handler will listen.
Select and configure an action to fire when the event occurs.

The following sections describe the dialogs of the wizard and provide information about the information required in each field of the dialogs.

For a specific procedural example of how to use the event handler wizard, refer to Chapter 13, "Interportlet Communication Example With Event Handling."

12.5.1 Opening the Portlet Event Handlers Wizard

You can open the Portlet Event Handlers wizard in two ways:

The wizard opens when you open a portlet in Oracle Enterprise Pack for Eclipse and click the ellipsis button next to Event Handlers in the Properties view.
The wizard opens when you click the Event Handlers link in the portlet editor.

Note:
If no event handlers have been added, the Events field indicates that. If any event handlers have been added, the field indicates the number that currently exist.

The wizard appears, as shown in Figure 12-1.

Figure 12-1 Portlet Event Handlers Wizard

Description of "Figure 12-1 Portlet Event Handlers Wizard"

When you click Add Handler, the event handler drop-down menu allows you to select a handler; to add an action, click Add Action to open the event action drop-down menu.

Based on your selection, the dialog box expands, displaying additional fields that you can use to set up the handler or action. Figure 12-2 shows an example of the expanded dialog for adding an event handler. Note that the entry fields in the wizard are validated; the OK button is disabled until all errors are corrected for the currently displayed properties.

Figure 12-2 Expanded Event Handlers Dialog

Description of "Figure 12-2 Expanded Event Handlers Dialog "

12.5.2 Portlet Event Handlers Wizard - Add Handler Field Descriptions

Table 12-5 explains the fields in the Add Handler dialog and how your selections affect the behavior of the event.

Note:

WebLogic Portal attempts to validate the settings of the Handle Event part of the Portlet Event Handlers dialog. You will receive an error message if any problems are detected. For detailed information on the WebLogic Portal validation framework, see the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.

Table 12-5 Portlet Event Handlers Wizard - Add Handler

Field	Description
Event Label	Required. This identifier can be used by the `<filterEvent>` tag in the portal file to distinguish multiple event handlers in the same portlet.
Description	Optional.
Only If Displayed check box	Optional. Indicates that the portlet to receive the event must be on the current page and not minimized or maximized—the portlet's content must be currently in a rendered state. (Remember that the user must also be entitled to see the portlet.) The default is `true`. Note: If the event is <handlePortalEvent event="onMinimize" fromSelfInstanceOnly="true"> then it is logically impossible for this event to fire if onlyIfDisplayed="true".
From Self Instance Only checkbox	Optional. Defines whether the handler for a given portlet instance is invoked only when the source event originates from that instance. The default is `false`. If From Self instance Only is set to true, any Listen To values are ignored.
Listen To (wildcard)	Identifies the portlet(s) that this portlet can listen to. The values include: Any – Listens to events fired from any portlet in the portal. This – Listens to events fired from the currently selected portlet. Selected Portlets – (default) Listens to events fired from selected portlets only. Click the ... button in the Listen To (portlets) part of the dialog to select portlets. This and Selected Portlets – Listens to events fired from the currently selected portlet and portlets selected in the Listen To (portlets) part of the dialog.
Listen To (portlets)	Optional. Allows you to specify the portlets that this portlet can listen to. You can choose a `.portlet` file from the file system by clicking the ... button). When you select a `.portlet` file and click OK, the portlet is added to the Listen To list. This part of the dialog is only enabled if you chose either the Selected Portlets or This and Selected Portlets option in the Listen To (wildcard) menu. Caution: The values that you enter here are not validated. A typo in either an event name or a definition label can be very difficult to resolve later.
Portlet	You can type a portlet name in the field and click Add, or click the browse button to navigate to the portlet for which you want to listen.
Event or Action	Depending on the event handler you added, you will choose an event or an action for which the portlet will listen. For example, if you added the `HandlePortalEvent` handler, you can use the Event drop-down menu to select portal events, such as the `onRefresh` event. If you choose a handler that exposes actions, type the name of the action in the Action field. For example, if you chose `HandlePageFlowEvent`, you could type `submitReport`. The `submitReport` action of the page flow is now visible in the Action drop-down menu.

12.5.3 Portlet Event Handlers Wizard - Add Action Field Descriptions

The available fields for the action depend on the type of action that you select. Table 12-6 explains the possible fields in the expanded Portlet Event Handlers dialog and how your selections affect the behavior of the action.

Table 12-6 Portlet Event Handlers Wizard - Add Action

Field	Description
Change Window Mode	Enter the value of the new window mode.
Change Window State	Enter the value of the new window state; possible values are normal, minimized, maximized.
Activate Page	This action activates the page on which the portlet `<portlet_def_id>` currently resides. This action will fire only when triggered during the handlePostBack life cycle. Do not select the Activate Page action if the Only If Displayed check box is selected. Logically, if the portlet is responding to the event only if it is displayed, the page that it is on must be active anyway.
Invoke Struts Action	Use this selection to cause an Apache Struts action to be raised. The value must be an unqualified name of a Struts action defined in the embedded content. This action is only available on the menu for Struts portlets. Note: Apache Struts is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.
Fire Generic Event	Use this selection to cause a generic event to be raised. Enter the name of the generic event.
Fire Custom Event	Use this selection to cause a custom event to be raised. Enter the name of the custom event.
Invoke BackingFile Method	Use this selection to cause a backing file method to run. Enter the name of the method that you want to invoke. This action is only available on the menu if a backing file is configured for the portlet.
Invoke Page Flow Action	Use this selection to cause a page flow action to be raised. This action is only available on the menu for page flow portlets. Note: Page Flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.
Invoke Faces Action	Use this selection to cause a JSF action to be raised. This action is only available on the menu for JSF portlets.

12.5.4 Definition Labels and Interportlet Communication

IPC behavior is based on portlet definition labels; that is, all portlet instances of a given .portlet file respond to the same events. You can use the event handler options Only If Displayed and From Self Instance Only to discriminate among the instances of the same .portlet file. For a description of these options, refer to Section 12.5.2, "Portlet Event Handlers Wizard - Add Handler Field Descriptions."

12.6 Custom Event Handling

All WLP portlet types support custom event handling. A custom event is an event that you define, and can contain a developer-defined payload. A custom event handler is triggered when a custom event is received, and the handler can fire any pre-defined action, including calling a user-defined method in a backing file.

The Portlet Event Handlers dialog with the Handle Custom Event handler selected is shown in Figure 12-3. Note that the entry fields in the wizard are validated; the OK button is disabled until all errors are corrected for the currently displayed properties.

Figure 12-3 Custom Event Handler Dialog

Description of "Figure 12-3 Custom Event Handler Dialog"

Table 12-7 describes the fields and features of the Custom Event Handler form dialog shown in Figure 12-7.

Table 12-7 Custom Event Dialog Fields

Field	Description
Event Label	Required. This identifier can be used by the `<filterEvent>` tag in the portal file to distinguish multiple event handlers in the same portlet.
Description	Optional.
Only If Displayed checkbox	Optional. Indicates that the portlet to receive the event must be on the current page and not minimized or maximized—the portlet's content must be currently in a rendered state. (Remember that the user must also be entitled to see the portlet.) The default is `true`. Note: If the event is <handlePortalEvent event="onMinimize" fromSelfInstanceOnly="true"> then it is logically impossible for this event to fire if onlyIfDisplayed="true".
From Self Instance Only checkbox	Optional. Defines whether the handler for a given portlet instance is invoked only when the source event originates from that instance. The default is `false`. If From Self instance Only is set to true, any Listen To values are ignored.
Listen To (wildcard)	Identifies the portlet(s) that this portlet can listen to. The values include: Any – Listens to events fired from any portlet in the portal. This – Listens to events fired from the currently selected portlet. Selected Portlets – (default) Listens to events fired from selected portlets only. Click the ... button in the Listen To (portlets) part of the dialog to select portlets. This and Selected Portlets – Listens to events fired from the currently selected portlet and portlets selected in the Listen To (portlets) part of the dialog.
Listen To (portlets)	Optional. Allows you to specify the portlets that this portlet can listen to. You can choose a `.portlet` file from the file system by clicking the ... button). When you select a `.portlet` file and click OK, the portlet is added to the Listen To list. This part of the dialog is only enabled if you chose either the Selected Portlets or This and Selected Portlets option in the Listen To (wildcard) menu. Caution: The values that you enter here are not validated. A typo in either an event name or a definition label can be very difficult to resolve later.
Portlet	You can type a portlet name in the field and click Add, or click the browse button to navigate to the portlet for which you want to listen.
Event Namespace	Enter a QName or NCName to uniquely identify the event. For details, see Section 12.12, "About QNames and Aliases."
Event Name	Enter a name for the event. The custom event handler responds to this named event, which is typically fired programmatically from a JSP or Java class.
Aliases	(Optional) Enter an alias for the event. For details, see Section 12.12, "About QNames and Aliases."

For information on the Add Action button selections, see Section 12.4.2, "Event Actions." Note that the Fire Custom Event action requires an Event Namespace, as shown in Figure 12-4. The Namespace must be a qualified QName namespace. For information on namespaces, see Section 12.12, "About QNames and Aliases."

Figure 12-4 Fire Custom Event Dialog

Description of "Figure 12-4 Fire Custom Event Dialog"

12.7 Events in Java Portlets

The JSR 286 specification adds support for events to Java portlets. WLP has previously supported events for all portlet types, including JSR 168 portlets, but in a manner slightly different from the JSR 286 specification. While the methods for handling events described in Section 12.4, "Portlet Event Handling" will continue to work for JSR 286 portlets, it is recommended that you use the JSR-286-standard event handling for Java portlets. This will maximize portability of these portlets to other Portal containers.

This section explains how to add events to Java portlets in a JSR-286-compliant way.

12.7.1 Overview

In JSR 286, portlets can declare events that they are interested in receiving, called processing events, and events that they are expected to fire, called publishing events. Only events declared as processing events will be delivered to the portlet, but the portlet is allowed to fire events it does not declare as publishing events. The list of declared published events is used exclusively at development time to give an indication to developers of what types of events a portlet may fire; it is not used at portlet runtime.

The Portlet Event Handlers dialog box for Java portlet types allows you to declare non-JSR-286-compliant event handling in the WLP-Handled Events tab, and to declare JSR-286-compliant events in the Java Portlet Events tab.

WLP-handled events are placed in the .portlet file for the portlet and are handled by the WLP framework. These events are not portable to other JSR 286 portlet containers, and therefore are not the recommended technique for handling events for Java portlets. Oracle recommends that you use Java portlet events instead.

Because Java portlet events comply to the JSR 286 standard, they are portable to other JSR 286 portlet containers. In the Java Portlet Events tab, the dialog handles the job of updating the portlet.xml file with the correct elements and attributes. Java portlets receive and can send events from the portlet's Java code. Note that a single portlet can both send and receive events.

Refer to the Java Portlet Specification Version 2 for more information on Java portlet event handling.

12.7.2 Adding a Processing Event

By declaring a processing event, you are declaring an event that the portlet can receive. Java portlets only receive events that are declared as processing events.

To add a processing event to a Java portlet:

Open the Portlet Event Handlers dialog. You can open the dialog by clicking the Event Handlers button in the Properties view or by clicking the Event Handlers link in the portlet editor. Note that the entry fields in the dialog are validated; the OK button is disabled until all errors are corrected for the currently displayed properties.
In the Portlet Event Handlers dialog, select the Java Portlet Events tab.
Select Processing from the Event Type menu, as shown in Figure 12-5.

Figure 12-5 Selecting a Processing Event Type

Description of "Figure 12-5 Selecting a Processing Event Type"
Click Add Processing Event. The Define or Choose a Portlet Event Definition dialog opens, as shown in Figure 12-6.

Figure 12-6 Define or Choose a Portlet Event Definition Dialog

Description of "Figure 12-6 Define or Choose a Portlet Event Definition Dialog"
To create a new event, select Define a new portlet event definition, and fill out the form.

Optionally, you can choose to select an existing event definition. To do this, select the radio button and pick an event from the drop down menu. This menu is only populated if one or more events were previously defined by other portlets in the same portlet application (portlet.xml).
(Optional) Specify an alias name. For information on aliases, see Section 12.12, "About QNames and Aliases."

To add an alias, click Edit and in the next dialog, click New. The Provide QName Components dialog appears (see Figure 12-7). Enter an optional Namespace URI and a Local Part for the QName and click OK. The alias definition appears in the Provide List of QName Alias(es) dialog (Figure 12-8). You can add as many event aliases to the event declaration as you like.

Figure 12-7 Provide QName Components Dialog

Description of "Figure 12-7 Provide QName Components Dialog"

Figure 12-8 Provide List of QName Alias(es) Dialog
(Optional) Enter a data type in the Value Type field. The Value Type specifies the Java object type of the event payload. If unspecified, all data types are accepted. If you specify a type, the Java portlet container will enforce the type of the event's payload: incoming events with payloads not matching this type will not be delivered to the portlet, and if the portlet fires an event with a payload type not matching the declared type, an IllegalArgumentException will be thrown. Per the JSR 286 specification, any types declared here must have a valid JAXB binding; most Java object types representing primitives have such bindings, as does java.lang.String.
Click OK to create the event. The new event appears in the Event Type list in the Portlet Event Handlers dialog box.
Click OK in the Portlet Event Handlers dialog when you are finished entering processing events. Note that the event definition is not saved in the portlet.xml file until you save the .portlet file.

12.7.3 Adding a Publishing Event

By declaring a publishing event, you are giving a hint as to the types of events the portlet can send. There is no enforcement of this as a restriction at runtime.

To add a publishing event to a Java portlet:

Open the Portlet Event Handlers dialog. You can open the dialog by clicking the Event Handlers button in the Properties view or by clicking the Event Handlers link in the portlet editor. Note that the entry fields in the dialog are validated; the OK button is disabled until all errors are corrected for the currently displayed properties.
In the Portlet Event Handlers dialog, select the Java Portlet Events tab.
Select Publishing from the Event Type menu, as shown in Figure 12-9.

Figure 12-9 Selecting a Publishing Event Type

Description of "Figure 12-9 Selecting a Publishing Event Type"
Click Add Publishing Event. The Define or Choose a Portlet Event Definition dialog opens, as shown in Figure 12-10.

Figure 12-10 Define or Choose a Portlet Event Definition Dialog

Description of "Figure 12-10 Define or Choose a Portlet Event Definition Dialog"
To create a new event, select Define a new portlet event definition, and fill out the form. For the QName or NCName, you can edit the defaults by clicking the Edit button. This name is a unique name to identify the event. For more information, see Section 12.12, "About QNames and Aliases."

Optionally, you can choose to select an existing event definition. To do this, select the radio button and pick an event from the drop down menu. This menu is only populated if one or more events were previously defined.
(Optional) For details on the Aliases section, see Section 12.12, "About QNames and Aliases." You can enter more than one alias.
(Optional) Enter a data type in the Value Type field. The Value Type specifies the Java object type of the event payload. If unspecified, all data types are accepted. If you specify a type, the Java portlet container will enforce the type of the event's payload: incoming events with payloads not matching this type will not be delivered to the portlet, and if the portlet fires an event with a payload type not matching the declared type, an IllegalArgumentException will be thrown. Per the JSR 286 specification, any types declared here must have a valid JAXB binding; most Java object types representing primitives have such bindings, as does java.lang.String.
Click OK to create the event. The new event appears in the Event Type list in the Portlet Event Handlers dialog box.
Click OK in the Portlet Event Handlers dialog when you are finished entering publishing events. Note that the event definition is not saved in the portlet.xml file until you save the .portlet file.

12.7.4 Modifying a Java Portlet Event

This section explains how to modify Publishing and Processing Java portlet events.

Open the Portlet Event Handlers dialog. You can open the dialog by clicking the Event Handlers button in the Properties view or by clicking the Event Handlers link in the portlet editor.
In the Portlet Event Handlers dialog, select the Java Portlet Events tab.

Use the Event Type drop-down menu to select either a Publishing or Processing. Publishing events are sent by the portlet and Processing events are received by the portlet.

Edit the selected event in the Java Portlet Event section on right side of the dialog box, as shown in Figure 12-11. After making changes to the editable fields, click OK. For more information on the editable fields, see Section 12.7.2, "Adding a Processing Event."

Note:
All entry fields in the Portlet Event Handlers dialog are validated. An error dialog appears when the validation fails. You cannot click OK or switch events, tabs, or event types until the errors are corrected for the currently displayed event properties.

Figure 12-11 Editing a Java Portlet Event Definition

Description of "Figure 12-11 Editing a Java Portlet Event Definition"

12.7.5 Deleting a Java Portlet Event

If you are deleting a Java portlet event, a dialog appears, and you must choose one of the following options:

Remove (disassociate) the Java portlet event from this portlet only.

In this case, the event definition remains in the portlet.xml file. Only the mapping to the current portlet is removed. Choose this case if other portlets reference the event. For example, if multiple portlets reference the same event, you would want to leave the event definition in the portlet.xml file.
Delete the Java portlet event from the portlet.xml.

In this case, the entire event and all mappings to the event are removed from the portlet.xml file. Only pick this option if you know that no other portlets require the event definition.

For example, Example 12-1 shows an excerpt from a portlet.xml file where three events are defined in the <event-definition> elements: eventDef_1, eventDef_2, and eventDef_3. The definition for the portlet called myJsf has all three events added to it, in the <supported-processing-event> elements.

If you remove eventDef_1 from the portlet named myJsf using the first option (disassociate), the <supported-processing-event> element named eventDef_1 will be removed from the portlet definition, as shown in Example 12-2. Note that any other portlets will continue to reference the event. If you select the second delete option, the entire <event-definition> element and the <supported-processing-event> element(s) will be removed. In this case, no portlets will reference the event.

Example 12-1 Event Definitions and Mapping Elements Before a Disassociate Operation

<portlet-app ...>
    <portlet>
        <portlet-name>myJsf</portlet-name>
        <portlet-class>JsfPortlet</portlet-class>
        <supports>
            <mime-type>text/html</mime-type>
            <portlet-mode>view</portlet-mode>
        </supports>
        <portlet-info>
           <title>JSF Portlet</title>
        </portlet-info>
        <supported-processing-event><name>eventDef_1</name>
        </supported-processing-event>
        <supported-processing-event><name>eventDef_2</name>
        </supported-processing-event>
        <supported-processing-event><name>eventDef_3</name>
        </supported-processing-event>
    </portlet>
    ...
    <event-definition>
    <name>eventDef_1</name></event-definition>
    <event-definition>
    <name>eventDef_2</name></event-definition>
    <event-definition>
    <name>eventDef_3</name></event-definition>
    ....
</portlet-app>

Example 12-2 Event Definitions and Mapping Elements After Disassociate Operation

<portlet-app ...>
    <portlet>        <portlet-name>myJsf</portlet-name>        <portlet-class>JsfPortlet</portlet-class>        <supports>            <mime-type>text/html</mime-type>            <portlet-mode>view</portlet-mode>        </supports>        <portlet-info>           <title>JSF Portlet</title>        </portlet-info>        <supported-processing-event><name>eventDef_2</name>
        </supported-processing-event>
        <supported-processing-event><name>eventDef_3</name>
        </supported-processing-event>
    </portlet>
    ...
    <event-definition>    <name>eventDef_1</name></event-definition>    <event-definition>    <name>eventDef_2</name></event-definition>    <event-definition>    <name>eventDef_3</name></event-definition>
    ....
</portlet-app>

12.8 Subscribing Java Portlets to Portal Framework Events

Java portlets can receive events generated by the portal framework (as opposed to events fired by other portlets) by simply subscribing to the appropriate event name. The table below gives the namespace and local name for the event QName for Java portlets to subscribe to for portal-generated events.

The column From Self Instance Only indicates whether the portlet will only receive the event if the event was fired for the particular portlet instance.

When the local name in the table below is in italics, it indicates that the event's local name should be the name of the specific action or event name the portlet wishes to receive an event about. For example, if the Java portlet wanted to receive an event whenever a JSF portlet triggered a JSF action named reset, the Java portlet would subscribe to an event with a QName consisting of the namespace urn:com:oracle:wlp:netuix:event:faces and local name reset.

Table 12-8 Namespaces and Local Names Portal Framework Events

Event Type	Sent	Namespace	Local Name	From Self Instance Only
Faces	When a JSF action occurs on a JSF portlet.	urn:com:oracle:wlp:netuix:event:faces	actionName	No
Generic	When another portlet sends a Generic event.	urn:com:oracle:wlp:netuix:event:generic	eventName	No
Custom	When any portlet sends a custom event.	See Section 12.8.1, "Custom Event Namespaces."	eventName	No
Struts	When a Struts action occurs on a Struts portlet.	urn:com:oracle:wlp:netuix:event:struts	actionName	No
PageFlow	When a page flow action occurs in a JPF portlet.	urn:com:oracle:wlp:netuix:event:pageflow	actionName	No
Init	Every time a portal page is rendered.	urn:com:oracle:wlp:netuix:event:init	init	No
LookAndFeelReinit	When a Look and Feel is dynamically changed.	urn:com:oracle:wlp:netuix:event:laf-reinit	reinit	No
Notification	When the user has a notification.	urn:com:oracle:wlp:netuix:event:notification	See Section 12.8.2, "Local Name for Notification Events."	No
Refresh	Whenever the portlet is refreshed.	urn:com:oracle:wlp:netuix:event:refresh	refresh	No
Activation	When a portlet first becomes visible.	urn:com:oracle:wlp:netuix:event:window	activate	Yes
Deactivation	When a portlet ceases to be visible.	urn:com:oracle:wlp:netuix:event:window	deactivate	Yes
Mode Change	When the portlet's mode changes.	urn:oasis:names:tc:wsrp:v2:types	newMode	Yes
State Change	When the portlet's state changes.	urn:oasis:names:tc:wsrp:v2:types	newWindowState	Yes

12.8.1 Custom Event Namespaces

For custom events, the namespace of the event is the namespace the event was sent with. For non-Java portlets, if no namespace was specified for the custom event when it was sent, the default custom event namespace of urn:com:oracle:wlp:netuix:event:custom is applied. For example, if in the .portlet file for a non-Java portlet there is an event handler with an action of:

<netuix:fireCustomEvent event="myCustomEvent"/>

A Java portlet could receive this event by subscribing to an event with a QName consisting of the namespace urn:com:oracle:wlp:netuix:event:custom and local name myCustomEvent.

If an empty namespace is explicitly declared for a custom event, the event will not receive the default custom event namespace. For example, if in the .portlet file for a non-Java portlet there is an event handler with an action of:

<netuix:fireCustomEvent qname="{}myCustomEvent"/>

A Java portlet could receive this event by subscribing to an event with a QName consisting of the namespace "" (the empty string) and local name myCustomEvent.

12.8.2 Local Name for Notification Events

For notification events, the local name for the event to subscribe to is generated by appending the namespace of the notification payload, the string "_._", and the notification's payload name. In this way, Java portlets can subscribe to receive events only for the particular notification(s) they wish.

12.9 Public Render Parameters

Public render parameters are a JSR 286 feature that allows portlets to share simple String values with other portlets during all phases of the portlet lifecycle. For more information, see Section 6.8, "Public Render Parameters."

12.10 Shared Parameters

Shared parameters are the same as JSR 286 portlet public render parameters, but for non-Java portlet types. For details, see Section 9.3, "Using Shared Parameters."

12.11 IPC Special Considerations and Limitations

The following sections describe special considerations that you should keep in mind as you implement interportlet communications.

This section contains the following topics:

Section 12.11.1, "Using Asynchronous Portlet Rendering with IPC"
Section 12.11.2, "Consistency of the Listen To Field"

12.11.1 Using Asynchronous Portlet Rendering with IPC

Although IPC is not supported when asynchronous content rendering for specific portlets is enabled, WebLogic Portal provides some features that allow these two mechanisms to coexist in your portal environment. In addition, you can disable asynchronous rendering for single requests using the mechanisms described in Section 10.5.8, "Asynchronous Content Rendering and IPC."

Tip:

If you enable asynchronous rendering at the portal/desktop level, you can use IPC without restrictions. For more information on asynchronous portal/desktop rendering, see the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.

12.11.2 Consistency of the Listen To Field

Pay attention to the Listen To field when you set up the listener portlet. The portlet definition you use on the consumer must match the WSRP portlet's portlet definition. For example, if you have "portlet_2" listening to "portlet_1", the WSRP portlet corresponding to "portlet_1"—the proxy on the consumer—must also have its portlet definition label set to "portlet_1". For more information on using IPC with WSRP, refer to the Oracle Fusion Middleware Federated Portals Guide for Oracle WebLogic Portal.

12.12 About QNames and Aliases

Portlet events and shared parameters (called public render parameters for Java portlets) both make use of QNames and optional aliases to allow interportlet communication. The QName provides a unique identifier for an event or shared parameter that is used internally by the portal framework when distributing events and shared parameter values. QNames allow a degree of isolation for portlets, to ensure that they do not interfere with other portlets' operations. Aliases provide a mechanism for renaming events or shared parameters as they are delivered to individual portlets, allowing communication between portlets that may not have been designed to communicate with each other.

A QName is a qualified name consisting of a Namespace URI and a Local Part, as defined by the Namespaces in XML standard from the W3C. This standard defines exactly what the namespace URI and Local Part can consist of, but to simplify, the namespace is any URI and the local part is an NCName – a string beginning with a letter or underscore followed by any letters, numbers, dashes ('-'), underscores ('_') or periods ('.'). In Java, the string representation of a QName object is {namespace}localName, with the namespace inside of braces to distinguish it from the local name. For convenience in the rest of this section, this nomenclature will be used.

Tip:

The Provide QName Components dialog automatically forms the namespace/local part identifier in the standard syntax, for example: {http://oracle.com/myevents}testevent. If you enter the QName directly in the Define or Choose a Portlet Public Render Param dialog, you must use this syntax.

12.12.1 QNames and Aliases in Events

QNames are used as the unique identifying name for events. Having both a namespace and local name for the event allows portlet developers to develop a suite of portlets which communicate with each other, while minimizing the chances of name collisions with other portlets. For example, a set of travel portlets from company XYZ may communicate using an event named {urn:com:xyz:travel}location.change. If a set of map portlets from company ABC also makes use of an event with a local name of location.change, they can ensure that the event won't cause confusion for the portlets from XYZ by using a unique namespace, for example {urn:com:abc:map}location.change.

Aliases make it possible for a single event handler to accept events with multiple different QNames. Aliases let you declare that an event with a particular QName is functionally equivalent to an event with another QName. Aliases are simply a list of QNames. When the portal framework is distributing an event to portlets, if the event's QName matches a declared alias for another event definition, the event will be renamed to match the portlet's expected event QName before it is delivered.

For example, if portlet X has declared an event it wishes to receive with a QName of {urn:com:xyz:travel}location.change, with an alias to {urn:com:abc:map}countrySelected, when an event with a QName of {urn:com:abc:map}countrySelected is fired by any portlet, the event payload will remain the same but the event will be delivered to portlet X using the QName {urn:com:xyz:travel}location.change. In this way, portlet X can have a single event-handler which accepts only a single event name, but other events can be declaratively sent to this event handler using aliases.Aliases apply only to the portlets that explicitly declare them. For example, given the following setup:

Portlet A:

Handles Event: {abc}zipCode

Portlet B:

Handles Event: {def}zip
- Alias: {abc}zipCode
Handles Event: {xyz}postalCode

Portlet C:

Handles Event: {xyz}postalCode
- Alias: {abc}zipCode
- Alias: {def}zip

If an event is sent (by any portlet) with a QName of {abc}zipCode, Portlet A will receive the event with a QName of {abc}zipCode, portlet B will receive the event with a QName o {def}zip, and portlet C will receive the event with a QName of {xyz}postalCode.

If an event is sent (by any portlet) with a QName of {def}zip, Portlet A will not receive the event, Portlet B will receive the event with a QName of {def}zip, and Portlet C will receive the event with a QName of {xyz}postalCode.

12.12.2 QNames and Aliases in Shared Parameters / Public Render Parameters

Shared parameters (called public render parameters in JSR 286 portlets) are accessed by portlets using a simple String name, called the identifier. When a portlet wants to read or set the value of a shared parameter in its code, it does so using this identifier. Since the identifier is used as a parameter name, there is a high probability it could conflict with another parameter of the same name being used by a different portlet.

Note:

For detailed information on Shared Parameters, see Section 9.3, "Using Shared Parameters." For detailed information on Public Render Parameters, see Section 12.9, "Public Render Parameters."

For example, a map portlet may use a parameter called location to store latitude and longitude coordinates, while a wiki portlet in the same portal may use a parameter called location to keep information on what content is currently being displayed. To avoid these name collisions with shared parameters, each shared parameter is declared with both an identifier (the name used by the portlet to access the parameter), and a QName (the unique name used by the portal framework to distribute the value to other portlets).

For example, if there are three portlets on a page:

Portlet A:

Shared Parameter Identifier: location
Shared Parameter QName: {urn:abc}map.location

Portlet B:

Shared Parameter Identifier: location
Shared Parameter QName: {urn:xyz}wiki.page.name

Portlet C:

Shared Parameter Identifier: coordinates
Shared Parameter QName: {urn:abc}map.location

In this scenario, Portlets A and C share the parameter with QName {urn:abc}map.location. Portlet A accesses it using the parameter name location, while portlet C accesses it using the parameter name coordinates. When Portlet B sets a parameter named location, even though it has the same identifier as the shared parameter from Portlet A, Portlet A would not see the new value because the QNames are different.

Aliases are used for shared parameters to give an alternate QName for a shared parameter, as a means of "inheriting" the value of other shared parameters. In most cases this is simple and straightforward, but because of how shared parameter values are distributed, this can have some side-effects that are not immediately obvious. For example, given the following setup:

Portlet A:

Shared Parameter Identifier: firstName
Shared Parameter QName: {urn:abc}customer.name.first
- Alias: {urn:xyz}customerFirstName

Portlet B:

Shared Parameter Identifier: first
Shared Parameter QName: {urn:xyz}customerFirstName

Portlet C:

Shared Parameter Identifier: name
Shared Parameter QName: {urn:qrs}customer.name
- Alias: {urn:abc}customer.name.first

In this scenario, if portlet B sets the value of its shared parameter first to Alice, the portal framework will distribute the shared parameter value using the QName {urn:xyz}customerFirstName. Because portlet A has aliased its shared parameter to that QName, portlet A will then see a value of Alice for its parameter named firstName. Portlet C will not see a new value for its shared parameter name.Continuing this scenario, if portlet A sets its parameter firstName to Bob, portlet C will then see the value of its parameter named name as Bob. Portlet B's value of parameter first remains Alice, as it was not aliased to portlet A's shared parameter.Furthermore, if portlet C then sets its parameter name to Carl, there are no aliases for portlet C's shared parameter QName in any of the other shared parameter declarations, so portlet A's parameter firstName will have a value of Bob, portlet B's parameter first will have a value of Alice, and portlet C's parameter name will have a value of Carl.To avoid this conditional distribution of shared parameter values, you can set up reciprocal aliases. For example:

Portlet A:

Shared Parameter Identifier: firstName
Shared Parameter QName: {urn:abc}customer.name.first
- Alias: {urn:xyz}customerFirstName
- Alias: {urn:qrs}customer.name

Portlet B:

Shared Parameter Identifier: first
Shared Parameter QName: {urn:xyz}customerFirstName
- Alias: {urn:abc}customer.name.first
- Alias: {urn:qrs}customer.name

Portlet C:

Shared Parameter Identifier: name
Shared Parameter QName: {urn:qrs}customer.name
- Alias: {urn:abc}customer.name.first
- Alias: {urn:xyz}customerFirstName

Because each shared parameter declaration in this setup has aliases to the other two, setting a shared parameter value in any of the portlets will cause all of the portlets to receive the same value.