com.northconcepts.datapipeline.eventbus

Class EventBus

java.lang.Object

com.northconcepts.datapipeline.eventbus.EventBus

public class EventBus
extends Object

An asynchronous, in-memory, event delivery service. When used with EventBusReader and EventBusWriter, the bus allows pipelines to be loosely coupled and used in one-to-many (publish-subscribe) scenarios.

See Also:

EventBusReader, EventBusWriter

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	EventBus.State

Field Summary

Fields

Modifier and Type	Field and Description
static Logger	log

Constructor Summary

Constructors

Constructor and Description
EventBus() Creates a bus using a single thread to deliver events.
EventBus(ExecutorService executorService) Creates a bus using the specified ExecutorService to deliver events to listeners.

Method Summary

Modifier and Type	Method and Description
static void	addEventBusLifecycleListener(EventBusLifecycleListener listener)
EventBus	addExceptionListener(EventFilter filter, ExceptionListener listener)
EventBus	addExceptionListener(ExceptionListener listener)
<T> EventBus	addListener(Class<T> eventListenerClass, EventFilter filter, T listener)
<T> EventBus	addListener(Class<T> eventListenerClass, EventFilter filter, T listener, Object topic)
<T> EventBus	addListener(Class<T> eventListenerClass, T listener)
EventBus	addListener(EventFilter filter, UntypedEventListener listener) Deprecated. Use addUntypedEventListener(EventFilter, UntypedEventListener) instead.
EventBus	addListener(EventFilter filter, UntypedEventListener listener, Object topic) Deprecated. Use addUntypedEventListener(EventFilter, UntypedEventListener, Object) instead.
EventBus	addListener(UntypedEventListener listener) Deprecated. Use addUntypedEventListener(UntypedEventListener) instead.
EventBus	addShutdownListener(EventFilter filter, ShutdownListener listener)
EventBus	addUntypedEventListener(EventFilter filter, UntypedEventListener listener)
EventBus	addUntypedEventListener(EventFilter filter, UntypedEventListener listener, Object topic)
EventBus	addUntypedEventListener(UntypedEventListener listener)
void	assertAlive() Asserts that this endpoint has started reading or writing, otherwise an exception is thrown.
protected void	cleanupGarbage()
protected Object	clone()
protected <T> void	deliverEvent(Event<T> event)
protected void	finalize()
static List<EventBus>	getAll()
long	getCompletedTaskCount() Returns the approximate total number of tasks that have completed execution by this bus' executorService or -1 if unknown.
long	getCorePoolSize() Returns the core number of threads in this bus' executorService or -1 if unknown.
Date	getCreatedOn() The time this job instance was created.
static Event<?>	getCurrentEvent() Returns the event currently being delivered on this thread.
long	getErrorCount() Returns the number of exceptions this bus has experienced.
long	getEventsActive() Returns the approximate number of threads that are actively delivering events using this bus' executorService or -1 if unknown.
long	getEventsDelivered() Returns the combined number of events each listener on this event bus has received (typically getEventsPublished() * getListenerCount()).
long	getEventsPublished() Returns the number of events sent to this event bus for delivery to listeners.
long	getEventsQueued() Returns the number of events waiting to be executed by this bus' executorService or -1 if unknown.
long	getId() Returns the unique (sequential) ID of this event bus (within this JVM/classloader).
long	getLargestPoolSize() Returns the largest number of threads that have ever simultaneously been in the pool in this bus' executorService or -1 if unknown.
int	getListenerCount() Returns the total number of listeners subscribed to this bus.
long	getMaximumPoolSize() Returns the maximum allowed number of threads in this bus' executorService or -1 if unknown.
String	getName() Returns the name assigned to this bus or its default name if one was not assigned.
long	getPoolSize() Returns the current number of threads in this bus' executorService pool or -1 if unknown.
<T> T	getPublisher(Class<T> eventListenerClass)
<T> T	getPublisher(Object eventSource, Class<T> eventListenerClass)
<T> T	getPublisher(Object eventSource, Class<T> eventListenerClass, Object topic)
long	getPublishersCreated() Returns the number of event publishers created by this bus.
long	getShutdownTimeout() Returns the time in milliseconds this bus will wait for events to complete before forcibly shutting down (defaults to 30 seconds).
String	getShutdownTimeoutAsString() Returns time as human readable string this bus will wait for events to complete before forcibly shutting down (defaults to 30 seconds).
EventBus.State	getState() Returns the current state of this bus.
static EventBus	getSystemEventBus()
long	getTaskCount() Returns the approximate total number of tasks that have ever been scheduled for execution by this bus' executorService or -1 if unknown.
int	getTypedListenerCount() Returns the number of type-specific listeners subscribed to this bus.
protected <T> TypedListenerList<T>	getTypedListenerList(Class<T> eventListenerClass)
int	getUntypedEventListenerCount() Returns the number of non-type-specific listeners subscribed to this bus.
int	getUntypedListenerCount() Deprecated. Use getUntypedEventListenerCount() instead.
UUID	getUuid() Returns the universally unique identifier (UUID) for this job.
protected void	handleException(Event<?> event, Object listener, Throwable e)
protected long	incEventsDelivered()
boolean	isAlive() Returns true if this bus has not been shutdown.
boolean	isDebug() Indicates if the bus should emit debug log messages when events are published or delivered and during the shutdown process.
boolean	isNotAlive() Returns true if this bus has been shutdown or is in the process of shutting down.
boolean	isPublishLifecycleEvents() Indicates if the bus should publish its own EventBusLifecycleListener and ShutdownListener events (defaults to true).
boolean	isUseStrongListenerReference() Indicates if the event bus uses strong references (default) or soft references for holding listeners added to the bus.
protected <T> void	publishEvent(Event<T> event)
static void	removeEventBusLifecycleListener(EventBusLifecycleListener listener)
EventBus	removeExceptionListener(ExceptionListener listener)
<T> EventBus	removeListener(Class<T> eventListenerClass, T listener)
EventBus	removeListener(Object listener)
EventBus	removeListener(UntypedEventListener listener) Deprecated. Use removeUntypedEventListener(UntypedEventListener) instead.
<T> EventBus	removeListenersByTopic(Class<T> eventListenerClass, Object topic)
EventBus	removeShutdownListener(ShutdownListener listener)
protected EventBus	removeTypedListenerReference(Reference<?> reference)
EventBus	removeUntypedEventListener(UntypedEventListener listener)
protected EventBus	removeUntypedEventListenerReference(Reference<?> reference)
EventBus	removeUntypedEventListenersByTopic(Object topic)
protected EventBus	removeUntypedListenerReference(Reference<?> reference) Deprecated. Use removeUntypedEventListenerReference(Reference) instead.
EventBus	setDebug(boolean debug) Indicates if the bus should emit debug log messages when events are published or delivered and during the shutdown process.
EventBus	setName(String name) Assigns a new name to this bus.
EventBus	setPublishLifecycleEvents(boolean publishLifecycleEvents) Indicates if the bus should publish its own EventBusLifecycleListener and ShutdownListener events (defaults to true).
EventBus	setShutdownTimeout(long shutdownTimeout) Sets the time in milliseconds this bus will wait for events to complete before forcibly shutting down (defaults to 30 seconds).
EventBus	setUseStrongListenerReference(boolean useStrongListenerReference) Indicates if the event bus uses strong references (default) or soft references for holding listeners added to the bus.
void	shutdown()

Methods inherited from class java.lang.Object

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

Field Detail

log

public static final Logger log

Constructor Detail

EventBus

public EventBus(ExecutorService executorService)

Creates a bus using the specified ExecutorService to deliver events to listeners.

EventBus

public EventBus()

Creates a bus using a single thread to deliver events. This configuration allows the bus to deliver events sequentially to listeners, in the order they were published, while not blocking the publisher.

Method Detail

getAll

public static List<EventBus> getAll()

getSystemEventBus

public static EventBus getSystemEventBus()

addEventBusLifecycleListener

public static void addEventBusLifecycleListener(EventBusLifecycleListener listener)

removeEventBusLifecycleListener

public static void removeEventBusLifecycleListener(EventBusLifecycleListener listener)

getCurrentEvent

public static Event<?> getCurrentEvent()

Returns the event currently being delivered on this thread.

getId

public long getId()

Returns the unique (sequential) ID of this event bus (within this JVM/classloader).

getUuid

public UUID getUuid()

Returns the universally unique identifier (UUID) for this job.

getName

public String getName()

Returns the name assigned to this bus or its default name if one was not assigned.

setName

public EventBus setName(String name)

Assigns a new name to this bus.

getState

public EventBus.State getState()

Returns the current state of this bus.

isAlive

public boolean isAlive()

Returns true if this bus has not been shutdown. This is equivalent to getState() == EventBus.State.ALIVE

isNotAlive

public boolean isNotAlive()

Returns true if this bus has been shutdown or is in the process of shutting down. This is equivalent to getState() != EventBus.State.ALIVE

assertAlive

public void assertAlive()

Asserts that this endpoint has started reading or writing, otherwise an exception is thrown.

getCreatedOn

public Date getCreatedOn()

The time this job instance was created.

isDebug

public boolean isDebug()

Indicates if the bus should emit debug log messages when events are published or delivered and during the shutdown process.

setDebug

public EventBus setDebug(boolean debug)

Indicates if the bus should emit debug log messages when events are published or delivered and during the shutdown process.

getShutdownTimeout

public long getShutdownTimeout()

Returns the time in milliseconds this bus will wait for events to complete before forcibly shutting down (defaults to 30 seconds).

getShutdownTimeoutAsString

public String getShutdownTimeoutAsString()

Returns time as human readable string this bus will wait for events to complete before forcibly shutting down (defaults to 30 seconds).

isPublishLifecycleEvents

public boolean isPublishLifecycleEvents()

Indicates if the bus should publish its own EventBusLifecycleListener and ShutdownListener events (defaults to true).

setPublishLifecycleEvents

public EventBus setPublishLifecycleEvents(boolean publishLifecycleEvents)

Indicates if the bus should publish its own EventBusLifecycleListener and ShutdownListener events (defaults to true).

setShutdownTimeout

public EventBus setShutdownTimeout(long shutdownTimeout)

Sets the time in milliseconds this bus will wait for events to complete before forcibly shutting down (defaults to 30 seconds).

isUseStrongListenerReference

public boolean isUseStrongListenerReference()

Indicates if the event bus uses strong references (default) or soft references for holding listeners added to the bus. Soft references are automatically garbage collected when the JVM runs out of memory in an effort to free up resources.

setUseStrongListenerReference

public EventBus setUseStrongListenerReference(boolean useStrongListenerReference)

Indicates if the event bus uses strong references (default) or soft references for holding listeners added to the bus. Soft references are automatically garbage collected when the JVM runs out of memory in an effort to free up resources.

getPublishersCreated

public long getPublishersCreated()

Returns the number of event publishers created by this bus.

getEventsPublished

public long getEventsPublished()

Returns the number of events sent to this event bus for delivery to listeners.

getEventsDelivered

public long getEventsDelivered()

Returns the combined number of events each listener on this event bus has received (typically getEventsPublished() * getListenerCount()).

incEventsDelivered

protected long incEventsDelivered()

getEventsActive

public long getEventsActive()

Returns the approximate number of threads that are actively delivering events using this bus' executorService or -1 if unknown.

getEventsQueued

public long getEventsQueued()

Returns the number of events waiting to be executed by this bus' executorService or -1 if unknown.

getTaskCount

public long getTaskCount()

Returns the approximate total number of tasks that have ever been scheduled for execution by this bus' executorService or -1 if unknown.

getCompletedTaskCount

public long getCompletedTaskCount()

Returns the approximate total number of tasks that have completed execution by this bus' executorService or -1 if unknown.

getCorePoolSize

public long getCorePoolSize()

Returns the core number of threads in this bus' executorService or -1 if unknown.

getLargestPoolSize

public long getLargestPoolSize()

Returns the largest number of threads that have ever simultaneously been in the pool in this bus' executorService or -1 if unknown.

getMaximumPoolSize

public long getMaximumPoolSize()

Returns the maximum allowed number of threads in this bus' executorService or -1 if unknown.

getPoolSize

public long getPoolSize()

Returns the current number of threads in this bus' executorService pool or -1 if unknown.

getErrorCount

public long getErrorCount()

Returns the number of exceptions this bus has experienced.

addExceptionListener

public EventBus addExceptionListener(ExceptionListener listener)

addExceptionListener

public EventBus addExceptionListener(EventFilter filter,
                                     ExceptionListener listener)

removeExceptionListener

public EventBus removeExceptionListener(ExceptionListener listener)

addShutdownListener

public EventBus addShutdownListener(EventFilter filter,
                                    ShutdownListener listener)

removeShutdownListener

public EventBus removeShutdownListener(ShutdownListener listener)

getTypedListenerList

protected <T> TypedListenerList<T> getTypedListenerList(Class<T> eventListenerClass)

addListener

public <T> EventBus addListener(Class<T> eventListenerClass,
                                T listener)

addListener

public <T> EventBus addListener(Class<T> eventListenerClass,
                                EventFilter filter,
                                T listener)

addListener

public <T> EventBus addListener(Class<T> eventListenerClass,
                                EventFilter filter,
                                T listener,
                                Object topic)

removeListener

public <T> EventBus removeListener(Class<T> eventListenerClass,
                                   T listener)

removeListenersByTopic

public <T> EventBus removeListenersByTopic(Class<T> eventListenerClass,
                                           Object topic)

removeListener

public EventBus removeListener(Object listener)

removeTypedListenerReference

protected EventBus removeTypedListenerReference(Reference<?> reference)

getTypedListenerCount

public int getTypedListenerCount()

Returns the number of type-specific listeners subscribed to this bus.

addListener

@Deprecated
public EventBus addListener(UntypedEventListener listener)

Deprecated. Use addUntypedEventListener(UntypedEventListener) instead.

Returns:

addUntypedEventListener

public EventBus addUntypedEventListener(UntypedEventListener listener)

addListener

@Deprecated
public EventBus addListener(EventFilter filter,
                                         UntypedEventListener listener)

Deprecated. Use addUntypedEventListener(EventFilter, UntypedEventListener) instead.

addUntypedEventListener

public EventBus addUntypedEventListener(EventFilter filter,
                                        UntypedEventListener listener)

addListener

@Deprecated
public EventBus addListener(EventFilter filter,
                                         UntypedEventListener listener,
                                         Object topic)

Deprecated. Use addUntypedEventListener(EventFilter, UntypedEventListener, Object) instead.

addUntypedEventListener

public EventBus addUntypedEventListener(EventFilter filter,
                                        UntypedEventListener listener,
                                        Object topic)

removeListener

@Deprecated
public EventBus removeListener(UntypedEventListener listener)

Deprecated. Use removeUntypedEventListener(UntypedEventListener) instead.

removeUntypedEventListener

public EventBus removeUntypedEventListener(UntypedEventListener listener)

removeUntypedEventListenersByTopic

public EventBus removeUntypedEventListenersByTopic(Object topic)

removeUntypedListenerReference

@Deprecated
protected EventBus removeUntypedListenerReference(Reference<?> reference)

Deprecated. Use removeUntypedEventListenerReference(Reference) instead.

removeUntypedEventListenerReference

protected EventBus removeUntypedEventListenerReference(Reference<?> reference)

getUntypedListenerCount

@Deprecated
public int getUntypedListenerCount()

Deprecated. Use getUntypedEventListenerCount() instead.

Returns the number of non-type-specific listeners subscribed to this bus.

getUntypedEventListenerCount

public int getUntypedEventListenerCount()

Returns the number of non-type-specific listeners subscribed to this bus.

getListenerCount

public int getListenerCount()

Returns the total number of listeners subscribed to this bus.

getPublisher

public <T> T getPublisher(Class<T> eventListenerClass)

getPublisher

public <T> T getPublisher(Object eventSource,
                          Class<T> eventListenerClass)

getPublisher

public <T> T getPublisher(Object eventSource,
                          Class<T> eventListenerClass,
                          Object topic)

publishEvent

protected <T> void publishEvent(Event<T> event)

deliverEvent

protected <T> void deliverEvent(Event<T> event)
                         throws Throwable

Throws:

Throwable

cleanupGarbage

protected void cleanupGarbage()

handleException

protected void handleException(Event<?> event,
                               Object listener,
                               Throwable e)

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable

shutdown

public void shutdown()
              throws InterruptedException

Throws:

InterruptedException

clone

protected Object clone()
                throws CloneNotSupportedException

Overrides:

clone in class Object

Throws:

CloneNotSupportedException