com.ibm.di.api
Class EventNotifier

java.lang.Object
  extended by com.ibm.di.api.EventNotifier

public class EventNotifier
extends Object

This class implements event broadcasting for the use of the Server API. Events are dispatched to registered event listeners. When a listener is being registered, event filters are specified, so that the listener receives only events of interest. Events are filtered based on their type and their id.

An atomic filter is a string, that does not contain whitespaces, newlines, commas and semi-colons. If an atomic filter ends with '*', it matches all texts, whose prefix is the same as the filter up to the '*' symbol. For example a "di.al.*" filter matches both "di.al.start" and "di.al.stop". A composite filter is a string that contains atomic filters, separated by whitespaces. (Note that an atomic filter is a valid composite filter.) A composite filter matches a piece of text, if any of its atomic filters matches the text. An empty string is considered to be a match-none filter. null is considered a match-all filter.

Two modes of operation are supported - synchronous and asynchronous. In synchronous mode, the 'broadcastEvent' method completes only after all matching listeners have handled the event. In asynchronous mode, there is no such guarantee.


Field Summary
static String MATCH_ALL_FILTER
          A filter that matches all events.
static String MATCH_NONE_FILTER
          A filter that matches no events.
 
Constructor Summary
EventNotifier(boolean sync, String suppressedEventTypesStr)
          Create a new notifier object with an empty set of event listeners.
 
Method Summary
 void addEventListener(DIEventListener listener, String typeFiltersStr, String idFilter)
          Register a new event listener accompanied with event filters.
 void broadcastEvent(DIEvent event)
          Broadcast an event to all registered listeners, whose filters match the event.
 boolean removeEventListener(DIEventListener listener)
          Unregisters an event listener.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MATCH_ALL_FILTER

public static final String MATCH_ALL_FILTER
A filter that matches all events.


MATCH_NONE_FILTER

public static final String MATCH_NONE_FILTER
A filter that matches no events.

See Also:
Constant Field Values
Constructor Detail

EventNotifier

public EventNotifier(boolean sync,
                     String suppressedEventTypesStr)
Create a new notifier object with an empty set of event listeners.

Parameters:
sync - whether the notifier will operate in synchronous mode
suppressedEventTypesStr - a list of filters for event types that will be suppressed by the notifier; suppressed events will not be propagated by the notifier events will not be propagated to listeners
Method Detail

addEventListener

public void addEventListener(DIEventListener listener,
                             String typeFiltersStr,
                             String idFilter)
                      throws DIException
Register a new event listener accompanied with event filters. The method accepts a filter that matches event type and a filter that matches event id. Both the type filter and the id filter must match an event if the listener is to receive it. If, for example, the type filter matches an event, but the id filter does not, the event will not be passed to the listener. If the listener object is already registered, the method will ignore the request.

Parameters:
listener - an event listener
typeFiltersStr - a composite filter that matches event type
idFilter - an atomic filter that matches event id
Throws:
DIException - if the listener is null

removeEventListener

public boolean removeEventListener(DIEventListener listener)
Unregisters an event listener. After unregistering, the listener will no longer receive events from the notifier.

Parameters:
listener - an event listener
Returns:
whether the listener was unregistered successfully

broadcastEvent

public void broadcastEvent(DIEvent event)
Broadcast an event to all registered listeners, whose filters match the event. If the event's type is suppressed, the method will ignore the event. If the notifier operates in synchronous mode, the method returns only after all listeners have handled the event.

Parameters:
event - an event