Package org.jini.rio.event

Provides classes and interfaces which enable support for distributed events.

See:
Description

Interface Summary

EventConsumer	The EventConsumer defines the semantics for a client to register and receive remote event notifications
EventProducer	The EventProducer defines the support for an event consumer to register for events a service produces
RemoteServiceEventListener	The RemoteServiceListener interface is used to specify support for clients that wish to participate in notification of distribted events.

Class Summary

BasicEventConsumer	The BasicEventConsumer is a helper class that manages the discovery of EventProducer instances that provide support for user defined events.
DispatchEventHandler	The DispatchEventHandler provides an implementation of an EventHandler which supports the notification of events to all registered event listeners with a valid lease.
DynamicEventConsumer	A DynamicEventConsumer extends BasicEventConsumer and provides the capability to discover when EventProducer instances join and leave the network
EventDescriptor	The EventDescriptor describes an event that an EventProducer will advertise as part of it's attribute set in a Jini Lookup Service.
EventHandler	The EventHandler is an abstract class which handles the basic event plumbing.
EventHandler.EventRegistrationResource	Container class for event registration objects which are created and behave as the resource that is being leased and controlled by the ServiceResource
EventNotificationAdapter	The EventNotificationAdapter defines the essentials for an event client to transform a remote event notification to a JMX notification.
MappedRemotePropertyChangeConsumer	Provides a RemotePropertyChangeConsumer mapped to a RemotePropertyChangeEvent
PooledEventConsumer	Provides the capability to use a Thread Pool to simultaneously handle multiple events.
RemotePropertyChangeConsumer	Provides a remote PropertyChangeConsumer using remote event semantics
RemotePropertyChangeDispatcher	Contains a DispatchEventHandler to handle the notification of bound property changes to interested consumers
RemotePropertyChangeEvent	The RemotePropertyChangeEvent wraps a PropertyChangeEvent giving capabilities for the remote notification of PropertyChangeEvent
RemoteServiceEvent	Wrapper around RemoteEvent to allow user defined event objects.
RoundRobinEventHandler	The RoundRobinEventHandler provides an implementation of an EventHandler which supports the notification of events using round-robin semantic.

Exception Summary

NoEventConsumerException

Package org.jini.rio.event Description

Provides classes and interfaces which enable support for distributed events. The distributed event model found within Rio extends Jini events providing an easier to use model with increased semantics. The Rio event model makes it easy to implement Jini events. The Rio event model provides a straightforward producer-consumer model with built in leasing.

The Rio Event Model provides the basis to craft a loosely coupled architecture that allows event producers to advertise event attributes, and event clients to discover event producers that produce the event(s) they are interested in.

This capability enables a peer-to-peer semantic allowing the exchange of event objects that indicate a change in state in the distributed system. Event consumers construct leased event registrations and are notified of the change in state by event producers.

By using a loosely coupled architecture, it becomes easier to adapt to changes. Interdependencies found in tightly coupled RPC oriented environments are removed with loosely coupled architectures. We can replace (or add) implementations at either end (event producer or event consumer) without altering existing components. By using a loosely coupled architecture we are able to more easily adapt to an unforeseen forward fit, replace defective component(s) online and scale a system dynamically. Overall these capabilities greatly minimize total development risk and cost.

The following event mechanisms are discussed below:

• Event Descriptors
• Event Producers
• Event Consumers
• Configuring the Event Consumer

Event Descriptors
A EventDescriptor provides a simple semantic for specifying and discovering event producers of a specific kind of event. A EventDescriptor is an attribute, part of the description of an Event Producer that is producing an event object described by a EventDescriptor.

Event objects may be simple to just indicate that an event has occurred or be rich containing other information about the event. For example, a snapshot of an object's state may be included with the event as it is delivered.

EventDescriptor’s may also be used for matching events for consumption. This will be explained in the Event Consumer section below.

Event Producers
Any service can be an Event Producer, that is. a service that has a zero-to-many dependency between objects so that when its state changes all its dependents are notified . This semantic is also known as the observer-observable and/or publish-subscribe pattern.

Rio adds to this capability by providing the notion that event producers have the flexibility to choose a notification policy, that is to say. event producers dictate event distribution mechanisms.

Event distribution mechanisms are based on an abstract EventHandler framework allowing the creation of multiple event dispatch mechanisms.

• DispatchEventHandler
A change of state in a DispatchEventHandler causes all of its valid event registrants (remote event listeners) to be notified. The EventProducer invokes the DispatchEventHandler’s fire() method to fire the event object reflecting the change in state of the EventProducer. The order in which notifications will be delivered is the order in which they registered interest

• RoundRobinEventHandler
A change of state in a RoundRobinEventHandler causes a single valid event registrant to be notified of the change in a round-robin fashion. The EventProducer invokes the RoundRobinEventHandler’s fire() method to fire the event object reflecting the change in state of the EventProducer. The order in which notifications will be delivered is the order in which they registered interest

For each subsequent notification the next event registrant in the list will be notified. If event registrants are removed from the collection of event registrants and the notification ordinal references the removed event registrant, then the notification ordinal will reference the next event registrant in the collection

Event Consumer
The recipients of an EventProducer’s event object are EventConsumer instances. The EventConsumer framework provides helper classes that manage the discovery of EventProducer instances that provide support for user defined events.

• BasicEventConsumer
The BasicEventConsumer implements theEventConsumer interface, which extends the Jini RemoteEventListener. The BasicEventConsumer, used as a local utility, manages the event registration and leasing of event registrations on behalf of a client. In this manner, clients wishing to easily register (subscribe) for the notification of an event in the distributed system need not be overly concerned with the underlying semantics and management of event registrations, leases and events

• DynamicEventConsumer
The DynamicEventConsumer extends the BasicEventConsumer and provides the capability to discover when new EventProducer instances that produce interested events appear on the network and to recognize when EventProducer instances that produce interested events leave the network

• PooledEventConsumer
The PooledEventConsumer extends DynamicEventConsumer and provides the capability to use a Thread Pool to simultaneously handle multiple events.

Configuring the Event Consumer
The BasicEventConsumer (and it's specializations) support the following configuration entries; where the configuration entry name are associated with the component name org.jini.rio.event

• eventConsumerExporter
  

  Type:	Exporter
  Default:	new BasicJeriExporter(TcpServerEndpoint.getInstance(0), new BasicILFactory(), false, false)
  Description:	The exporter used to export the BasicEventConsumer as a remote event listener. A new exporter is obtained every time a BasicEventConsumer needs to export itself

• eventLeasePreparer

  Type:	ProxyPreparer
  Default:	new BasicProxyPreparer()
  Description:	Preparer for the leases returned when a BasicEventConsumer registers with the event mechanism of any of the services

• eventLeaseDuration

  Type:	long
  Default:	30 seconds
  Description:	The length (in milliseconds) the EventRegistration lease duration should be. This value should not be too small as it will result in frequent network traffic