Namespace: portlet

Portlet Specification 2.0 (JSR 286) provided Ajax support for portlets by adding a resource URL, resource request, and serveResource() method to allow portlet JavaScript code to retrieve data directly from the portlet. Portlet Specification 3.0 (JSR 362) expands on that by providing capability allowing a portlet to change its state through JavaScript functions.

Portlet Specification 3.0 introduces a JavaScript component called the Portlet Hub that manages the state of all portlets on a portal page.

Some terminology:

Portlet Hub

JavaScript component that manages the state of all portlets on a portal page. It is considered to be part of the portal implementation. This document describes its JavaScript interfaces and behavior.

Portlet JavaScript code can use the Portlet Hub programming interface to modify its state by setting private and public render parameters to submit forms while remaining in the Ajax application paradigm.

Many portlets can be present on the page and the portlets are in general independent of one another and they are not aware of the state of other portlets, so they are unable to generate URLs properly representing the complete page state. The Portlet Hub provides methods that allow portlets to obtain URLs representing the current portal page state.

The programming interface and behavior of this component is standardized by JSR 362.

Portlet Client

JavaScript code written by the portlet developer that uses the portlet hub to manage its state and to obtain URLs for retrieving data.

Changing the render state

The portlet client can use portlet hub functions to initiate state changes.

The portlet client can set public and private render parameters as well as the portlet mode and window state.

In addition, the portlet client can submit a portlet action request that uses HTTP POST semantics. The portal will execute the portlet Action Phase and Event Phase processing on the server and return the updated page state to the portlet hub.

After the requested state change has been performed, the portlet hub will usually provide each affected portlet client with its updated state information.

However, regardless of whether the state change was initiated by setting parameters or through a portlet action, the portal may respond by completely refreshing the page. The portal may do so in order to support portlets that are affected by the state change but do not participate in the portlet client-side support, or for implementation-specific reasons.

If the portal responds to a state change request by refreshing the page, the portlets will not be updated with new page state information before the page refresh is carried out.

Receiving render state Updates

When a state change occurs that affects a portlet, the portlet hub informs the affected portlet client of its new state through use of a callback function. The change causing the update does not necessarily need to be initiated by the portlet client itself.

For example, when portlet A changes a public render parameter used by portlet B, the portlet hub will inform both the portlet A and the portlet B clients of that change.

Portlet Client Events

Portlet client events consist of an event type and an event payload. Both are defined by by the portlet clients themselves.

Portlet client events have no connection to the server-side portlet event mechanism.

The portlet hub provides utility functions that enable the portlet client to dispatch and listen for portlet client events.

Error Handling

When the portlet hub can recognize an error during function execution, the error will be reported to the portlet client through an exception.

However, some methods initiate work that is performed asynchronously. Errors that occur during asynchronous processing will be reported to the portelt client through the onError callback function.

Important Considerations

The portlet hub calls the portlet client callback functions in several situations as described above. When the portlet hub calls the portlet client, the portlet client may navigate to a different page or may initiate another change to the render state that could potentially cause a page refresh.

Due to this behavior, the delivery of neither render state updates nor portlet client events can be guaranteed.

The portlet hub provides for orderly state transitions by allowing only a single blocking operation (action, setRenderState, startPartialAction) to be active at any one time.

The state transition is considered to be active from the initial portlet client call to one of the blocking operations until the portlet hub has performed the requested state change and has informed all of the affected portlet clients by firing the corresponding onStateChange events.

This has the following implications:

1. It is not possible to initiate a sequence of blocking operations.

   For example, once a portlet client calls the {@link setRenderState} method, it cannot call any additional blocking method until after its onStateChange listener function has been called.

2. It is not possible to initiate a blocking operation during execution of the onStateChange listener function, since execution of that function belongs to the preceding state change operation.