org.bushe.swing.event
Interface EventService

All Known Implementing Classes:
SwingEventService, ThreadSafeEventService

public interface EventService

The core interface. An EventService provides publish/subscribe services to a single JVM using Class-based and String-based (i.e. "topic") publications and subscriptions.

In the class-based pub/sub, Objects are published on an EventService and (@link EventSubscriber}s subscribe by providing a class or interface. Full class semantics are used, as expected. That is, if a subscriber subscribes to a class, the subscriber is notified if an object of that class is publish or if an object of a subclass of that class is published. Likewise if a subscriber subscribes to and interface, it will be notified if any object that implements that interface is published. Subscribers can subscribe "exactly" using subscribeExactly(Class, EventSubscriber) so that they are notified only if an object of the exact class is published (and will not be notified if subclasses are published, since this would not be "exact")

In topic-based pub/sub, a data Object is published on a topic name (String). EventTopicSubscribers subscribe to either the exact name of the topic or they may subscribe using a Regular Expression that is used to match topic names.

See package documentation for usage details and examples.

A single subscriber cannot subscribe more than once to an event or topic name. EventService implementations should handle double-subscription requests by returing false on subscribe(). A single EventSubscriber can subscribe to more than one event class, and a single EventTopicSubscriber can subscribe to more than one topic name or pattern. A single object may implement both EventSubscriber and EventTopicSubscriber interfaces. Subscribers are guaranteed to only be called for the classes and/or topic names they subscribe to. If a subscriber subscribes to a topic and to a regular expression that matches the topic name, this is considered two different subscriptions and the subscriber will be called twice for the publication on the topic. Similarly, if a subscriber subscribes to a class and its subclasses using subscribe() and again to a class of the same type using subscribeExactly(), this is considered two different subscriptions and the subscriber will be called twice for the publication for a single event of the exact type.

By default the EventService only holds WeakReferences to subscribers. If a subscriber has no references to it, then it can be garbage collected. This avoids memory leaks in exchange for the risk of accidently adding a listener and have it disappear unexpectedly. If you want to subscribe a subscriber that will have no other reference to it, then use one of the subscribeStrongly() methods, which will prevent garbage collection.

Unless garbage collected, EventSubscribers will remain subscribed until they are passed to one of the unsubscribe() methods with the event class or topic name to which there are subscribed.

Publication on a class or topic name can be vetoed by a VetoEventListener. All VetoEventListeners are checked before any EventSubscribers or EventTopicSubscribers are called. This is unlike the JavaBean's VetoPropertyEventListener which can leave side effects and half-propogated events. VetoEventListeners are subscribed in the same manner as EventSubscribers and EventTopicSubscribers.

Subscribers are called in the order in which they are subscribed by default (FIFO). This is also unlike Swing, where event listeners are called in the reverse order of when they were subscribed (FILO).

This simple example prints "Hello World"

 EventService eventService = new ThreadSafeEventService();
 //Create a subscriber
 EventTopicSubscriber subscriber = new EventTopicSubscriber() {
    public void onEvent(String topic, Object event) {
        System.out.println(topic+" "+event);
    }
 });
 eventService.subscribe("Hello", subscriber);
 eventService.publish("Hello", "World");
 System.out.println(subscriber + " Since the reference is used after it is subscribed, it doesn't get garbage
 collected,
 this is not necessary if you use subscribeStrongly()");
 

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).

There is nothing special about the term "Event," this could just as easily be called a "Message" Service, this term is already taken by the JMS, which is similar, but is used across processes and networks.

Author:
Michael Bushe michael@bushe.com
See Also:
for the default implementation, for the Swing-safe implementation, for simple access to the Swing-safe implementation, for subscription annotations, for subscription annotations

Method Summary
 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 eventClass)
          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.
 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.
 int getDefaultCacheSizePerClassOrTopic()
           
 java.lang.Object getLastEvent(java.lang.Class eventClass)
           
 java.lang.Object getLastTopicData(java.lang.String topic)
           
 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 getSubscribersByPattern(java.lang.String pattern)
           
 java.util.List getSubscribersToClass(java.lang.Class eventClass)
           
 java.util.List getSubscribersToExactClass(java.lang.Class eventClass)
           
 java.util.List getSubscribersToTopic(java.lang.String topic)
           
 java.util.List getVetoSubscribers(java.lang.Class eventClass)
           
 java.util.List getVetoSubscribers(java.util.regex.Pattern pattern)
           
 java.util.List getVetoSubscribers(java.lang.String topic)
           
 java.util.List getVetoSubscribersToClass(java.lang.Class eventClass)
           
 java.util.List getVetoSubscribersToExactClass(java.lang.Class eventClass)
           
 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.
 void publish(java.lang.String topic, java.lang.Object o)
          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.
 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 a 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 setDefaultCacheSizePerClassOrTopic(int defaultCacheSizePerClassOrTopic)
          Sets the default cache size for each kind of event, default is 0 (no caching).
 boolean subscribe(java.lang.Class eventClass, EventSubscriber subscriber)
          Subscribes a WeakReference to an EventSubscriber to the publication of events of an event class and its subclasses, or to an event's interface.
 boolean subscribe(java.util.regex.Pattern topicPattern, EventTopicSubscriber subscriber)
          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 subscriber)
          Subscribes a WeakReference to an EventSubscriber to the publication of a topic name.
 boolean subscribe(java.lang.reflect.Type type, EventSubscriber subscriber)
           
 boolean subscribeExactly(java.lang.Class eventClass, EventSubscriber subscriber)
          Subscribes a WeakReference to an EventSubscriber to the publication of events of an event class (not its subclasses).
 boolean subscribeExactlyStrongly(java.lang.Class eventClass, EventSubscriber subscriber)
          Subscribes a subscriber to an event class (and not its subclasses).
 boolean subscribeStrongly(java.lang.Class eventClass, EventSubscriber subscriber)
          Subscribes a subscriber to an event class and its subclasses.
 boolean subscribeStrongly(java.util.regex.Pattern topicPattern, EventTopicSubscriber subscriber)
          Subscribes a subscriber to all the event topic names that match a RegEx expression.
 boolean subscribeStrongly(java.lang.String topic, EventTopicSubscriber subscriber)
          Subscribes a subscriber to an event topic name.
 boolean subscribeVetoListener(java.lang.Class eventClass, VetoEventListener vetoListener)
          Subscribes a WeakReference to a VetoListener to a event class and its subclasses.
 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 eventClass, EventSubscriber subscriber)
          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.
 boolean unsubscribe(java.util.regex.Pattern topicPattern, EventTopicSubscriber subscriber)
          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 topic, EventTopicSubscriber subscriber)
          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 eventClass, EventSubscriber subscriber)
          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.
 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).
 

Method Detail

publish

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.

Parameters:
event - The event that occured

publish

void publish(java.lang.reflect.Type genericType,
             java.lang.Object event)
Use this method to publish generified objects to subscribers of Types, i.e. subscribers that use subscribe(Type, EventSubscriber), and to publish to subscribers to the non-generic type, i.e., those that use 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);
 

Parameters:
genericType - the generified type of the event. Due to generic type erasure, this must be supplied.
event - The event that occured

publish

void publish(java.lang.String topic,
             java.lang.Object o)
Publishes an object on a topic name so that all subscribers to that name will be notified about it.

Parameters:
topic - The name of the topic subscribed to
o - the object to publish

subscribe

boolean subscribe(java.lang.Class eventClass,
                  EventSubscriber subscriber)
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.

Parameters:
eventClass - the class of published objects to listen to
subscriber - The subscriber that will accept the events when published.
Returns:
true if the subscriber was subscribed sucessfully, false otherwise

subscribe

boolean subscribe(java.lang.reflect.Type type,
                  EventSubscriber subscriber)

subscribeExactly

boolean subscribeExactly(java.lang.Class eventClass,
                         EventSubscriber subscriber)
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.

Parameters:
eventClass - the class of published objects to listen to
subscriber - The subscriber that will accept the events when published.
Returns:
true if the subscriber was subscribed sucessfully, false otherwise

subscribe

boolean subscribe(java.lang.String topic,
                  EventTopicSubscriber subscriber)
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.

Parameters:
topic - the name of the topic listened to
subscriber - The topic subscriber that will accept the events when published.
Returns:
true if the subscriber was subscribed sucessfully, false otherwise

subscribe

boolean subscribe(java.util.regex.Pattern topicPattern,
                  EventTopicSubscriber subscriber)
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.

Parameters:
topicPattern - pattern that matches to the name of the topic published to
subscriber - The topic subscriber that will accept the events when published.
Returns:
true if the subscriber was subscribed sucessfully, false otherwise

subscribeStrongly

boolean subscribeStrongly(java.lang.Class eventClass,
                          EventSubscriber subscriber)
Subscribes a subscriber to an event class and its subclasses.

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

Parameters:
eventClass - the class of published objects to listen to
subscriber - The subscriber that will accept the events when published.
Returns:
true if the subscriber was subscribed sucessfully, false otherwise

subscribeExactlyStrongly

boolean subscribeExactlyStrongly(java.lang.Class eventClass,
                                 EventSubscriber subscriber)
Subscribes a subscriber to an event class (and not its subclasses).

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

Parameters:
eventClass - the class of published objects to listen to
subscriber - The subscriber that will accept the events when published.
Returns:
true if the subscriber was subscribed sucessfully, false otherwise

subscribeStrongly

boolean subscribeStrongly(java.lang.String topic,
                          EventTopicSubscriber subscriber)
Subscribes a subscriber to an event topic name.

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

Parameters:
topic - the name of the topic listened to
subscriber - The topic subscriber that will accept the events when published.
Returns:
true if the subscriber was subscribed sucessfully, false otherwise

subscribeStrongly

boolean subscribeStrongly(java.util.regex.Pattern topicPattern,
                          EventTopicSubscriber subscriber)
Subscribes a subscriber to all the event topic names that match a RegEx expression.

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

Parameters:
topicPattern - the name of the topic listened to
subscriber - The topic subscriber that will accept the events when published.
Returns:
true if the subscriber was subscribed sucessfully, false otherwise

unsubscribe

boolean unsubscribe(java.lang.Class eventClass,
                    EventSubscriber subscriber)
Stop the subscription for a subscriber that is subscribed to an event class and its subclasses.

Parameters:
eventClass - the class of published objects to listen to
subscriber - 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

unsubscribeExactly

boolean unsubscribeExactly(java.lang.Class eventClass,
                           EventSubscriber subscriber)
Stop the subscription for a subscriber that is subscribed to an event class (and not its subclasses).

Parameters:
eventClass - the class of published objects to listen to
subscriber - 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

unsubscribe

boolean unsubscribe(java.lang.String topic,
                    EventTopicSubscriber subscriber)
Stop the subscription for a subscriber that is subscribed to an event topic

Parameters:
topic - the topic listened to
subscriber - 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

unsubscribe

boolean unsubscribe(java.util.regex.Pattern topicPattern,
                    EventTopicSubscriber subscriber)
Stop the subscription for a subscriber that is subscribed to an event topic

Parameters:
topicPattern - the regex expression matching topics listened to
subscriber - 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

subscribeVetoListener

boolean subscribeVetoListener(java.lang.Class eventClass,
                              VetoEventListener vetoListener)
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.

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

subscribeVetoListenerExactly

boolean subscribeVetoListenerExactly(java.lang.Class eventClass,
                                     VetoEventListener vetoListener)
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.

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

subscribeVetoListener

boolean subscribeVetoListener(java.lang.String topic,
                              VetoTopicEventListener vetoListener)
Subscribes a WeakReference to a VetoTopicEventListener to a topic name.

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

subscribeVetoListener

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.

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

subscribeVetoListenerStrongly

boolean subscribeVetoListenerStrongly(java.lang.Class eventClass,
                                      VetoEventListener vetoListener)
Subscribes a VetoListener for an event class and its subclasses.

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

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

subscribeVetoListenerExactlyStrongly

boolean subscribeVetoListenerExactlyStrongly(java.lang.Class eventClass,
                                             VetoEventListener vetoListener)
Subscribes a VetoListener for an event class (but not its subclasses).

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

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

subscribeVetoListenerStrongly

boolean subscribeVetoListenerStrongly(java.lang.String topic,
                                      VetoTopicEventListener vetoListener)
Subscribes a VetoListener to a topic name.

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

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:
subscribeVetoListenerStrongly(Class,VetoEventListener)

subscribeVetoListenerStrongly

boolean subscribeVetoListenerStrongly(java.util.regex.Pattern topicPattern,
                                      VetoTopicEventListener vetoListener)
Subscribes a VetoTopicEventListener to a set of topics that match a RegEx expression.

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

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:
subscribeVetoListenerStrongly(Pattern,VetoTopicEventListener)

unsubscribeVetoListener

boolean unsubscribeVetoListener(java.lang.Class eventClass,
                                VetoEventListener vetoListener)
Stop the subscription for a vetoListener that is subscribed to an event class and its subclasses.

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

unsubscribeVetoListenerExactly

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).

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

unsubscribeVetoListener

boolean unsubscribeVetoListener(java.lang.String topic,
                                VetoTopicEventListener vetoListener)
Stop the subscription for a VetoTopicEventListener that is subscribed to an event topic name.

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

unsubscribeVetoListener

boolean unsubscribeVetoListener(java.util.regex.Pattern topicPattern,
                                VetoTopicEventListener vetoListener)
Stop the subscription for a VetoTopicEventListener that is subscribed to an event topic RegEx pattern.

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

getSubscribers

java.util.List getSubscribers(java.lang.Class eventClass)
Union of getSubscribersToClass(Class) and getSubscribersToExactClass(Class)

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

getSubscribersToClass

java.util.List getSubscribersToClass(java.lang.Class eventClass)
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

getSubscribersToExactClass

java.util.List getSubscribersToExactClass(java.lang.Class eventClass)
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

getSubscribers

java.util.List getSubscribers(java.lang.String topic)
Union of getSubscribersByPattern(String) and geSubscribersToTopic(String)

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.

getSubscribersToTopic

java.util.List getSubscribersToTopic(java.lang.String topic)
Parameters:
topic - the topic of interest
Returns:
the subscribers that subscribed to the exact topic name.

getSubscribersByPattern

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

getVetoSubscribers

java.util.List getVetoSubscribers(java.lang.Class eventClass)
Parameters:
eventClass - the eventClass of interest
Returns:
the veto subscribers that will be called when an event of eventClass or its subclasses is published.

getVetoSubscribersToExactClass

java.util.List getVetoSubscribersToExactClass(java.lang.Class eventClass)
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.

getVetoSubscribersToClass

java.util.List getVetoSubscribersToClass(java.lang.Class eventClass)
Parameters:
eventClass - the eventClass of interest
Returns:
the veto subscribers that are subscribed to the eventClass and its subclasses

getVetoSubscribers

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

getVetoSubscribers

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

clearAllSubscribers

void clearAllSubscribers()
Clears all current subscribers and veto subscribers


setDefaultCacheSizePerClassOrTopic

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.

Parameters:
defaultCacheSizePerClassOrTopic -

getDefaultCacheSizePerClassOrTopic

int getDefaultCacheSizePerClassOrTopic()
Returns:
the default number of event payloads kept per event class or topic

setCacheSizeForEventClass

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.

Parameters:
eventClass - the class of event
cacheSize - the number of published events to cache for this event

getCacheSizeForEventClass

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.

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

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

This overrides any setting for the DefaultCacheSizePerClassOrTopic.

Exact topic names take precedence over pattern matching.

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

Parameters:
topicName - the topic name
cacheSize - the number of published data Objects to cache for this topci

setCacheSizeForTopic

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

This overrides any setting for the DefaultCacheSizePerClassOrTopic.

Exact topic names take precedence over pattern matching.

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

Parameters:
pattern - the pattern matching topic names
cacheSize - the number of data Objects to cache for this topci

getCacheSizeForTopic

int getCacheSizeForTopic(java.lang.String topic)
Returns the number of cached data objects published on a particular topic.

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

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

java.lang.Object getLastEvent(java.lang.Class eventClass)
Parameters:
eventClass - an index into the cache
Returns:
the last event published for this event class, or null if caching is turned off (the default)

getCachedEvents

java.util.List getCachedEvents(java.lang.Class eventClass)
Parameters:
eventClass - an index into the cache
Returns:
the last events published for this event class, or null if caching is turned off (the default)

getLastTopicData

java.lang.Object getLastTopicData(java.lang.String topic)
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

java.util.List getCachedTopicData(java.lang.String topic)
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

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

Parameters:
eventClass - the event class to clear the cache for

clearCache

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

Parameters:
topic - the topic name to clear the cache for

clearCache

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

Parameters:
pattern - the pattern to match topic caches to

clearCache

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


unsubscribe

boolean unsubscribe(java.lang.Class eventClass,
                    java.lang.Object subcribedByProxy)
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.

Parameters:
eventClass - class this object is subscribed to by proxy
subcribedByProxy - object subscribed by proxy

unsubscribeExactly

boolean unsubscribeExactly(java.lang.Class eventClass,
                           java.lang.Object subcribedByProxy)
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.

Parameters:
eventClass - class this object is subscribed to by proxy
subcribedByProxy - object subscribed by proxy

unsubscribe

boolean unsubscribe(java.lang.String topic,
                    java.lang.Object subcribedByProxy)
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.

Parameters:
topic - the topic this object is subscribed to by proxy
subcribedByProxy - object subscribed by proxy

unsubscribe

boolean unsubscribe(java.util.regex.Pattern pattern,
                    java.lang.Object subcribedByProxy)
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.

Parameters:
pattern - the RegEx expression this object is subscribed to by proxy
subcribedByProxy - object subscribed by proxy