WSRP2.0 defines a mechanism by which a consumer can co-ordinate events across the portlets it consumes from different producers. Consumers may implement mechanisms through which portlets, and any other view components the consumer aggregates, react in a coordinated manner. Event distribution is one such mechanism which enables event-driven consumer applications.
This document describes the event use cases with reference to WSRP 2.0 specification.
Event Distribution
Event distribution mechanism provides for portlets generating and consuming events that carry both semantic meaning, through their name and data in their payload. In addition, consumers can also generate events for distribution to portlets. All events are distributed by the consumer such that any current portlet state which is stored at the consumer can be supplied along with the event to the portlet. This also allows the consumer to apply whatever policies it chooses to control the event distribution.
WSRP 2.0 defines a mechanism by which the consumer can selectively distribute events, including ones it generates itself, among the portlets. For these reasons, there is a "three-step" capability built into the protocol. This is an extension of the WSRP v1 two-step protocol as the additional step, event distribution, is entirely optional. This enables consumers to provide coordinated cross-portlet response to the end-user's interaction while providing the equivalent user experience as WSRP v1 for those consumers not supporting event distribution.
Use Cases
Use Case 1: Event distribution between a local portlet and a remote portlet
Scenario
Consumer consumes 2 portlets.
1.LocalPortlet is a local portlet
2.Consumer consumes RemotePortlet2? from Producer2
3.LocalPortlet throws an event
Event Distribution
When LocalPortlet? throws an event, consumer receives this event and distributes the event to RemotePortlet2?. This scenario demonstrates consumer coordinated events mechanism, where a consumer propagates a local event to a remote producer.
Note:
Same scenario can be extended to demonstrate event propagation between a local portlet and multiple remote portlets.
Use Case 2: Event distribution between two remote portlets
Scenario
Consumer consumes two remote portlets from different producers.
1.Consumer consumes RemotePortlet1? from Producer1
2.Consumer consumes RemotePortlet2? from Producer2
3.RemotePortlet1 throws an event
Event Distribution
When RemotePortlet1? throws an event, consumer receives this event and distributes the event to RemotePortlet2?. This scenario demonstrates consumer coordinated events mechanism, where a consumer propagates events across different producers.
Use Case 3: Event distribution between two remote portlets and event response returns failure code
Scenario
Consumer consumes two remote portlets from different producers.
1.Consumer consumes RemotePortlet1? from Producer1
2.Consumer consumes RemotePortlet2? from Producer2
3.RemotePortlet1 throws an event
Event Distribution
When RemotePortlet1? throws an event, consumer receives this event and distributes the event to RemotePortlet2?. If the handleEventResponse returns a failed event, consumer must not retry to distribute failed event, as producer/portlet is capable of appropriate retries for processing any event.
Use Case 4: Event distribution between two remote portlets and event times out
Scenario
Consumer consumes two remote portlets from different producers.
1.Consumer consumes RemotePortlet1? from Producer1
2.Consumer consumes RemotePortlet2? from Producer2
3.RemotePortlet1 throws an event
Event Distribution
When RemotePortlet1? throws an event, consumer receives this event and distributes the event to RemotePortlet2?. No response comes from Producer2 and event times out.
In this case, WSRP implementation can throw a time out error. Its up to consumer to decide whether to retry the event or continue with subsequent request, based on the policies set.
Use Case 5: Cyclic events across two remote portlets
Scenario
Consumer consumes two remote portlets from different producers.
1.Consumer consumes RemotePortlet1? from Producer1
2.Consumer consumes RemotePortlet2? from Producer2
3.RemotePortlet1 throws an event, which is distributed to RemotePortlet2?
4.RemotePortlet2 throws an event, which is distributed to RemotePortlet1?
5.Steps 3 and 4 continue indefinetely
Event Distribution
When RemotePortlet1? throws an event, consumer receives this event and distributes the event to RemotePortlet2?. RemotePortlet2? now throws an event and it is distributed to remote portlet1. This cycle of continues.
To avoid recursion of events, consumer can come up with a policy to determine cyclic events and stop propagating events after few cycles, say 3 or 5.
Use Case 6: System generated event
Scenario
Consumer consumes two remote portlets from different producers.
1.Consumer consumes RemotePortlet1? from Producer1
2.Consumer consumes RemotePortlet2? from Producer2
3.Consumer receives a system generated event
Event Distribution
If consumer receives a system generated event, it can handle the events based on policies set. Default policy could be to propagate the system generated event to all portlets consumed by the consumer.
In this case, consumer distributes the event to RemotePortlet1? and RemotePortlet2?
Use Case 7: Handling event wild cards
Scenario
1.Consumer consumes three remote portlets from three different producers.
2.Consumer consumes RemotePortlet1? from Producer1, RemotePortlet2? from Producer2 and RemotePortlet3? from Producer3.
3.RemotePortlet1 is interested in any event related to member details (member.*)
4.RemotePortlet2 is interested in event related to member address zipcode (member.address.zipChanged)
5.RemotePortlet3 is interested in any event related to member address (member.address.*)
6.Consumer receives an event member.address.CityChanged
Event Distribution
Consumer can set policies on event distribution to portlets, based on events consumed and published by portlets. In this case, member details event is a super set of member address event and member address zip code event.
Consumer can set following policy to propagate member events
1.Events starting with event name member.* will be propagated to RemoteProducer1?
2.Events starting with event name member.address.* will be propagated to RemoteProducer1? and RemoteProducer3?
3.Event with event name member.address.zipChanged will be propagated to RemoteProducer1?, RemoteProducer2? and RemoteProducer3?
Following sequence diagram shows how consumer handles member.address.cityChanged event.
Note: Portlet developers are encouraged to organize their event's local names in a hierarchical manner and MUST use the '.' character to delimit levels within the hierarchy.
Use Case 8: Event wiring across portlets
Scenario
Consumer consumes two remote portlets from different producers.
1.Consumer consumes RemotePortlet1? from Producer1
2.RemotePortlet1 publishes/consumes event zipcode
3.Consumer consumes RemotePortlet2? from Producer2
4.RemotePortlet2 publishes/consumes event postcode
5.RemotePortlet1 throws zipcode event
Event Distribution
Consumer can enforce policies on how to handle events and wire related events. In this case, consumer discovers that RemotePortlet1? is interested in zipcode event and RemotePortlet2? is interested in postcode event. Since zipcode to postcode refer to same data, consumer maps zipcode to postcode. Such mappings are referred to as wiring of events.
Consumer receives zipcode event from RemotePortlet1? and distributes the event to RemotePortlet2?
Note:
Note: