Rio Project 4.2 API Documentation

org.rioproject.event
Class BasicEventConsumer

java.lang.Object
  org.rioproject.event.BasicEventConsumer

All Implemented Interfaces:

Remote, EventListener, RemoteEventListener, ServerProxyTrust, EventConsumer

Direct Known Subclasses:

DynamicEventConsumer

public class BasicEventConsumer
extends Object
implements EventConsumer, ServerProxyTrust

The BasicEventConsumer is a helper class that manages the discovery of EventProducer instances that provide support for user defined events. The BasicEventConsumer is to be used as a local (within a JVM) utility, managing the discovery, event registration and leasing of EventRegistration objects on behalf of client(s). 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.

Author:

Dennis Reedy

Field Summary

static int	DEFAULT_LEASE_DURATION Default Lease duration is 5 minutes
protected EventDescriptor	edTemplate
protected long	ektime
protected Map<Long,EventRegistration>	eventRegistrationTable
protected List<RemoteServiceEventListener>	eventSubscribers
protected MarshalledObject	handback
protected long	leaseDuration
protected Hashtable<ServiceID,org.rioproject.event.BasicEventConsumer.EventLeaseManager>	leaseTable
protected int	received
static String	RESPONSE_WATCH
protected StopWatch	responseWatch
protected long	sktime
protected WatchDataSourceRegistry	watchRegistry

Constructor Summary

BasicEventConsumer(EventDescriptor edTemplate)
Create a BasicEventConsumer with an EventDescriptor

BasicEventConsumer(EventDescriptor edTemplate, Configuration config)
Create a BasicEventConsumer with an EventDescriptor

BasicEventConsumer(EventDescriptor edTemplate, RemoteServiceEventListener listener)
Create a BasicEventConsumer with an EventDescriptor and a RemoteServiceEventListener

BasicEventConsumer(EventDescriptor edTemplate, RemoteServiceEventListener listener, Configuration config)
Create a BasicEventConsumer with an EventDescriptor and a RemoteServiceEventListener

BasicEventConsumer(EventDescriptor edTemplate, RemoteServiceEventListener listener, MarshalledObject handback, Configuration config)
Create a BasicEventConsumer with an EventDescriptor, a RemoteServiceEventListener, and a MarshalledObject to be used as a handback

BasicEventConsumer(RemoteServiceEventListener listener)
Create a BasicEventConsumer with a RemoteServiceEventListener

Method Summary

void	createWatch(WatchDataSourceRegistry watchRegistry) Create a response time watch for this EventConsumer, which will track the response time for event consumers, measured by how long the response time takes
boolean	deregister(RemoteServiceEventListener listener) De-registers a registered RemoteServiceEventListener from this EventConsumer
void	deregister(ServiceID serviceID) This method handles the cleanup for removing a registration from a EventProducer instance
void	deregister(ServiceID serviceID, boolean disconnect) This method handles the cleanup for removing a registration from a EventProducer instance
void	destroyWatch() Destroys the response time watch.
protected void	finalize() Override finalize to ensure we unexport ourselves.
protected EventDescriptor	getDescriptor(Entry[] attrs, EventDescriptor template) Method to return a matching EventDescriptor from a service's set of attributes
Object	getEventRegistrationSource(long eventID) Returns the source object of an EventRegistration given an event ID
protected RemoteServiceEventListener[]	getListeners() Get all registered RemoteServiceEventListeners
TrustVerifier	getProxyVerifier() Returns a TrustVerifier which can be used to verify that a given proxy to this event consumer can be trusted
Watch	getWatch() Get the response time watch for this EventConsumer
void	notify(RemoteEvent rEvent) Remote event notification.
protected void	printStats() Convenience method to print statistics for every thousand events sent.
EventRegistration	register(EventProducer eventProducer, EventDescriptor eventDesc, ServiceID serviceID) Register for notification of event from an EventProducer.
boolean	register(RemoteServiceEventListener listener) Register a RemoteServiceEventListener to this EventConsumer.
boolean	register(RemoteServiceEventListener listener, MarshalledObject handback) Register a RemoteServiceEventListener to this EventConsumer with a MarshalledObject handback object.
EventRegistration	register(ServiceItem item) Given a ServiceItem this method checks to see if the ServiceItem contains a proxy of type EventProducer, performs event registration and ensures the Lease contained in the event registration is managed by a LeaseRenewalManager
void	terminate() The terminate method will de-register for event notifications across all discovered EventProducer instances.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

eventSubscribers

protected final List<RemoteServiceEventListener> eventSubscribers

leaseTable

protected final Hashtable<ServiceID,org.rioproject.event.BasicEventConsumer.EventLeaseManager> leaseTable

eventRegistrationTable

protected final Map<Long,EventRegistration> eventRegistrationTable

edTemplate

protected EventDescriptor edTemplate

received

protected int received

sktime

protected long sktime

ektime

protected long ektime

handback

protected MarshalledObject handback

DEFAULT_LEASE_DURATION

public static final int DEFAULT_LEASE_DURATION

Default Lease duration is 5 minutes

See Also:

Constant Field Values

leaseDuration

protected long leaseDuration

responseWatch

protected StopWatch responseWatch

watchRegistry

protected WatchDataSourceRegistry watchRegistry

RESPONSE_WATCH

public static final String RESPONSE_WATCH

See Also:

Constant Field Values

Constructor Detail

BasicEventConsumer

public BasicEventConsumer(EventDescriptor edTemplate)
                   throws Exception

Create a BasicEventConsumer with an EventDescriptor

Parameters:

edTemplate - The EventDescriptor template

Throws:

Exception - If the BasicEventConsumer cannot be created

BasicEventConsumer

public BasicEventConsumer(RemoteServiceEventListener listener)
                   throws Exception

Create a BasicEventConsumer with a RemoteServiceEventListener

Parameters:

listener - The RemoteServiceEventListener

Throws:

Exception - If the BasicEventConsumer cannot be created

BasicEventConsumer

public BasicEventConsumer(EventDescriptor edTemplate,
                          Configuration config)
                   throws Exception

Create a BasicEventConsumer with an EventDescriptor

Parameters:

edTemplate - The EventDescriptor template

config - Configuration object

Throws:

Exception - If the BasicEventConsumer cannot be created

BasicEventConsumer

public BasicEventConsumer(EventDescriptor edTemplate,
                          RemoteServiceEventListener listener)
                   throws Exception

Create a BasicEventConsumer with an EventDescriptor and a RemoteServiceEventListener

Parameters:

edTemplate - The EventDescriptor template

listener - The RemoteServiceEventListener

Throws:

Exception - If the BasicEventConsumer cannot be created

BasicEventConsumer

public BasicEventConsumer(EventDescriptor edTemplate,
                          RemoteServiceEventListener listener,
                          Configuration config)
                   throws Exception

Create a BasicEventConsumer with an EventDescriptor and a RemoteServiceEventListener

Parameters:

edTemplate - The EventDescriptor template

listener - The RemoteServiceEventListener

config - Configuration object

Throws:

Exception - If the BasicEventConsumer cannot be created

BasicEventConsumer

public BasicEventConsumer(EventDescriptor edTemplate,
                          RemoteServiceEventListener listener,
                          MarshalledObject handback,
                          Configuration config)
                   throws Exception

Create a BasicEventConsumer with an EventDescriptor, a RemoteServiceEventListener, and a MarshalledObject to be used as a handback

Parameters:

edTemplate - The EventDescriptor template

listener - The RemoteServiceEventListener

handback - The MarshalledObject to be used as a handback

config - Configuration object

Throws:

Exception - If the BasicEventConsumer cannot be created

Method Detail

terminate

public void terminate()

The terminate method will de-register for event notifications across all discovered EventProducer instances. Invocation of this method will result in the cancellation of any leases involved with event registration and the removal from the event notification pool. This method will also unexport the EventConsumer, removing it from the RMI runtime. This method will also destroy the response time watch if it was created

Specified by:

terminate in interface EventConsumer

register

public boolean register(RemoteServiceEventListener listener)

Register a RemoteServiceEventListener to this EventConsumer. If there are no RemoteServiceEventListener instances registered events will be dropped by this BasicEventConsumer. Each registered RemoteServiceEventListener will be notified for each event received.

Specified by:

register in interface EventConsumer

Parameters:

listener - The RemoteServiceEventListener

Returns:

true if the RemoteServiceEventListener has been added

register

public boolean register(RemoteServiceEventListener listener,
                        MarshalledObject handback)

Register a RemoteServiceEventListener to this EventConsumer with a MarshalledObject handback object. If there are no RemoteServiceEventListener instances registered events will be dropped by this BasicEventConsumer. Each registered RemoteServiceEventListener will be notified for each event received

Specified by:

register in interface EventConsumer

Parameters:

listener - The RemoteServiceEventListener

handback - The MarshalledObject to be used as a handback

Returns:

true if the RemoteServiceEventListener has been added

deregister

public boolean deregister(RemoteServiceEventListener listener)

De-registers a registered RemoteServiceEventListener from this EventConsumer

Specified by:

deregister in interface EventConsumer

Parameters:

listener - The RemoteServiceEventListener

Returns:

true if the RemoteServiceEventListener was removed

createWatch

public void createWatch(WatchDataSourceRegistry watchRegistry)

Create a response time watch for this EventConsumer, which will track the response time for event consumers, measured by how long the response time takes

Parameters:

watchRegistry - The WatchDataSourceRegistry to register the watch

destroyWatch

public void destroyWatch()

Destroys the response time watch. Once this method is called the response time watch will be rendered useless

getWatch

public Watch getWatch()

Get the response time watch for this EventConsumer

Returns:

The response time watch for this EventConsumer

register

public EventRegistration register(ServiceItem item)

Given a ServiceItem this method checks to see if the ServiceItem contains a proxy of type EventProducer, performs event registration and ensures the Lease contained in the event registration is managed by a LeaseRenewalManager

Parameters:

item - The ServiceItem

Returns:

The EventRegistration, or null if the service is not an EventProducer or the EventDescriptor template the BasicEventConsumer was started with cannot be matched

Throws:

NullPointerException - if the item parameter is null

register

public EventRegistration register(EventProducer eventProducer,
                                  EventDescriptor eventDesc,
                                  ServiceID serviceID)

Register for notification of event from an EventProducer.

Parameters:

eventProducer - The EventProducer, must not be null

eventDesc - The EventDescriptor, must not be null

serviceID - The serviceID of the EventProducer to register

Returns:

The EventRegistration, or null if the service is not an EventProducer or the EventDescriptor template the BasicEventConsumer was started with cannot be matched

Throws:

NullPointerException - if any og the parameters are null

getEventRegistrationSource

public Object getEventRegistrationSource(long eventID)

Returns the source object of an EventRegistration given an event ID

Specified by:

getEventRegistrationSource in interface EventConsumer

Parameters:

eventID - The eventID

Returns:

If found, returns the source object associated with the eventID, otherwise returns null

deregister

public void deregister(ServiceID serviceID)

This method handles the cleanup for removing a registration from a EventProducer instance

Parameters:

serviceID - The serviceID of the EventProducer to deregister

Throws:

NullPointerException - if the serviceID parameter is null

deregister

public void deregister(ServiceID serviceID,
                       boolean disconnect)

This method handles the cleanup for removing a registration from a EventProducer instance

Parameters:

serviceID - The serviceID of the EventProducer to deregister

disconnect - Whether to explicitly cancel the lease with the EventProducer, or just let the least time out

Throws:

NullPointerException - if the serviceID parameter is null

notify

public void notify(RemoteEvent rEvent)
            throws UnknownEventException

Remote event notification. This method is called by an EventProducer to notify the RemoteEventListener of a state change through a RemoteEvent

Specified by:

notify in interface RemoteEventListener

Throws:

UnknownEventException - If the RemoteEvent cannot be downcast to a RemoteServiceEvent

getProxyVerifier

public TrustVerifier getProxyVerifier()

Returns a TrustVerifier which can be used to verify that a given proxy to this event consumer can be trusted

Specified by:

getProxyVerifier in interface ServerProxyTrust

getDescriptor

protected EventDescriptor getDescriptor(Entry[] attrs,
                                        EventDescriptor template)

Method to return a matching EventDescriptor from a service's set of attributes

Parameters:

attrs - Array of attributes

template - The EventDescriptor template

Returns:

An EventDescriptor if found or null if no match

printStats

protected void printStats()

Convenience method to print statistics for every thousand events sent. This method will only print result if the Logger has it's Level set to FINEST

finalize

protected void finalize()
                 throws Throwable

Override finalize to ensure we unexport ourselves. This is needed if

Overrides:

finalize in class Object

Throws:

Throwable

getListeners

protected RemoteServiceEventListener[] getListeners()

Get all registered RemoteServiceEventListeners

Returns:

An array of all registered RemoteServiceEventListener objects