EventSource (IBM WebSphere Application Server, Release 8.5)

All Known Subinterfaces:

AlarmManager, AsynchScope, AsynchScopeManager, SubsystemMonitor, WorkManager
```
public interface EventSource
```
Runtime objects implement this when they are an event source Java objects can be registered with an EventSource. The listeners are called when we broadcast events or the fireEvent method is called. The listeners are called using the j2ee context of the code which registered the listener.
An EventSource, itself, can generate events. The events that are internally published by an EventSource are documented in the EventSourceEvents interface. The listener object should implement the required Event interfaces and add an instance of this object using the EventSource.addListener method.
Applications can create listeners that implement one or more interfaces. These listener objects can be registered with an EventSource. These listeners will receive events fired on any interface that the listener implements. Events are fired by using a proxy returned by the getEventTrigger method. This returns a proxy for a particular event interface. Any interface can be used as an event interface. Invoking a method on the proxy fires the event. Any listener that implements this interface will have the corresponding method on it-self invoked with the same parameters as those used by the proxy caller. When the event method returns a value, the value returned to the firer of the event is the value returned by the first listener invoked. All other return values are discarded.
The listeners called by an EventSource should not throw exceptions. If an listener method does throw an exception then it is 'swallowed' and hidden from the event publisher, i.e. the publisher will never see an exception. The publisher may need to surround invoking proxy methods with a try catch block because of the event method signatures but none of the these exceptions will be thrown in practise. However, these exceptions can be detected by an application if a listener that implements EventSourceEvents is registered with the EventSource. The EventSourceEvents.listenerThrewException event is fired when a listener throws an exception.
At most once semantics are used for event delivery. If the server fails during this time then no events may be delivered and on restart any pending events are lost.
An EventSource and any associated EventTrigger proxies are thread safe and can be called from multiple threads. No event order guarantees are provided when multiple threads use the same EventSource or any proxies associated with a single EventSource. If event sequence is important in these circumstances then the application must provide its own sequencing mechanism. If an EventSource and its associated EventTrigger proxies are used by a single thread at a time then event order is guaranteed.
Listeners have their methods invoked synchronously on the same thread as the publisher. Therefore, care needs to be taken with synchronization blocks. If the publisher has acquired a monitor on an object then if listeners are called on the same thread then they will also be able to acquire a monitor on that lock because it is the same thread. If the application wants the listeners to be called on a different thread then the application should start a Work that fires the event.
While EventSources and proxies can be shared between threads this doesn't mean your listeners are thread safe automatically. Listener implementations need to make themselves thread safe using synchronization techniques if this is important to the application. Alternatively, an application could synchronize on the EventSource instance and fire the event inside that synchronized block.
The order listeners are fired can be ordered by specifying an listener sequence number when calling addListener. If the sequence number is not specified then it defaults to 5. Valid sequence numbers are integers from 0..9. Listeners are invoked in ascending order, 0 first and 9 last.

See Also:
EventSourceEvents

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`APPLICATION_NOTIFICATION_EVENT_SOURCE` This can be used to lookup the EAR wide EventSource for an application.
`static int`	`MAX_LISTENER_SEQUENCE_VALUE` This is the highest permissibile listener sequence number .
`static int`	`MIN_LISTENER_SEQUENCE_VALUE` This is the lowest permissibile listener sequence number .

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addListener(java.lang.Object listener)` This adds a new listener to the event source.
`void`	`addListener(java.lang.Object listener, int orderSequenceNumber)` This adds a new listener to the event source.
`java.lang.Object`	`getEventTrigger(java.lang.Class listenerInterface)` This returns an event proxy.
`java.lang.Object`	`getEventTrigger(java.lang.Class listenerInterface, boolean sameTransaction)` This returns an event proxy.
`void`	`removeListener(java.lang.Object listener)` This removes a listener from the event source.

- Field Detail
  - APPLICATION_NOTIFICATION_EVENT_SOURCE
```
static final java.lang.String APPLICATION_NOTIFICATION_EVENT_SOURCE
```
    This can be used to lookup the EAR wide EventSource for an application. This fires an event to all locally registered listeners, i.e. within this JVM. Just use
```
 InitialContext ic = new InitialContext();
 EventSource jvmAppES = (EventSource)ic.lookup(EventSource.APPLICATION_NOTIFICATION_EVENT_SOURCE);
 
```
    See Also:
    Constant Field Values
  - MAX_LISTENER_SEQUENCE_VALUE
```
static final int MAX_LISTENER_SEQUENCE_VALUE
```
    This is the highest permissibile listener sequence number . Listeners with this sequence number are called LAST.
    
    See Also:
    Constant Field Values
  - MIN_LISTENER_SEQUENCE_VALUE
```
static final int MIN_LISTENER_SEQUENCE_VALUE
```
    This is the lowest permissibile listener sequence number . Listeners with this sequence are called FIRST.
    
    See Also:
    Constant Field Values
- Method Detail
  - addListener
```
void addListener(java.lang.Object listener)
                 throws java.lang.IllegalArgumentException
```
    This adds a new listener to the event source. It will receives events only for those interfaces that it implements. The default order sequence number is to 5
    
    Parameters:
    listener - The listener to be added.
    
    Throws:
    
    java.lang.IllegalArgumentException - This can be thrown if the async bean is an EnterpriseBean.
  - addListener
```
void addListener(java.lang.Object listener,
               int orderSequenceNumber)
                 throws java.lang.IllegalArgumentException
```
    This adds a new listener to the event source. It will receives events only for those interfaces that it implements. The listener is assign the specified sequence number
    Sequence numbers outside the range 0..9 will result in an IllegalArgumentException. Listeners are called in ascending order, 0 first and 9 last.
    
    Parameters:
    listener - The listener to be added.
    orderSequenceNumber - The sequence number associated with the listener, 0..9
    
    Throws:
    
    java.lang.IllegalArgumentException - This can be thrown if the async bean is an EnterpriseBean.
  - removeListener
```
void removeListener(java.lang.Object listener)
```
    This removes a listener from the event source. If it was not already registered then this call is ignored.
    
    Parameters:
    listener - The listener to be removed.
  - getEventTrigger
```
java.lang.Object getEventTrigger(java.lang.Class listenerInterface)
```
    This returns an event proxy. When a method on this proxy is called then the event source iterates over all listeners, the listeners which implement the listenerInterface interface have the same method invoked with the same arguments. The J2EE context from the registerer of the listener is used. Each listener gets an independent transaction.
    If the method called on the proxy returns a value then it should be discarded, the return value is random. Event methods should not have return values.
    If the EventSource is remote then all parameters and return type of the methods on listenerInterface must be serializable or an IllegalArgumentException will be thrown. The only scenario where this is relevant in when sending events to a Work that is serializable.
    Here is a code snippet showing a typical usage pattern.
```
 EventSource es = ...;
 
 EventSourceEvents eventProxy = (EventSourceEvents)es.getEventTrigger(EventSourceEvents.class);
 
 eventProxy.listenerCountChanged(es, 0, 1);
 
```
    Here we find the EventSource to publish on, get an EventTrigger proxy for the event interface and then invoke one or more methods on the proxy. Each time a method is invoked on the proxy, the event method is fired.
    Parameters:
    listenerInterface - This is the type which the returned proxy emulates. The event will only be fired on listeners which implement this interface.
    See Also:
    Work
  - getEventTrigger
```
java.lang.Object getEventTrigger(java.lang.Class listenerInterface,
                               boolean sameTransaction)
```
    This returns an event proxy. When a method on this proxy is called then the event source iterates over all listeners, the listeners which implement the listenerInterface interface have the same method invoked with the same arguments. The J2EE context from the registerer of the listener is used. If the sameTransaction parameter is true then all listeners share the transaction context of the event firer otherwise each listener gets an independent transaction.
    If the method called on the proxy returns a value then it should be discarded, the return value is random. Event methods should not have return values.
    If a listener wants to rollback a transaction then if the component which created it was a BMT then the JNDI userTransaction can be used otherwise a sessionbean must be used and it's EJBContext.setRollback method called.
    If the EventSource is a remoteable one, i.e. a serializable work then sameTransaction must be false or else an IllegalArgumentException is thrown. In this case, all method parameters and return types must also be serializable or else an IllegalArgumentException is thrown.
    
    Parameters:
    listenerInterface - This is the type which the returned proxy emulates. The event will only be fired on listeners which implement this interface.
    sameTransaction - If true then all listeners will share the transaction if any of the event firer. Otherwise, each listener gets it's own transaction.

APPLICATION_NOTIFICATION_EVENT_SOURCE

MAX_LISTENER_SEQUENCE_VALUE

MIN_LISTENER_SEQUENCE_VALUE

addListener

addListener

removeListener

getEventTrigger

getEventTrigger