|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 anEventService
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). EventTopicSubscriber
s 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.
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 |
---|
void publish(java.lang.Object event)
event
- The event that occuredvoid publish(java.lang.reflect.Type genericType, java.lang.Object event)
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);
genericType
- the generified type of the event. Due to generic type erasure, this must be supplied.event
- The event that occuredvoid publish(java.lang.String topic, java.lang.Object o)
topic
- The name of the topic subscribed too
- the object to publishboolean subscribe(java.lang.Class eventClass, EventSubscriber subscriber)
eventClass
- the class of published objects to listen tosubscriber
- The subscriber that will accept the events when published.
boolean subscribe(java.lang.reflect.Type type, EventSubscriber subscriber)
boolean subscribeExactly(java.lang.Class eventClass, EventSubscriber subscriber)
eventClass
- the class of published objects to listen tosubscriber
- The subscriber that will accept the events when published.
boolean subscribe(java.lang.String topic, EventTopicSubscriber subscriber)
topic
- the name of the topic listened tosubscriber
- The topic subscriber that will accept the events when published.
boolean subscribe(java.util.regex.Pattern topicPattern, EventTopicSubscriber subscriber)
topicPattern
- pattern that matches to the name of the topic published tosubscriber
- The topic subscriber that will accept the events when published.
boolean subscribeStrongly(java.lang.Class eventClass, EventSubscriber subscriber)
unsubscribe(Class,EventSubscriber)
is called.
eventClass
- the class of published objects to listen tosubscriber
- The subscriber that will accept the events when published.
boolean subscribeExactlyStrongly(java.lang.Class eventClass, EventSubscriber subscriber)
unsubscribe(Class,EventSubscriber)
is called.
eventClass
- the class of published objects to listen tosubscriber
- The subscriber that will accept the events when published.
boolean subscribeStrongly(java.lang.String topic, EventTopicSubscriber subscriber)
unsubscribe(String,EventTopicSubscriber)
is called.
topic
- the name of the topic listened tosubscriber
- The topic subscriber that will accept the events when published.
boolean subscribeStrongly(java.util.regex.Pattern topicPattern, EventTopicSubscriber subscriber)
unsubscribe(String,EventTopicSubscriber)
is called.
topicPattern
- the name of the topic listened tosubscriber
- The topic subscriber that will accept the events when published.
boolean unsubscribe(java.lang.Class eventClass, EventSubscriber subscriber)
eventClass
- the class of published objects to listen tosubscriber
- The subscriber that is subscribed to the event. The same reference as that was subscribed.
boolean unsubscribeExactly(java.lang.Class eventClass, EventSubscriber subscriber)
eventClass
- the class of published objects to listen tosubscriber
- The subscriber that is subscribed to the event. The same reference as that was subscribed.
boolean unsubscribe(java.lang.String topic, EventTopicSubscriber subscriber)
topic
- the topic listened tosubscriber
- The subscriber that is subscribed to the topic. The same reference as that was subscribed.
boolean unsubscribe(java.util.regex.Pattern topicPattern, EventTopicSubscriber subscriber)
topicPattern
- the regex expression matching topics listened tosubscriber
- The subscriber that is subscribed to the topic. The same reference as that was subscribed.
boolean subscribeVetoListener(java.lang.Class eventClass, VetoEventListener vetoListener)
eventClass
- the class of published objects that can be vetoedvetoListener
- The vetoListener that can determine whether an event is published.
boolean subscribeVetoListenerExactly(java.lang.Class eventClass, VetoEventListener vetoListener)
eventClass
- the class of published objects that can be vetoedvetoListener
- The vetoListener that can determine whether an event is published.
boolean subscribeVetoListener(java.lang.String topic, VetoTopicEventListener vetoListener)
topic
- the name of the topic listened tovetoListener
- The vetoListener that can determine whether an event is published.
boolean subscribeVetoListener(java.util.regex.Pattern topicPattern, VetoTopicEventListener vetoListener)
topicPattern
- the RegEx pattern to match topics withvetoListener
- The vetoListener that can determine whether an event is published.
boolean subscribeVetoListenerStrongly(java.lang.Class eventClass, VetoEventListener vetoListener)
unsubscribeVetoListener(Class,VetoEventListener)
is
called.
eventClass
- the class of published objects to listen tovetoListener
- The vetoListener that will accept the events when published.
boolean subscribeVetoListenerExactlyStrongly(java.lang.Class eventClass, VetoEventListener vetoListener)
unsubscribeVetoListener(Class,VetoEventListener)
is
called.
eventClass
- the class of published objects to listen tovetoListener
- The vetoListener that will accept the events when published.
boolean subscribeVetoListenerStrongly(java.lang.String topic, VetoTopicEventListener vetoListener)
unsubscribeVetoListener(String,VetoTopicEventListener)
is
called.
topic
- the name of the topic listened tovetoListener
- The topic vetoListener that will accept or reject publication.
subscribeVetoListenerStrongly(Class,VetoEventListener)
boolean subscribeVetoListenerStrongly(java.util.regex.Pattern topicPattern, VetoTopicEventListener vetoListener)
unsubscribeVetoListener(Pattern,VetoTopicEventListener)
is
called.
topicPattern
- the RegEx pattern that matches the name of the topics listened tovetoListener
- The topic vetoListener that will accept or reject publication.
subscribeVetoListenerStrongly(Pattern,VetoTopicEventListener)
boolean unsubscribeVetoListener(java.lang.Class eventClass, VetoEventListener vetoListener)
eventClass
- the class of published objects that can be vetoedvetoListener
- The vetoListener that will accept or reject publication of an event.
boolean unsubscribeVetoListenerExactly(java.lang.Class eventClass, VetoEventListener vetoListener)
eventClass
- the class of published objects that can be vetoedvetoListener
- The vetoListener that will accept or reject publication of an event.
boolean unsubscribeVetoListener(java.lang.String topic, VetoTopicEventListener vetoListener)
topic
- the name of the topic that is listened tovetoListener
- The vetoListener that can determine whether an event is published on that topic
boolean unsubscribeVetoListener(java.util.regex.Pattern topicPattern, VetoTopicEventListener vetoListener)
topicPattern
- the RegEx pattern matching the name of the topics listened tovetoListener
- The vetoListener that can determine whether an event is published on that topic
java.util.List getSubscribers(java.lang.Class eventClass)
eventClass
- the eventClass of interest
java.util.List getSubscribersToClass(java.lang.Class eventClass)
eventClass
- the eventClass of interest
java.util.List getSubscribersToExactClass(java.lang.Class eventClass)
eventClass
- the eventClass of interest
java.util.List getSubscribers(java.lang.String topic)
topic
- the topic of interest
java.util.List getSubscribersToTopic(java.lang.String topic)
topic
- the topic of interest
java.util.List getSubscribersByPattern(java.lang.String pattern)
pattern
- the RegEx pattern for the topic of interest
java.util.List getVetoSubscribers(java.lang.Class eventClass)
eventClass
- the eventClass of interest
java.util.List getVetoSubscribersToExactClass(java.lang.Class eventClass)
eventClass
- the eventClass of interest
java.util.List getVetoSubscribersToClass(java.lang.Class eventClass)
eventClass
- the eventClass of interest
java.util.List getVetoSubscribers(java.lang.String topic)
topic
- the topic of interest
java.util.List getVetoSubscribers(java.util.regex.Pattern pattern)
pattern
- the RegEx pattern for the topic of interest
void clearAllSubscribers()
void setDefaultCacheSizePerClassOrTopic(int defaultCacheSizePerClassOrTopic)
defaultCacheSizePerClassOrTopic
- int getDefaultCacheSizePerClassOrTopic()
void setCacheSizeForEventClass(java.lang.Class eventClass, int cacheSize)
eventClass
- the class of eventcacheSize
- the number of published events to cache for this eventint getCacheSizeForEventClass(java.lang.Class eventClass)
eventClass
- the class of event
setCacheSizeForEventClass(Class,int)
void setCacheSizeForTopic(java.lang.String topicName, int cacheSize)
topicName
- the topic namecacheSize
- the number of published data Objects to cache for this topcivoid setCacheSizeForTopic(java.util.regex.Pattern pattern, int cacheSize)
pattern
- the pattern matching topic namescacheSize
- the number of data Objects to cache for this topciint getCacheSizeForTopic(java.lang.String topic)
topic
- the topic name
setCacheSizeForTopic(String,int)
,
setCacheSizeForTopic(java.util.regex.Pattern,int)
java.lang.Object getLastEvent(java.lang.Class eventClass)
eventClass
- an index into the cache
java.util.List getCachedEvents(java.lang.Class eventClass)
eventClass
- an index into the cache
java.lang.Object getLastTopicData(java.lang.String topic)
topic
- an index into the cache
java.util.List getCachedTopicData(java.lang.String topic)
topic
- an index into the cache
void clearCache(java.lang.Class eventClass)
eventClass
- the event class to clear the cache forvoid clearCache(java.lang.String topic)
topic
- the topic name to clear the cache forvoid clearCache(java.util.regex.Pattern pattern)
pattern
- the pattern to match topic caches tovoid clearCache()
boolean unsubscribe(java.lang.Class eventClass, java.lang.Object subcribedByProxy)
eventClass
- class this object is subscribed to by proxysubcribedByProxy
- object subscribed by proxyboolean unsubscribeExactly(java.lang.Class eventClass, java.lang.Object subcribedByProxy)
eventClass
- class this object is subscribed to by proxysubcribedByProxy
- object subscribed by proxyboolean unsubscribe(java.lang.String topic, java.lang.Object subcribedByProxy)
topic
- the topic this object is subscribed to by proxysubcribedByProxy
- object subscribed by proxyboolean unsubscribe(java.util.regex.Pattern pattern, java.lang.Object subcribedByProxy)
pattern
- the RegEx expression this object is subscribed to by proxysubcribedByProxy
- object subscribed by proxy
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |