org.bushe.swing.event
Class ThreadSafeEventService

java.lang.Object
  extended by org.bushe.swing.event.ThreadSafeEventService
All Implemented Interfaces:
EventService
Direct Known Subclasses:
SwingEventService

public class ThreadSafeEventService
extends java.lang.Object
implements EventService

A thread-safe EventService implementation.

Multithreading

This implementation is not Swing thread-safe. If publication occurs on a thread other than the Swing EventDispatchThread, subscribers will receive the event on the calling thread, and not the EDT. Swing components should use the SwingEventService instead, which is the implementation used by the EventBus.

Two threads may be accessing the ThreadSafeEventService at the same time, on unsubscribing a listener for topic "A" and the other publishing on topic "A". If the unsubsubscribing thread gets the lock first, then it is unsubscubscribed, end of story. If the publisher gets the lock first, then a snapshot copy of the current listeners is made during the publication, the lock is released and the subscribers are called. Between the time the lock is released and the time that the listener is called, the unsubscribing thread can unsubscribe, resulting in an unsubscribed object receiving notifiction of the event.

On event publication, subscribers are called in the order in which they subscribed.

Events and/or topic data can be cached, but are not by default. To cache events or topic data, call #setDefaultCacheSizePerClassOrTopic(int), #setCacheSizeForEventClass(Class, int), or #setCacheSizeForTopic(String, int), #setCacheSizeForTopic(Pattern, int). Retrieve cached values with #getLastEvent(Class), #getLastTopicData(String), #getCachedEvents(Class), or #getCachedTopicData(String). Using caching while subscribing is most likely to make sense only if you subscribe and publish on the same thread (so caching is very useful for Swing applications since both happen on the EDT in a single-threaded manner). In multithreaded applications, you never know if your subscriber has handled an event while it was being subscribed (before the subscribe() method returned) that is newer or older than the retrieved cached value (taked before or after subscribe() respectively).

To deal with subscribers that take too long (a concern in Swing applications), the EventService can be made to issue SubscriberTimingEvents when subscribers exceed a certain time. This does not interrupt subscriber processing and is published after the subscriber finishes. The service can log a warning for SubscriberTimingEvents, see the constructor (long, boolean). The timing is checked for veto subscribers too.

Logging

Exceptions are logged by default, override handleException(String,Object,String,Object,Throwable, StackTraceElement[],String) to handleException exceptions in another way. Each call to a subscriber is wrapped in a try block to ensure one listener does not interfere with another.

Fine logging can be turned via java.util.logging using the name "org.bushe.swing.event.ThreadSafeEventService". This aids in debugging which subscription and publication issues.

Cleanup of Stale WeakReferences and Stale Annotation Proxies

The EventService may need to clean up stale WeakReferences and ProxySubscribers created for EventBus annotations. (Aside: EventBus Annotations are handled by the creation of proxies to the annotated objects. Since the annotations create weak references by default, annotation proxies must held strongly by the EventService, otherwise the proxy is garbage collected.) When a WeakReference's referent or an ProxySubscriber's proxiedObject (the annotated object) is claimed by the garbage collector, the EventService still holds onto the actual WeakReference or ProxySubscriber subscribed to the EventService (which are pretty tiny).

There are two ways that these stale WeakReferences and ProxySubscribers are cleaned up.

  1. On every publish, subscribe and unsubscribe, every subscriber and veto subscriber to a class or topic is checked to see if it is a stale WeakReference or a stale ProxySubscriber (one whose getProxySubscriber() returns null). If the subscriber is stale, it is unsubscribed from the EventService immediately. If it is a ProxySubscriber, it's proxyUnsubscribed() method is called after it is unsubscribed. (This isn't as expecive as it sounds, since checks to avoid double subscription is necessary anyway).
  2. Another cleanup thread may get started to clean up remaining stale subscribers. This cleanup thread only comes into play for subscribers to topic or classes that haven't been used (published/subscribed/unsibscribed to). A detailed description of the cleanup thread follows.

The Cleanup Thread

If a topic or class is never published to again, WeakReferences and ProxySubscribers can be left behind if they are not cleaned up. To prevent loitering stale subscribers, the ThreadSafeEventService may periodically run through all the EventSubscribers and VetoSubscribers for all topics and classes and clean up stale proxies. Proxies for Annotations that have a ReferenceStrength.STRONG are never cleaned up in normal usage. (By specifying ReferenceStrength.STRONG, the programmer is buying into unsubscribing annotated objects themselves. There is one caveat: If getProxiedSubscriber() returns null, even for a ProxySubscriber with a STRONG reference strength, that proxy is cleaned up as it is assumed it is stale or just wrong. This would not occur normally in EventBus usage, but only if someone is implementing their own custom ProxySubscriber and/or AnnotationProcessor.)

Cleanup is pretty rare in general. Not only are stale subscribers cleaned up with regular usage, stale subscribers on abandonded topics and classes do not take up a lot of memory, hence, they are allowed to build up to a certain degree. Cleanup does not occur until the number of WeakReferences and SubscriptionsProxy's with WeakReference strength subscribed to an EventService for all the EventService's subscriptions in total exceed the cleanupStartThreshhold, which is set to CLEANUP_START_THRESHOLD_DEFAULT (500) by default. The default is overridable in the constructor or via #setCleanupStartThreshhold(Integer). If set to null, cleanup will never start.

Once the cleanup start threshold is exceeded, a java.util.Timer is started to clean up stale subscribers periodically in another thread. The timer will fire every cleanupPeriodMS milliseconds, which is set to the CLEANUP_PERIOD_MS_DEFAULT (20 minutes) by default. The default is overridable in the constructor or via #setCleanupPeriodMS(Integer). If set to null, cleanup will not start. This is implemented with a java.util.Timer, so Timer's warnings apply - setting this too low will cause cleanups to bunch up and hog the cleanup thread.

After a cleanup cycle completes, if the number of stale subscribers falls at or below the cleanupStopThreshhold cleanup stops until the cleanupStartThreshhold is exceeded again. The cleanupStopThreshhold is set to CLEANUP_STOP_THRESHOLD_DEFAULT (100) by default. The default is overridable in the constructor or via #setCleanupStopThreshhold(Integer). If set to null or 0, cleanup will not stop if it is ever started.

Cleanup can be monitored by subscribing to the CleanupEvent class.

All cleanup parameters are tunable "live" and checked after each subscription and after each cleanup cycle. To make cleanup never run, set cleanupStartThreshhold to Integer.MAX_VALUE and cleanupPeriodMS to null. To get cleanup to run continuously, set set cleanupStartThreshhold to 0 and cleanupPeriodMS to some reasonable value, perhaps 1000 (1 second) or so (not recommended, cleanup is conducted with regular usage and the cleanup thread is rarely created or invoked).

Cleanup is not run in a daemon thread, and thus will not stop the JVM from exiting.

Author:
Michael Bushe michael@bushe.com
See Also:
for a complete description of the API
To do:
perhaps publication should double-check to see if a subscriber is still subscribed, (param) a JMS-like selector (can be done in base classes by implements like a commons filter, (param) register a Comparator to sort subscriber's calling order - for a class or topic

Field Summary
static java.lang.Long CLEANUP_PERIOD_MS_DEFAULT
           
static java.lang.Integer CLEANUP_START_THRESHOLD_DEFAULT
           
static java.lang.Integer CLEANUP_STOP_THRESHOLD_DEFAULT
           
protected static java.util.logging.Logger LOG
           
 
Constructor Summary
ThreadSafeEventService()
          Creates a ThreadSafeEventService that does not monitor timing of handlers.
ThreadSafeEventService(java.lang.Integer cleanupStartThreshold, java.lang.Integer cleanupStopThreshold, java.lang.Long cleanupPeriodMS)
          Creates a ThreadSafeEventService while providing proxy cleanup customization.
ThreadSafeEventService(java.lang.Long timeThresholdForEventTimingEventPublication)
          Creates a ThreadSafeEventService while providing time monitoring options.
ThreadSafeEventService(java.lang.Long timeThresholdForEventTimingEventPublication, boolean subscribeTimingEventsInternally)
          Creates a ThreadSafeEventService while providing time monitoring options.
ThreadSafeEventService(java.lang.Long timeThresholdForEventTimingEventPublication, boolean subscribeTimingEventsInternally, java.lang.Integer cleanupStartThreshold, java.lang.Integer cleanupStopThreshold, java.lang.Long cleanupPeriodMS)
          Creates a ThreadSafeEventService while providing time monitoring options.
 
Method Summary
protected  void addEventToCache(java.lang.Object event, java.lang.String topic, java.lang.Object eventObj)
          Adds an event to the event cache, if appropriate.
 void clearAllSubscribers()
          Clears all current subscribers and veto subscribers
 void clearCache()
          Clear all event caches for all topics and event.
 void clearCache(java.lang.Class eventClassToClear)
          Clears the event cache for a specific event class or interface and it's any of it's subclasses or implementing classes.
 void clearCache(java.util.regex.Pattern pattern)
          Clears the topic data cache for all topics that match a particular pattern.
 void clearCache(java.lang.String topic)
          Clears the topic data cache for a specific topic name.
protected  void decWeakRefPlusProxySubscriberCount()
          Decrement the count of stale proxies
 java.util.List getCachedEvents(java.lang.Class eventClass)
           
 java.util.List getCachedTopicData(java.lang.String topic)
           
 int getCacheSizeForEventClass(java.lang.Class eventClass)
          Returns the number of events cached for a particular class of event.
 int getCacheSizeForTopic(java.lang.String topic)
          Returns the number of cached data objects published on a particular topic.
 java.lang.Long getCleanupPeriodMS()
          Get the cleanup interval.
 java.lang.Integer getCleanupStartThreshhold()
          Gets the threshold above which cleanup starts.
 java.lang.Integer getCleanupStopThreshold()
          Gets the threshold below which cleanup stops.
 int getDefaultCacheSizePerClassOrTopic()
           
 java.lang.Object getLastEvent(java.lang.Class eventClass)
           
 java.lang.Object getLastTopicData(java.lang.String topic)
           
protected  java.lang.Object getRealSubscriberAndCleanStaleSubscriberIfNecessary(java.util.Iterator iterator, java.lang.Object existingSubscriber)
          Unsubscribe a subscriber if it is a stale ProxySubscriber.
 java.util.List getSubscribers(java.lang.Class eventClass)
          Union of getSubscribersToClass(Class) and getSubscribersToExactClass(Class)
 java.util.List getSubscribers(java.lang.String topic)
          Union of getSubscribersByPattern(String) and geSubscribersToTopic(String)
 java.util.List getSubscribers(java.lang.reflect.Type eventType)
           
 java.util.List getSubscribersByPattern(java.lang.String topic)
           
 java.util.List getSubscribersToClass(java.lang.Class eventClass)
           
 java.util.List getSubscribersToExactClass(java.lang.Class eventClass)
           
protected  java.util.List getSubscribersToPattern(java.util.regex.Pattern topicPattern)
           
 java.util.List getSubscribersToTopic(java.lang.String topic)
           
 java.util.List getVetoSubscribers(java.lang.Class eventClass)
           
 java.util.List getVetoSubscribers(java.util.regex.Pattern topicPattern)
           
 java.util.List getVetoSubscribers(java.lang.String topic)
           
 java.util.List getVetoSubscribersToClass(java.lang.Class eventClass)
           
 java.util.List getVetoSubscribersToExactClass(java.lang.Class eventClass)
           
protected  void handleException(java.lang.Object event, java.lang.Throwable e, java.lang.StackTraceElement[] callingStack, EventSubscriber eventSubscriber)
          Called during event handling exceptions, calls handleException
protected  void handleException(java.lang.String action, java.lang.Object event, java.lang.String topic, java.lang.Object eventObj, java.lang.Throwable e, java.lang.StackTraceElement[] callingStack, java.lang.String sourceString)
          All exception handling goes through this method.
protected  void handleVeto(VetoEventListener vl, java.lang.Object event, VetoTopicEventListener vtl, java.lang.String topic, java.lang.Object eventObj)
          Handle vetos of an event or topic, by default logs finely.
protected  void incWeakRefPlusProxySubscriberCount()
          Increment the count of stale proxies and start a cleanup task if necessary
protected  void onEventException(java.lang.String topic, java.lang.Object eventObj, java.lang.Throwable e, java.lang.StackTraceElement[] callingStack, EventTopicSubscriber eventTopicSubscriber)
          Called during event handling exceptions, calls handleException
 void publish(java.lang.Object event)
          Publishes an Object so that subscribers will be notified if they subscribed to the Object's class, one of its subclasses, or to one of its implementing interfaces.
protected  void publish(java.lang.Object event, java.lang.String topic, java.lang.Object eventObj, java.util.List subscribers, java.util.List vetoSubscribers, java.lang.StackTraceElement[] callingStack)
          All publish methods call this method.
 void publish(java.lang.String topicName, java.lang.Object eventObj)
          Publishes an object on a topic name so that all subscribers to that name will be notified about it.
 void publish(java.lang.reflect.Type genericType, java.lang.Object event)
          Use this method to publish generified objects to subscribers of Types, i.e.
protected  void removeProxySubscriber(ProxySubscriber proxy, java.util.Iterator iter)
           
 void setCacheSizeForEventClass(java.lang.Class eventClass, int cacheSize)
          Set the number of events cached for a particular class of event.
 void setCacheSizeForTopic(java.util.regex.Pattern pattern, int cacheSize)
          Set the number of published data objects cached for topics matching a pattern.
 void setCacheSizeForTopic(java.lang.String topicName, int cacheSize)
          Set the number of published data objects cached for a particular event topic.
 void setCleanupPeriodMS(java.lang.Long cleanupPeriodMS)
          Sets the cleanup interval.
 void setCleanupStartThreshhold(java.lang.Integer cleanupStartThreshhold)
          Sets the threshold above which cleanup starts.
 void setCleanupStopThreshold(java.lang.Integer cleanupStopThreshold)
          Sets the threshold below which cleanup stops.
 void setDefaultCacheSizePerClassOrTopic(int defaultCacheSizePerClassOrTopic)
          Sets the default cache size for each kind of event, default is 0 (no caching).
 boolean subscribe(java.lang.Class cl, EventSubscriber eh)
          Subscribes a WeakReference to an EventSubscriber to the publication of events of an event class and its subclasses, or to an event's interface.
protected  boolean subscribe(java.lang.Object topicOrClass, java.util.Map subscriberMap, java.lang.Object subscriber)
          All subscribe methods call this method, including veto subscriptions.
 boolean subscribe(java.util.regex.Pattern pat, EventTopicSubscriber eh)
          Subscribes a WeakReference to an EventSubscriber to the publication of all the topic names that match a RegEx Pattern.
 boolean subscribe(java.lang.String topic, EventTopicSubscriber eh)
          Subscribes a WeakReference to an EventSubscriber to the publication of a topic name.
 boolean subscribe(java.lang.reflect.Type type, EventSubscriber eh)
           
 boolean subscribeExactly(java.lang.Class cl, EventSubscriber eh)
          Subscribes a WeakReference to an EventSubscriber to the publication of events of an event class (not its subclasses).
 boolean subscribeExactlyStrongly(java.lang.Class cl, EventSubscriber eh)
          Subscribes a subscriber to an event class (and not its subclasses).
 boolean subscribeStrongly(java.lang.Class cl, EventSubscriber eh)
          Subscribes a subscriber to an event class and its subclasses.
 boolean subscribeStrongly(java.util.regex.Pattern pat, EventTopicSubscriber eh)
          Subscribes a subscriber to all the event topic names that match a RegEx expression.
 boolean subscribeStrongly(java.lang.String name, EventTopicSubscriber eh)
          Subscribes a subscriber to an event topic name.
protected  void subscribeTiming(SubscriberTimingEvent event)
           
protected  void subscribeVetoException(java.lang.Object event, java.lang.String topic, java.lang.Object eventObj, java.lang.Throwable e, java.lang.StackTraceElement[] callingStack, VetoEventListener vetoer)
          Called during veto exceptions, calls handleException
 boolean subscribeVetoListener(java.lang.Class eventClass, VetoEventListener vetoListener)
          Subscribes a WeakReference to a VetoListener to a event class and its subclasses.
protected  boolean subscribeVetoListener(java.lang.Object subscription, java.util.Map vetoListenerMap, java.lang.Object vetoListener)
          All veto subscriptions methods call this method.
 boolean subscribeVetoListener(java.util.regex.Pattern topicPattern, VetoTopicEventListener vetoListener)
          Subscribes a WeakReference to an VetoTopicEventListener to all the topic names that match the RegEx Pattern.
 boolean subscribeVetoListener(java.lang.String topic, VetoTopicEventListener vetoListener)
          Subscribes a WeakReference to a VetoTopicEventListener to a topic name.
 boolean subscribeVetoListenerExactly(java.lang.Class eventClass, VetoEventListener vetoListener)
          Subscribes a WeakReference to a VetoListener to a event class (but not its subclasses).
 boolean subscribeVetoListenerExactlyStrongly(java.lang.Class eventClass, VetoEventListener vetoListener)
          Subscribes a VetoListener for an event class (but not its subclasses).
 boolean subscribeVetoListenerStrongly(java.lang.Class eventClass, VetoEventListener vetoListener)
          Subscribes a VetoListener for an event class and its subclasses.
 boolean subscribeVetoListenerStrongly(java.util.regex.Pattern topicPattern, VetoTopicEventListener vetoListener)
          Subscribes a VetoTopicEventListener to a set of topics that match a RegEx expression.
 boolean subscribeVetoListenerStrongly(java.lang.String topic, VetoTopicEventListener vetoListener)
          Subscribes a VetoListener to a topic name.
 boolean unsubscribe(java.lang.Class cl, EventSubscriber eh)
          Stop the subscription for a subscriber that is subscribed to an event class and its subclasses.
 boolean unsubscribe(java.lang.Class eventClass, java.lang.Object subcribedByProxy)
          When using annotations, an object may be subscribed by proxy.
protected  boolean unsubscribe(java.lang.Object o, java.util.Map subscriberMap, java.lang.Object subscriber)
          All event subscriber unsubscriptions call this method.
 boolean unsubscribe(java.util.regex.Pattern topicPattern, EventTopicSubscriber eh)
          Stop the subscription for a subscriber that is subscribed to an event topic
 boolean unsubscribe(java.util.regex.Pattern pattern, java.lang.Object subcribedByProxy)
          When using annotations, an object may be subscribed by proxy.
 boolean unsubscribe(java.lang.String name, EventTopicSubscriber eh)
          Stop the subscription for a subscriber that is subscribed to an event topic
 boolean unsubscribe(java.lang.String topic, java.lang.Object subcribedByProxy)
          When using annotations, an object may be subscribed by proxy.
 boolean unsubscribeExactly(java.lang.Class cl, EventSubscriber eh)
          Stop the subscription for a subscriber that is subscribed to an event class (and not its subclasses).
 boolean unsubscribeExactly(java.lang.Class eventClass, java.lang.Object subcribedByProxy)
          When using annotations, an object may be subscribed by proxy.
 boolean unsubscribeVetoListener(java.lang.Class eventClass, VetoEventListener vetoListener)
          Stop the subscription for a vetoListener that is subscribed to an event class and its subclasses.
protected  boolean unsubscribeVetoListener(java.lang.Object o, java.util.Map vetoListenerMap, java.lang.Object vl)
          All veto unsubscriptions methods call this method.
 boolean unsubscribeVetoListener(java.util.regex.Pattern topicPattern, VetoTopicEventListener vetoListener)
          Stop the subscription for a VetoTopicEventListener that is subscribed to an event topic RegEx pattern.
 boolean unsubscribeVetoListener(java.lang.String topic, VetoTopicEventListener vetoListener)
          Stop the subscription for a VetoTopicEventListener that is subscribed to an event topic name.
 boolean unsubscribeVetoListenerExactly(java.lang.Class eventClass, VetoEventListener vetoListener)
          Stop the subscription for a vetoListener that is subscribed to an event class (but not its subclasses).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CLEANUP_START_THRESHOLD_DEFAULT

public static final java.lang.Integer CLEANUP_START_THRESHOLD_DEFAULT

CLEANUP_STOP_THRESHOLD_DEFAULT

public static final java.lang.Integer CLEANUP_STOP_THRESHOLD_DEFAULT

CLEANUP_PERIOD_MS_DEFAULT

public static final java.lang.Long CLEANUP_PERIOD_MS_DEFAULT

LOG

protected static final java.util.logging.Logger LOG
Constructor Detail

ThreadSafeEventService

public ThreadSafeEventService()
Creates a ThreadSafeEventService that does not monitor timing of handlers.


ThreadSafeEventService

public ThreadSafeEventService(java.lang.Long timeThresholdForEventTimingEventPublication)
Creates a ThreadSafeEventService while providing time monitoring options.

Parameters:
timeThresholdForEventTimingEventPublication - the longest time a subscriber should spend handling an event, The service will publish an SubscriberTimingEvent after listener processing if the time was exceeded. If null, no EventSubscriberTimingEvent will be issued.

ThreadSafeEventService

public ThreadSafeEventService(java.lang.Long timeThresholdForEventTimingEventPublication,
                              boolean subscribeTimingEventsInternally)
Creates a ThreadSafeEventService while providing time monitoring options.

Parameters:
timeThresholdForEventTimingEventPublication - the longest time a subscriber should spend handling an event, The service will publish an SubscriberTimingEvent after listener processing if the time was exceeded. If null, no EventSubscriberTimingEvent will be issued.
subscribeTimingEventsInternally - add a subscriber to the SubscriberTimingEvent internally and call the protected subscribeTiming() method when they occur. This logs a warning to a java.util.logging logger by default.

ThreadSafeEventService

public ThreadSafeEventService(java.lang.Integer cleanupStartThreshold,
                              java.lang.Integer cleanupStopThreshold,
                              java.lang.Long cleanupPeriodMS)
Creates a ThreadSafeEventService while providing proxy cleanup customization. Proxies are used with Annotations.

Parameters:
cleanupStartThreshold - see class javadoc.
cleanupStopThreshold - see class javadoc.
cleanupPeriodMS - see class javadoc.

ThreadSafeEventService

public ThreadSafeEventService(java.lang.Long timeThresholdForEventTimingEventPublication,
                              boolean subscribeTimingEventsInternally,
                              java.lang.Integer cleanupStartThreshold,
                              java.lang.Integer cleanupStopThreshold,
                              java.lang.Long cleanupPeriodMS)
Creates a ThreadSafeEventService while providing time monitoring options.

Parameters:
timeThresholdForEventTimingEventPublication - the longest time a subscriber should spend handling an event. The service will publish an SubscriberTimingEvent after listener processing if the time was exceeded. If null, no SubscriberTimingEvent will be issued.
subscribeTimingEventsInternally - add a subscriber to the SubscriberTimingEvent internally and call the protected subscribeTiming() method when they occur. This logs a warning to a java.util.logging logger by default.
cleanupStartThreshold - see class javadoc.
cleanupStopThreshold - see class javadoc.
cleanupPeriodMS - see class javadoc.
Throws:
java.lang.IllegalArgumentException - if timeThresholdForEventTimingEventPublication is null and subscribeTimingEventsInternally is true.
To do:
(nonSwing-only?) start a timer call and when it calls back, report the time if exceeded.
Method Detail

getCleanupStartThreshhold

public java.lang.Integer getCleanupStartThreshhold()
Gets the threshold above which cleanup starts. See the class javadoc on cleanup.

Returns:
the threshold at which cleanup starts

setCleanupStartThreshhold

public void setCleanupStartThreshhold(java.lang.Integer cleanupStartThreshhold)
Sets the threshold above which cleanup starts. See the class javadoc on cleanup.

Parameters:
the - threshold at which cleanup starts

getCleanupStopThreshold

public java.lang.Integer getCleanupStopThreshold()
Gets the threshold below which cleanup stops. See the class javadoc on cleanup.

Parameters:
the - threshold at which cleanup stops (it may start again)

setCleanupStopThreshold

public void setCleanupStopThreshold(java.lang.Integer cleanupStopThreshold)
Sets the threshold below which cleanup stops. See the class javadoc on cleanup.

Parameters:
the - threshold at which cleanup stops (it may start again).

getCleanupPeriodMS

public java.lang.Long getCleanupPeriodMS()
Get the cleanup interval. See the class javadoc on cleanup.

Parameters:
the - interval in milliseconds between cleanup runs.

setCleanupPeriodMS

public void setCleanupPeriodMS(java.lang.Long cleanupPeriodMS)
Sets the cleanup interval. See the class javadoc on cleanup.

Parameters:
the - interval in milliseconds between cleanup runs. Passing null stops cleanup.

subscribe

public boolean subscribe(java.lang.Class cl,
                         EventSubscriber eh)
Description copied from interface: EventService
Subscribes a WeakReference to an EventSubscriber to the publication of events of an event class and its subclasses, or to an event's interface.

Subscription is weak by default to avoid having to call unsubscribe(), and to avoid the memory leaks that would occur if unsubscribe was not called. The service will respect the WeakReference semantics. In other words, if the subscriber has not been garbage collected, then onEvent(Object) will be called normally. If the hard reference has been garbage collected, the service will unsubscribe it's WeakReference.

It's allowable to call unsubscribe() with the same EventSubscriber hard reference to stop a subscription immediately.

The service will create the WeakReference on behalf of the caller. on behalf of the caller.

Specified by:
subscribe in interface EventService
Parameters:
cl - the class of published objects to listen to
eh - The subscriber that will accept the events when published.
Returns:
true if the subscriber was subscribed sucessfully, false otherwise
See Also:
EventService.subscribe(Class,EventSubscriber)

subscribe

public boolean subscribe(java.lang.reflect.Type type,
                         EventSubscriber eh)
Specified by:
subscribe in interface EventService
See Also:
EventService.subscribe(java.lang.reflect.Type, EventSubscriber)

subscribeExactly

public boolean subscribeExactly(java.lang.Class cl,
                                EventSubscriber eh)
Description copied from interface: EventService
Subscribes a WeakReference to an EventSubscriber to the publication of events of an event class (not its subclasses).

Subscription is weak by default to avoid having to call unsubscribe(), and to avoid the memory leaks that would occur if unsubscribe was not called. The service will respect the WeakReference semantics. In other words, if the subscriber has not been garbage collected, then the onEvent will be called normally. If the hard reference has been garbage collected, the service will unsubscribe it's WeakReference.

It's allowable to call unsubscribe() with the same EventSubscriber hard reference to stop a subscription immediately.

The service will create the WeakReference on behalf of the caller.

Specified by:
subscribeExactly in interface EventService
Parameters:
cl - the class of published objects to listen to
eh - The subscriber that will accept the events when published.
Returns:
true if the subscriber was subscribed sucessfully, false otherwise
See Also:
EventService.subscribeExactly(Class,EventSubscriber)

subscribe

public boolean subscribe(java.lang.String topic,
                         EventTopicSubscriber eh)
Description copied from interface: EventService
Subscribes a WeakReference to an EventSubscriber to the publication of a topic name.

Subscription is weak by default to avoid having to call unsubscribe(), and to avoid the memory leaks that would occur if unsubscribe was not called. The service will respect the WeakReference semantics. In other words, if the subscriber has not been garbage collected, then the onEvent will be called normally. If the hard reference has been garbage collected, the service will unsubscribe it's WeakReference.

It's allowable to call unsubscribe() with the same EventSubscriber hard reference to stop a subscription immediately.

Specified by:
subscribe in interface EventService
Parameters:
topic - the name of the topic listened to
eh - The topic subscriber that will accept the events when published.
Returns:
true if the subscriber was subscribed sucessfully, false otherwise
See Also:
EventService.subscribe(String,EventTopicSubscriber)

subscribe

public boolean subscribe(java.util.regex.Pattern pat,
                         EventTopicSubscriber eh)
Description copied from interface: EventService
Subscribes a WeakReference to an EventSubscriber to the publication of all the topic names that match a RegEx Pattern.

Subscription is weak by default to avoid having to call unsubscribe(), and to avoid the memory leaks that would occur if unsubscribe was not called. The service will respect the WeakReference semantics. In other words, if the subscriber has not been garbage collected, then the onEvent will be called normally. If the hard reference has been garbage collected, the service will unsubscribe it's WeakReference.

It's allowable to call unsubscribe() with the same EventSubscriber hard reference to stop a subscription immediately.

Specified by:
subscribe in interface EventService
Parameters:
pat - pattern that matches to the name of the topic published to
eh - The topic subscriber that will accept the events when published.
Returns:
true if the subscriber was subscribed sucessfully, false otherwise
See Also:
EventService.subscribe(Pattern,EventTopicSubscriber)

subscribeStrongly

public boolean subscribeStrongly(java.lang.Class cl,
                                 EventSubscriber eh)
Description copied from interface: EventService
Subscribes a subscriber to an event class and its subclasses.

The subscriber will remain subscribed until EventService.unsubscribe(Class,EventSubscriber) is called.

Specified by:
subscribeStrongly in interface EventService
Parameters:
cl - the class of published objects to listen to
eh - The subscriber that will accept the events when published.
Returns:
true if the subscriber was subscribed sucessfully, false otherwise
See Also:
EventService.subscribeStrongly(Class,EventSubscriber)

subscribeExactlyStrongly

public boolean subscribeExactlyStrongly(java.lang.Class cl,
                                        EventSubscriber eh)
Description copied from interface: EventService
Subscribes a subscriber to an event class (and not its subclasses).

The subscriber will remain subscribed until EventService.unsubscribe(Class,EventSubscriber) is called.

Specified by:
subscribeExactlyStrongly in interface EventService
Parameters:
cl - the class of published objects to listen to
eh - The subscriber that will accept the events when published.
Returns:
true if the subscriber was subscribed sucessfully, false otherwise
See Also:
EventService.subscribeExactlyStrongly(Class,EventSubscriber)

subscribeStrongly

public boolean subscribeStrongly(java.lang.String name,
                                 EventTopicSubscriber eh)
Description copied from interface: EventService
Subscribes a subscriber to an event topic name.

The subscriber will remain subscribed until EventService.unsubscribe(String,EventTopicSubscriber) is called.

Specified by:
subscribeStrongly in interface EventService
Parameters:
name - the name of the topic listened to
eh - The topic subscriber that will accept the events when published.
Returns:
true if the subscriber was subscribed sucessfully, false otherwise
See Also:
EventService.subscribeStrongly(String,EventTopicSubscriber)

subscribeStrongly

public boolean subscribeStrongly(java.util.regex.Pattern pat,
                                 EventTopicSubscriber eh)
Description copied from interface: EventService
Subscribes a subscriber to all the event topic names that match a RegEx expression.

The subscriber will remain subscribed until EventService.unsubscribe(String,EventTopicSubscriber) is called.

Specified by:
subscribeStrongly in interface EventService
Parameters:
pat - the name of the topic listened to
eh - The topic subscriber that will accept the events when published.
Returns:
true if the subscriber was subscribed sucessfully, false otherwise
See Also:
EventService.subscribeStrongly(Pattern,EventTopicSubscriber)

clearAllSubscribers

public void clearAllSubscribers()
Description copied from interface: EventService
Clears all current subscribers and veto subscribers

Specified by:
clearAllSubscribers in interface EventService
See Also:
EventService.clearAllSubscribers()

subscribeVetoListener

public boolean subscribeVetoListener(java.lang.Class eventClass,
                                     VetoEventListener vetoListener)
Description copied from interface: EventService
Subscribes a WeakReference to a VetoListener to a event class and its subclasses.

Use this method to avoid having to call unsubscribe(), though with care since garbage collection semantics is indeterminate. The service will respect the WeakReference semantics. In other words, if the vetoListener has not been garbage collected, then the onEvent will be called normally. If the hard reference has been garbage collected, the service will unsubscribe it's WeakReference.

It's allowable to call unsubscribe() with the same VetoListener hard reference to stop a subscription immediately.

The service will create the WeakReference on behalf of the caller.

Specified by:
subscribeVetoListener in interface EventService
Parameters:
eventClass - the class of published objects that can be vetoed
vetoListener - The vetoListener that can determine whether an event is published.
Returns:
true if the vetoListener was subscribed sucessfully, false otherwise
See Also:
EventService.subscribeVetoListener(Class,VetoEventListener)

subscribeVetoListenerExactly

public boolean subscribeVetoListenerExactly(java.lang.Class eventClass,
                                            VetoEventListener vetoListener)
Description copied from interface: EventService
Subscribes a WeakReference to a VetoListener to a event class (but not its subclasses).

Use this method to avoid having to call unsubscribe(), though with care since garbage collection semantics is indeterminate. The service will respect the WeakReference semantics. In other words, if the vetoListener has not been garbage collected, then the onEvent will be called normally. If the hard reference has been garbage collected, the service will unsubscribe it's WeakReference.

It's allowable to call unsubscribe() with the same VetoListener hard reference to stop a subscription immediately.

The service will create the WeakReference on behalf of the caller.

Specified by:
subscribeVetoListenerExactly in interface EventService
Parameters:
eventClass - the class of published objects that can be vetoed
vetoListener - The vetoListener that can determine whether an event is published.
Returns:
true if the vetoListener was subscribed sucessfully, false otherwise
See Also:
EventService.subscribeVetoListenerExactly(Class,VetoEventListener)

subscribeVetoListener

public boolean subscribeVetoListener(java.lang.String topic,
                                     VetoTopicEventListener vetoListener)
Description copied from interface: EventService
Subscribes a WeakReference to a VetoTopicEventListener to a topic name.

Specified by:
subscribeVetoListener in interface EventService
Parameters:
topic - the name of the topic listened to
vetoListener - The vetoListener that can determine whether an event is published.
Returns:
true if the vetoListener was subscribed sucessfully, false otherwise
See Also:
EventService.subscribeVetoListener(String,VetoTopicEventListener)

subscribeVetoListener

public boolean subscribeVetoListener(java.util.regex.Pattern topicPattern,
                                     VetoTopicEventListener vetoListener)
Description copied from interface: EventService
Subscribes a WeakReference to an VetoTopicEventListener to all the topic names that match the RegEx Pattern.

Specified by:
subscribeVetoListener in interface EventService
Parameters:
topicPattern - the RegEx pattern to match topics with
vetoListener - The vetoListener that can determine whether an event is published.
Returns:
true if the vetoListener was subscribed sucessfully, false otherwise
See Also:
EventService.subscribeVetoListener(Pattern,VetoTopicEventListener)

subscribeVetoListenerStrongly

public boolean subscribeVetoListenerStrongly(java.lang.Class eventClass,
                                             VetoEventListener vetoListener)
Description copied from interface: EventService
Subscribes a VetoListener for an event class and its subclasses.

The VetoListener will remain subscribed until EventService.unsubscribeVetoListener(Class,VetoEventListener) is called.

Specified by:
subscribeVetoListenerStrongly in interface EventService
Parameters:
eventClass - the class of published objects to listen to
vetoListener - The vetoListener that will accept the events when published.
Returns:
true if the vetoListener was subscribed sucessfully, false otherwise
See Also:
EventService.subscribeVetoListenerStrongly(Class,VetoEventListener)

subscribeVetoListenerExactlyStrongly

public boolean subscribeVetoListenerExactlyStrongly(java.lang.Class eventClass,
                                                    VetoEventListener vetoListener)
Description copied from interface: EventService
Subscribes a VetoListener for an event class (but not its subclasses).

The VetoListener will remain subscribed until EventService.unsubscribeVetoListener(Class,VetoEventListener) is called.

Specified by:
subscribeVetoListenerExactlyStrongly in interface EventService
Parameters:
eventClass - the class of published objects to listen to
vetoListener - The vetoListener that will accept the events when published.
Returns:
true if the vetoListener was subscribed sucessfully, false otherwise
See Also:
EventService.subscribeVetoListenerExactlyStrongly(Class,VetoEventListener)

subscribeVetoListenerStrongly

public boolean subscribeVetoListenerStrongly(java.lang.String topic,
                                             VetoTopicEventListener vetoListener)
Description copied from interface: EventService
Subscribes a VetoListener to a topic name.

The VetoListener will remain subscribed until EventService.unsubscribeVetoListener(String,VetoTopicEventListener) is called.

Specified by:
subscribeVetoListenerStrongly in interface EventService
Parameters:
topic - the name of the topic listened to
vetoListener - The topic vetoListener that will accept or reject publication.
Returns:
true if the vetoListener was subscribed sucessfully, false otherwise
See Also:
EventService.subscribeVetoListenerStrongly(String,VetoTopicEventListener)

subscribeVetoListenerStrongly

public boolean subscribeVetoListenerStrongly(java.util.regex.Pattern topicPattern,
                                             VetoTopicEventListener vetoListener)
Description copied from interface: EventService
Subscribes a VetoTopicEventListener to a set of topics that match a RegEx expression.

The VetoListener will remain subscribed until EventService.unsubscribeVetoListener(Pattern,VetoTopicEventListener) is called.

Specified by:
subscribeVetoListenerStrongly in interface EventService
Parameters:
topicPattern - the RegEx pattern that matches the name of the topics listened to
vetoListener - The topic vetoListener that will accept or reject publication.
Returns:
true if the vetoListener was subscribed sucessfully, false otherwise
See Also:
EventService.subscribeVetoListenerStrongly(Pattern,VetoTopicEventListener)

subscribeVetoListener

protected boolean subscribeVetoListener(java.lang.Object subscription,
                                        java.util.Map vetoListenerMap,
                                        java.lang.Object vetoListener)
All veto subscriptions methods call this method. Extending classes only have to override this method to subscribe all veto subscriptions.

Parameters:
o - the topic, Pattern, or event class to subsribe to
vetoListenerMap - the internal map of veto listeners to use (by topic of class)
vl - the veto listener to subscribe, may be a VetoEventListener or a WeakReference to one
Returns:
boolean if the veto listener is subscribed (was not subscribed).
Throws:
java.lang.IllegalArgumentException - if vl or o is null

subscribe

protected boolean subscribe(java.lang.Object topicOrClass,
                            java.util.Map subscriberMap,
                            java.lang.Object subscriber)
All subscribe methods call this method, including veto subscriptions. Extending classes only have to override this method to subscribe all subscriber subscriptions.

Overriding this method is only for the adventurous. This basically gives you just enough rope to hang yourself.

Parameters:
o - the topic String or event Class to subscribe to
subscriberMap - the internal map of subscribers to use (by topic or class)
subscriber - the EventSubscriber or EventTopicSubscriber to subscribe, or a WeakReference to either
Returns:
boolean if the subscriber is subscribed (was not subscribed).
Throws:
java.lang.IllegalArgumentException - if subscriber or topicOrClass is null

unsubscribe

public boolean unsubscribe(java.lang.Class cl,
                           EventSubscriber eh)
Description copied from interface: EventService
Stop the subscription for a subscriber that is subscribed to an event class and its subclasses.

Specified by:
unsubscribe in interface EventService
Parameters:
cl - the class of published objects to listen to
eh - The subscriber that is subscribed to the event. The same reference as that was subscribed.
Returns:
true if the subscriber was subscribed to the event, false if it wasn't
See Also:
EventService.unsubscribe(Class,EventSubscriber)

unsubscribeExactly

public boolean unsubscribeExactly(java.lang.Class cl,
                                  EventSubscriber eh)
Description copied from interface: EventService
Stop the subscription for a subscriber that is subscribed to an event class (and not its subclasses).

Specified by:
unsubscribeExactly in interface EventService
Parameters:
cl - the class of published objects to listen to
eh - The subscriber that is subscribed to the event. The same reference as that was subscribed.
Returns:
true if the subscriber was subscribed to the event, false if it wasn't
See Also:
EventService.unsubscribeExactly(Class,EventSubscriber)

unsubscribe

public boolean unsubscribe(java.lang.String name,
                           EventTopicSubscriber eh)
Description copied from interface: EventService
Stop the subscription for a subscriber that is subscribed to an event topic

Specified by:
unsubscribe in interface EventService
Parameters:
name - the topic listened to
eh - The subscriber that is subscribed to the topic. The same reference as that was subscribed.
Returns:
true if the subscriber was subscribed to the event, false if it wasn't
See Also:
EventService.unsubscribe(String,EventTopicSubscriber)

unsubscribe

public boolean unsubscribe(java.util.regex.Pattern topicPattern,
                           EventTopicSubscriber eh)
Description copied from interface: EventService
Stop the subscription for a subscriber that is subscribed to an event topic

Specified by:
unsubscribe in interface EventService
Parameters:
topicPattern - the regex expression matching topics listened to
eh - The subscriber that is subscribed to the topic. The same reference as that was subscribed.
Returns:
true if the subscriber was subscribed to the event, false if it wasn't
See Also:
EventService.unsubscribe(String,EventTopicSubscriber)

unsubscribe

public boolean unsubscribe(java.lang.Class eventClass,
                           java.lang.Object subcribedByProxy)
Description copied from interface: EventService
When using annotations, an object may be subscribed by proxy. This unsubscibe method will unsubscribe an object that is subscribed with a ProxySubscriber.

If an object is subscribed by proxy and it implements EventSubscriber, then the normal unsubscribe methods will still unsubscribe the object.

Specified by:
unsubscribe in interface EventService
Parameters:
eventClass - class this object is subscribed to by proxy
subcribedByProxy - object subscribed by proxy
See Also:
EventService.unsubscribe(Class,Object)

unsubscribeExactly

public boolean unsubscribeExactly(java.lang.Class eventClass,
                                  java.lang.Object subcribedByProxy)
Description copied from interface: EventService
When using annotations, an object may be subscribed by proxy. This unsubscibe method will unsubscribe an object that is subscribed with a ProxySubscriber.

If an object is subscribed by proxy and it implements EventSubscriber, then the normal unsubscribe methods will still unsubscribe the object.

Specified by:
unsubscribeExactly in interface EventService
Parameters:
eventClass - class this object is subscribed to by proxy
subcribedByProxy - object subscribed by proxy
See Also:
EventService.unsubscribeExactly(Class,Object)

unsubscribe

public boolean unsubscribe(java.lang.String topic,
                           java.lang.Object subcribedByProxy)
Description copied from interface: EventService
When using annotations, an object may be subscribed by proxy. This unsubscibe method will unsubscribe an object that is subscribed with a ProxySubscriber.

If an object is subscribed by proxy and it implements EventSubscriber, then the normal unsubscribe methods will still unsubscribe the object.

Specified by:
unsubscribe in interface EventService
Parameters:
topic - the topic this object is subscribed to by proxy
subcribedByProxy - object subscribed by proxy
See Also:
EventService.unsubscribe(String,Object)

unsubscribe

public boolean unsubscribe(java.util.regex.Pattern pattern,
                           java.lang.Object subcribedByProxy)
Description copied from interface: EventService
When using annotations, an object may be subscribed by proxy. This unsubscibe method will unsubscribe an object that is subscribed with a ProxySubscriber.

If an object is subscribed by proxy and it implements EventSubscriber, then the normal unsubscribe methods will still unsubscribe the object.

Specified by:
unsubscribe in interface EventService
Parameters:
pattern - the RegEx expression this object is subscribed to by proxy
subcribedByProxy - object subscribed by proxy
See Also:
EventService.unsubscribe(java.util.regex.Pattern,Object)

unsubscribe

protected boolean unsubscribe(java.lang.Object o,
                              java.util.Map subscriberMap,
                              java.lang.Object subscriber)
All event subscriber unsubscriptions call this method. Extending classes only have to override this method to subscribe all subscriber unsubscriptions.

Parameters:
o - the topic or event class to unsubsribe from
subscriberMap - the map of subscribers to use (by topic of class)
eh - the subscriber to unsubscribe, either an EventSubscriber or an EventTopicSubscriber, or a WeakReference to either
Returns:
boolean if the subscriber is unsubscribed (was subscribed).

unsubscribeVetoListener

public boolean unsubscribeVetoListener(java.lang.Class eventClass,
                                       VetoEventListener vetoListener)
Description copied from interface: EventService
Stop the subscription for a vetoListener that is subscribed to an event class and its subclasses.

Specified by:
unsubscribeVetoListener in interface EventService
Parameters:
eventClass - the class of published objects that can be vetoed
vetoListener - The vetoListener that will accept or reject publication of an event.
Returns:
true if the vetoListener was subscribed to the event, false if it wasn't
See Also:
EventService.unsubscribeVetoListener(Class,VetoEventListener)

unsubscribeVetoListenerExactly

public boolean unsubscribeVetoListenerExactly(java.lang.Class eventClass,
                                              VetoEventListener vetoListener)
Description copied from interface: EventService
Stop the subscription for a vetoListener that is subscribed to an event class (but not its subclasses).

Specified by:
unsubscribeVetoListenerExactly in interface EventService
Parameters:
eventClass - the class of published objects that can be vetoed
vetoListener - The vetoListener that will accept or reject publication of an event.
Returns:
true if the vetoListener was subscribed to the event, false if it wasn't
See Also:
EventService.unsubscribeVetoListenerExactly(Class,VetoEventListener)

unsubscribeVetoListener

public boolean unsubscribeVetoListener(java.lang.String topic,
                                       VetoTopicEventListener vetoListener)
Description copied from interface: EventService
Stop the subscription for a VetoTopicEventListener that is subscribed to an event topic name.

Specified by:
unsubscribeVetoListener in interface EventService
Parameters:
topic - the name of the topic that is listened to
vetoListener - The vetoListener that can determine whether an event is published on that topic
Returns:
true if the vetoListener was subscribed to the topic, false if it wasn't
See Also:
EventService.unsubscribeVetoListener(String,VetoTopicEventListener)

unsubscribeVetoListener

public boolean unsubscribeVetoListener(java.util.regex.Pattern topicPattern,
                                       VetoTopicEventListener vetoListener)
Description copied from interface: EventService
Stop the subscription for a VetoTopicEventListener that is subscribed to an event topic RegEx pattern.

Specified by:
unsubscribeVetoListener in interface EventService
Parameters:
topicPattern - the RegEx pattern matching the name of the topics listened to
vetoListener - The vetoListener that can determine whether an event is published on that topic
Returns:
true if the vetoListener was subscribed to the topicPattern, false if it wasn't
See Also:
EventService.unsubscribeVetoListener(Pattern,VetoTopicEventListener)

unsubscribeVetoListener

protected boolean unsubscribeVetoListener(java.lang.Object o,
                                          java.util.Map vetoListenerMap,
                                          java.lang.Object vl)
All veto unsubscriptions methods call this method. Extending classes only have to override this method to subscribe all veto unsubscriptions.

Parameters:
o - the topic or event class to unsubsribe from
vetoListenerMap - the map of veto listeners to use (by topic or class)
vl - the veto listener to unsubscribe, or a WeakReference to one
Returns:
boolean if the veto listener is unsubscribed (was subscribed).

publish

public void publish(java.lang.Object event)
Description copied from interface: EventService
Publishes an Object so that subscribers will be notified if they subscribed to the Object's class, one of its subclasses, or to one of its implementing interfaces.

Specified by:
publish in interface EventService
Parameters:
event - The event that occured
See Also:
EventService.publish(Object)

publish

public void publish(java.lang.reflect.Type genericType,
                    java.lang.Object event)
Description copied from interface: EventService
Use this method to publish generified objects to subscribers of Types, i.e. subscribers that use EventService.subscribe(Type, EventSubscriber), and to publish to subscribers to the non-generic type, i.e., those that use EventService.subscribe(Class, EventSubscriber) .

Due to generic type erasure, the type must be supplied by the caller. You can get a declared object's type by using the TypeReference class. For Example:

 TypeReference> subscribingTypeReference = new TypeReference>(){};
 EventBus.subscribe(subscribingTypeReference.getType(), mySubscriber);
 EventBus.subscribe(List.class, thisSubscriberWillGetCalledToo);
 ...
 //Likely in some other class
 TypeReference> publishingTypeReference = new TypeReference>(){};
 List trades = new ArrayList();
 EventBus.publish(publishingTypeReference.getType(), trades);
 trades.add(trade);
 EventBus.publish(publishingTypeReference.getType(), trades);
 

Specified by:
publish in interface EventService
Parameters:
genericType - the generified type of the event. Due to generic type erasure, this must be supplied.
event - The event that occured
See Also:
EventService.publish(java.lang.reflect.Type, Object)

publish

public void publish(java.lang.String topicName,
                    java.lang.Object eventObj)
Description copied from interface: EventService
Publishes an object on a topic name so that all subscribers to that name will be notified about it.

Specified by:
publish in interface EventService
Parameters:
topicName - The name of the topic subscribed to
eventObj - the object to publish
See Also:
EventService.publish(String,Object)

publish

protected void publish(java.lang.Object event,
                       java.lang.String topic,
                       java.lang.Object eventObj,
                       java.util.List subscribers,
                       java.util.List vetoSubscribers,
                       java.lang.StackTraceElement[] callingStack)
All publish methods call this method. Extending classes only have to override this method to handle all publishing cases.

Parameters:
event - the event to publish, null if publishing on a topic
topic - if publishing on a topic, the topic to publish on, else null
eventObj - if publishing on a topic, the eventObj to publish, else null
subscribers - the subscribers to publish to - must be a snapshot copy
vetoSubscribers - the veto subscribers to publish to - must be a snapshot copy.
Throws:
java.lang.IllegalArgumentException - if eh or o is null

addEventToCache

protected void addEventToCache(java.lang.Object event,
                               java.lang.String topic,
                               java.lang.Object eventObj)
Adds an event to the event cache, if appropriate. This method is called just before publication to listeners, after the event passes any veto listeners.

Using protected visibility to open the caching to other implementations.

Parameters:
event - the event about to be published, null if topic is non-null
topic - the topic about to be published to, null if the event is non-null
eventObj - the eventObj about to be published on a topic, null if the event is non-null

getSubscribers

public java.util.List getSubscribers(java.lang.Class eventClass)
Description copied from interface: EventService
Union of getSubscribersToClass(Class) and getSubscribersToExactClass(Class)

Specified by:
getSubscribers in interface EventService
Parameters:
eventClass - the eventClass of interest
Returns:
the subscribers that will be called when an event of eventClass is published, this includes those subscribed that match by exact class and those that match to a class and its subtypes
See Also:
EventService.getSubscribers(Class)

getSubscribersToClass

public java.util.List getSubscribersToClass(java.lang.Class eventClass)
Specified by:
getSubscribersToClass in interface EventService
Parameters:
eventClass - the eventClass of interest
Returns:
the subscribers that are subscribed to match to a class and its subtypes, but not those subscribed by exact class
See Also:
EventService.getSubscribersToClass(Class)

getSubscribersToExactClass

public java.util.List getSubscribersToExactClass(java.lang.Class eventClass)
Specified by:
getSubscribersToExactClass in interface EventService
Parameters:
eventClass - the eventClass of interest
Returns:
the subscribers that are subscribed by exact class but not those subscribed to match to a class and its subtypes
See Also:
EventService.getSubscribersToExactClass(Class)

getSubscribers

public java.util.List getSubscribers(java.lang.reflect.Type eventType)
See Also:
EventService.getSubscribers(Class)

getSubscribers

public java.util.List getSubscribers(java.lang.String topic)
Description copied from interface: EventService
Union of getSubscribersByPattern(String) and geSubscribersToTopic(String)

Specified by:
getSubscribers in interface EventService
Parameters:
topic - the topic of interest
Returns:
the subscribers that will be called when an event is published on the topic. This includes subscribers subsribed to match the exact topic name and those subscribed by a RegEx Pattern that matches the topic name.
See Also:
EventService.getSubscribers(String)

getSubscribersToTopic

public java.util.List getSubscribersToTopic(java.lang.String topic)
Specified by:
getSubscribersToTopic in interface EventService
Parameters:
topic - the topic of interest
Returns:
the subscribers that subscribed to the exact topic name.
See Also:
EventService.getSubscribers(Class)

getSubscribersByPattern

public java.util.List getSubscribersByPattern(java.lang.String topic)
Specified by:
getSubscribersByPattern in interface EventService
Parameters:
topic - the RegEx pattern for the topic of interest
Returns:
the subscribers that subscribed by a RegEx Pattern that matches the topic name.

getSubscribersToPattern

protected java.util.List getSubscribersToPattern(java.util.regex.Pattern topicPattern)

getVetoSubscribers

public java.util.List getVetoSubscribers(java.lang.Class eventClass)
Specified by:
getVetoSubscribers in interface EventService
Parameters:
eventClass - the eventClass of interest
Returns:
the veto subscribers that will be called when an event of eventClass or its subclasses is published.
See Also:
EventService.getVetoSubscribers(Class)

getVetoSubscribersToClass

public java.util.List getVetoSubscribersToClass(java.lang.Class eventClass)
Specified by:
getVetoSubscribersToClass in interface EventService
Parameters:
eventClass - the eventClass of interest
Returns:
the veto subscribers that are subscribed to the eventClass and its subclasses
See Also:
EventService.getVetoSubscribersToClass(Class)

getVetoSubscribersToExactClass

public java.util.List getVetoSubscribersToExactClass(java.lang.Class eventClass)
Specified by:
getVetoSubscribersToExactClass in interface EventService
Parameters:
eventClass - the eventClass of interest
Returns:
the veto subscribers that will be called when an event of eventClass (but not its subclasses) is published.

getVetoSubscribers

public java.util.List getVetoSubscribers(java.lang.String topic)
Specified by:
getVetoSubscribers in interface EventService
Parameters:
topic - the topic of interest
Returns:
the veto subscribers that will be called when an event is published on the topic.

getVetoSubscribers

public java.util.List getVetoSubscribers(java.util.regex.Pattern topicPattern)
Specified by:
getVetoSubscribers in interface EventService
Parameters:
topicPattern - the RegEx pattern for the topic of interest
Returns:
the veto subscribers that will be called when an event is published on the topic.

subscribeTiming

protected void subscribeTiming(SubscriberTimingEvent event)

handleVeto

protected void handleVeto(VetoEventListener vl,
                          java.lang.Object event,
                          VetoTopicEventListener vtl,
                          java.lang.String topic,
                          java.lang.Object eventObj)
Handle vetos of an event or topic, by default logs finely.

Parameters:
vl - the veto listener for an event
event - the event, can be null if topic is not
vtl - the veto listener for a topic
topic - can be null if event is not
eventObj - the object published with the topic

setDefaultCacheSizePerClassOrTopic

public void setDefaultCacheSizePerClassOrTopic(int defaultCacheSizePerClassOrTopic)
Sets the default cache size for each kind of event, default is 0 (no caching).

If this value is set to a positive number, then when an event is published, the EventService caches the event or topic payload data for later retrieval. This allows subscribers to find out what has most recently happened before they subscribed. The cached event(s) are returned from #getLastEvent(Class), #getLastTopicData(String), #getCachedEvents(Class), or #getCachedTopicData(String)

The default can be overridden on a by-event-class or by-topic basis.

Specified by:
setDefaultCacheSizePerClassOrTopic in interface EventService
Parameters:
defaultCacheSizePerClassOrTopic -

getDefaultCacheSizePerClassOrTopic

public int getDefaultCacheSizePerClassOrTopic()
Specified by:
getDefaultCacheSizePerClassOrTopic in interface EventService
Returns:
the default number of event payloads kept per event class or topic

setCacheSizeForEventClass

public void setCacheSizeForEventClass(java.lang.Class eventClass,
                                      int cacheSize)
Set the number of events cached for a particular class of event. By default, no events are cached.

This overrides any setting for the DefaultCacheSizePerClassOrTopic.

Class hierarchy semantics are respected. That is, if there are three events, A, X and Y, and X and Y are both derived from A, then setting the cache size for A applies the cache size for all three. Setting the cache size for X applies to X and leaves the settings for A and Y in tact. Intefaces can be passed to this method, but they only take effect if the cache size of a class or it's superclasses has been set. Just like Class.getInterfaces(), if multiple cache sizes are set, the interface names declared earliest in the implements clause of the eventClass takes effect.

The cache for an event is not adjusted until the next event of that class is published.

Specified by:
setCacheSizeForEventClass in interface EventService
Parameters:
eventClass - the class of event
cacheSize - the number of published events to cache for this event

getCacheSizeForEventClass

public int getCacheSizeForEventClass(java.lang.Class eventClass)
Returns the number of events cached for a particular class of event. By default, no events are cached.

This result is computed for a particular class from the values passed to #setCacheSizeForEventClass(Class, int), and respects the class hierarchy.

Specified by:
getCacheSizeForEventClass in interface EventService
Parameters:
eventClass - the class of event
Returns:
the maximum size of the event cache for the given event class
See Also:
setCacheSizeForEventClass(Class,int)

setCacheSizeForTopic

public void setCacheSizeForTopic(java.lang.String topicName,
                                 int cacheSize)
Set the number of published data objects cached for a particular event topic. By default, no caching is done.

This overrides any setting for the DefaultCacheSizePerClassOrTopic.

Settings for exact topic names take precedence over pattern matching.

The cache for a topic is not adjusted until the next publication on that topic.

Specified by:
setCacheSizeForTopic in interface EventService
Parameters:
topicName - the topic name
cacheSize - the number of published data Objects to cache for this topci

setCacheSizeForTopic

public void setCacheSizeForTopic(java.util.regex.Pattern pattern,
                                 int cacheSize)
Set the number of published data objects cached for topics matching a pattern. By default, caching is done.

This overrides any setting for the DefaultCacheSizePerClassOrTopic.

Settings for exact topic names take precedence over pattern matching. If a topic matches the cache settings for more than one pattern, the cache size chosen is an undetermined one from one of the matched pattern settings.

The cache for a topic is not adjusted until the next publication on that topic.

Specified by:
setCacheSizeForTopic in interface EventService
Parameters:
pattern - the pattern matching topic names
cacheSize - the number of data Objects to cache for this topci

getCacheSizeForTopic

public int getCacheSizeForTopic(java.lang.String topic)
Returns the number of cached data objects published on a particular topic. By default, no caching is performed.

This result is computed for a particular topic from the values passed to #setCacheSizeForTopic(String, int) and #setCacheSizeForTopic(Pattern, int).

Specified by:
getCacheSizeForTopic in interface EventService
Parameters:
topic - the topic name
Returns:
the maximum size of the data Object cache for the given topic
See Also:
setCacheSizeForTopic(String,int), setCacheSizeForTopic(java.util.regex.Pattern,int)

getLastEvent

public java.lang.Object getLastEvent(java.lang.Class eventClass)
Specified by:
getLastEvent in interface EventService
Parameters:
eventClass - an index into the cache, cannot be an inteface
Returns:
the last event published for this event class, or null if caching is turned off (the default)

getCachedEvents

public java.util.List getCachedEvents(java.lang.Class eventClass)
Specified by:
getCachedEvents in interface EventService
Parameters:
eventClass - an index into the cache, cannot be an inteface
Returns:
the last events published for this event class, or null if caching is turned off (the default)

getLastTopicData

public java.lang.Object getLastTopicData(java.lang.String topic)
Specified by:
getLastTopicData in interface EventService
Parameters:
topic - an index into the cache
Returns:
the last data Object published on this topic, or null if caching is turned off (the default)

getCachedTopicData

public java.util.List getCachedTopicData(java.lang.String topic)
Specified by:
getCachedTopicData in interface EventService
Parameters:
topic - an index into the cache
Returns:
the last data Objects published on this topic, or null if caching is turned off (the default)

clearCache

public void clearCache(java.lang.Class eventClassToClear)
Clears the event cache for a specific event class or interface and it's any of it's subclasses or implementing classes.

Specified by:
clearCache in interface EventService
Parameters:
eventClassToClear - the event class to clear the cache for

clearCache

public void clearCache(java.lang.String topic)
Clears the topic data cache for a specific topic name.

Specified by:
clearCache in interface EventService
Parameters:
topic - the topic name to clear the cache for

clearCache

public void clearCache(java.util.regex.Pattern pattern)
Clears the topic data cache for all topics that match a particular pattern.

Specified by:
clearCache in interface EventService
Parameters:
pattern - the pattern to match topic caches to

clearCache

public void clearCache()
Clear all event caches for all topics and event.

Specified by:
clearCache in interface EventService

subscribeVetoException

protected void subscribeVetoException(java.lang.Object event,
                                      java.lang.String topic,
                                      java.lang.Object eventObj,
                                      java.lang.Throwable e,
                                      java.lang.StackTraceElement[] callingStack,
                                      VetoEventListener vetoer)
Called during veto exceptions, calls handleException


onEventException

protected void onEventException(java.lang.String topic,
                                java.lang.Object eventObj,
                                java.lang.Throwable e,
                                java.lang.StackTraceElement[] callingStack,
                                EventTopicSubscriber eventTopicSubscriber)
Called during event handling exceptions, calls handleException


handleException

protected void handleException(java.lang.Object event,
                               java.lang.Throwable e,
                               java.lang.StackTraceElement[] callingStack,
                               EventSubscriber eventSubscriber)
Called during event handling exceptions, calls handleException


handleException

protected void handleException(java.lang.String action,
                               java.lang.Object event,
                               java.lang.String topic,
                               java.lang.Object eventObj,
                               java.lang.Throwable e,
                               java.lang.StackTraceElement[] callingStack,
                               java.lang.String sourceString)
All exception handling goes through this method. Logs a warning by default.


getRealSubscriberAndCleanStaleSubscriberIfNecessary

protected java.lang.Object getRealSubscriberAndCleanStaleSubscriberIfNecessary(java.util.Iterator iterator,
                                                                               java.lang.Object existingSubscriber)
Unsubscribe a subscriber if it is a stale ProxySubscriber. Used during subscribe() and in the cleanup Timer. See the class javadoc.

Not private since I don't claim I'm smart enough to anticipate all needs, but I am smart enough to doc the rules you must follow to override this method. Those rules may change (changes will be doc'ed), override at your own risk.

Overriders MUST call iterator.remove() to unsubscribe the proxy if the subscriber is a ProxySubscriper and is stale and should be cleaned up. If the ProxySubscriber is unsubscribed, then implementers MUST also call proxyUnsubscribed() on the subscriber. Overriders MUST also remove the proxy from the weakProxySubscriber list by calling removeStaleProxyFromList. Method assumes caller is holding the listenerList lock (else how can you pass the iterator?).

Parameters:
iterator - current iterator
existingSubscriber - the current value of the iterator
Returns:
the real value of the param, or the proxied subscriber of the param if the param is a a ProxySubscriber

removeProxySubscriber

protected void removeProxySubscriber(ProxySubscriber proxy,
                                     java.util.Iterator iter)

incWeakRefPlusProxySubscriberCount

protected void incWeakRefPlusProxySubscriberCount()
Increment the count of stale proxies and start a cleanup task if necessary


decWeakRefPlusProxySubscriberCount

protected void decWeakRefPlusProxySubscriberCount()
Decrement the count of stale proxies