1.1.1 handleEvents() Operation

A useful way of describing the distinction between an interaction and an event is that an interaction is an encodable event (i.e. can be referenced by presentation markup) with an opaque payload which the Consumer will always attempt to deliver to the portlet that generated the markup. This difference results in the need for a different signature that the Consumer uses to distribute events to a Portlet; namely:

HandleEventResponse = handleEvents(RegistrationContext,

PortletContext, RuntimeContext,

UserContext, MarkupParams,

EventParams, Event[]);

Faults: AccessDenied, InconsistentParameters, InvalidRegistration,

ModifyRegistrationRequired, InvalidUserCategory,

InvalidHandle, InvalidCookie, InvalidSession,

MissingParameters, OperationFailed,

PortletStateChangeRequired, UnsupportedMode,

UnsupportedWindowState, UnsupportedLocale, UnsupportedMimeType

These events provide a means by which a Portlet can become informed about changes in the environment where the Consumer is incorporating the Portlet’s markup. These notifications could have originated from another Portlet or directly from the Consumer. It is the Consumer which determines which events to distribute to which Portlets, usually based on the needs of the environment (e.g. the portal application) and the metadata concerning the events Portlets can generate and/or consume. As event distribution is Consumer managed, Portlets should neither assume nor require a particular manner of event distribution in order to function properly.

1.1.1.1 Event handling

In order for the inherent overhead of remote invocations to not degrade End-User performance to unacceptable levels, WSRP collapses invocations that are equivalent outside of the event being processed into a single invocation that deals with an array of events.

Since the order of events might be important to the Consumer, the Producer/Portlet MUST process the supplied events and return any generated events in a sequenced array manner (first generated event to process or first event generated appears first in the array, etc). While there are valid reasons why a Consumer might order the supplied events on criteria other than the order in which the Consumer received them, Consumers are encouraged to only do such a reordering when needed by application logic.

While the Consumer MAY invoke handleEvent() multiple times for any one portlet while preparing to gather markup, it MUST NOT invoke handleEvent() an additional time while the portlet is already processing an event for the same End-User.

1.2 Defined Events

This specification defines the following events in the interest of promoting interoperability on a set of commonly encountered scenarios. All of these are defined within the WSRP types namespace (i.e. urn:oasis:names:tc:wsrp:v2:types)

1.2.1 onLoad

This event is to be delivered only on the first use of the portlet for a particular End-User’s set of interactions with the Consumer. It is to be delivered as the first invocation of the Portlet and carries no event payload. In the case of a Portlet where the initiating interaction would have been performBlockingInteraction, this results in two passes through the three-step nature of the protocol with the getMarkup step of the first pass being optimized away much as it would have been if markup had been fetched from a cache.

1.2.2 eventHandlingFailed

This event signals that the Consumer detected errors while distributing events. As a simple notification, this event carries no predefined payload, but does use an open content definition.

1.2.3 eventProcessingFailed

This event signals to the Consumer that the Portlet failed to process an event. The payload of this event contains the event where the processing failed.

Note: Subbu has proposed the equivalent of this event as a separate field in handleEventResponse. One advantage of Subbu’s proposal is that by keeping failures in a separate field, those Consumer which will ignore or specially process failures do not have to separate them from the normal flow. The downside is that it considers failure notifications to be different than any other type of notification.