org.obe.spi.service
Interface ApplicationEventBroker

All Superinterfaces:
WorkflowService

public interface ApplicationEventBroker
extends WorkflowService

Provides access to temporal events and external events originating in third party applications.

The workflow engine subscribes to events by specifying the event type, an optional set of event keys, an optional predicate, and a set of correlation keys. The combination of event type, event keys and predicate are used to discriminate the precise event instance to which the engine is subscribing. The correlation keys encapsulate the workflow context and typically contain between one and four strings: processDefinitionId, processInstanceId, activityInstanceId and transitionId. All elements of the array must be non-null.

This somewhat complex scheme is intended to enhance performance, since in a production system the alternative of evaluating large numbers of simple expressions would not perform well. The event type definitions and the expressions used to compute the key values from the inbound event data are registered in the event broker.

When unsubscribing, all existing subscriptions which match the array of correlation keys are cancelled, even if it contains fewer elements than the existing subscription. This enables a process instance, for example, to cancel all outstanding subscriptions in one call by passing just the processDefinitionId and processInstanceId.

Author:
Adrian Price
See Also:
ApplicationEvent, ApplicationEventListener

Nested Class Summary
static interface ApplicationEventBroker.ApplicationEventSubscription
          Describes a subscription to an application event.
static interface ApplicationEventBroker.EventSubscription
          Describes an event subscription.
static interface ApplicationEventBroker.TemporalEventSubscription
          Describes a subscription to one or more temporal events.
 
Field Summary
static java.lang.String SERVICE_NAME
           
 
Method Summary
 void addApplicationEventListener(ApplicationEventListener listener)
          Adds an application event listener.
 void createEventType(EventTypeMetaData eventType)
          Registers an application event type.
 void deleteEventType(java.lang.String eventType)
          Unregisters an application event type.
 EventTypeMetaData[] findEventTypeMetaData()
          Finds meta-data for all application event types.
 EventTypeMetaData findEventTypeMetaData(java.lang.String eventId)
          Finds meta-data for a specific application event type.
 void fireApplicationEvent(ApplicationEvent event, java.lang.String[] correlationKeys)
          Notifies listeners of an event which matches the specified correlation keys.
 void publish(ApplicationEvent event)
          Injects an application event for matching.
 void publish(java.lang.Object source, java.util.Map attrs)
          Injects an application event for matching.
 void removeApplicationEventListener(ApplicationEventListener listener)
          Removes an application event listener.
 ApplicationEventBroker.TemporalEventSubscription subscribe(java.lang.String eventType, java.util.Date effective, java.util.Date expiry, int count, Duration interval, java.lang.String calendar, boolean recoverable, java.lang.String[] correlationKeys)
          Subscribes to a series of timed events.
 ApplicationEventBroker.TemporalEventSubscription subscribe(java.lang.String eventType, java.util.Date effective, java.lang.String[] correlationKeys)
          Subscribes to a single timed event.
 ApplicationEventBroker.ApplicationEventSubscription subscribe(java.lang.String eventType, java.lang.Object[] eventKeys, java.lang.String predicate, java.util.Date effective, java.util.Date expiry, int count, java.lang.String[] correlationKeys, WorkflowContext ctx)
          Subscribes to an application event.
 boolean supportsKeyBasedSubscriptions()
          Whether this event broker implementation supports key-based subscriptions.
 void unsubscribe(java.lang.String[] correlationKeys, boolean exact)
          Cancels matching subscriptions.
 void updateEventType(EventTypeMetaData eventType)
          Updates an application event type.
 
Methods inherited from interface org.obe.spi.WorkflowService
exit, getServiceManager, getServiceName, init
 

Field Detail

SERVICE_NAME

public static final java.lang.String SERVICE_NAME
See Also:
Constant Field Values
Method Detail

createEventType

public void createEventType(EventTypeMetaData eventType)
                     throws RepositoryException
Registers an application event type.

Parameters:
eventType - The application event type definition.
Throws:
ObjectAlreadyExistsException - if the event type is already registered.
RepositoryException - if the application event type could not be registered for some other reason.

deleteEventType

public void deleteEventType(java.lang.String eventType)
                     throws RepositoryException
Unregisters an application event type.

Parameters:
eventType - The application event name.
Throws:
ObjectNotFoundException - if the application event name is not registered.
RepositoryException - if the application event type could not be unregistered for some other reason.

updateEventType

public void updateEventType(EventTypeMetaData eventType)
                     throws RepositoryException
Updates an application event type.

Parameters:
eventType - The application event type definition.
Throws:
ObjectNotFoundException - if the application event name is not registered.
RepositoryException - if the application event type could not be updated for some other reason.

findEventTypeMetaData

public EventTypeMetaData[] findEventTypeMetaData()
                                          throws RepositoryException
Finds meta-data for all application event types. This method is intended to support design-time clients and management applications.

Returns:
The list of all application event types.
Throws:
RepositoryException - if an error occurred.

findEventTypeMetaData

public EventTypeMetaData findEventTypeMetaData(java.lang.String eventId)
                                        throws RepositoryException
Finds meta-data for a specific application event type.

Parameters:
eventId - The application event ID.
Returns:
Meta-data for the event type.
Throws:
RepositoryException

addApplicationEventListener

public void addApplicationEventListener(ApplicationEventListener listener)
Adds an application event listener. The event listener will be notified of all events for which a matching subscription has been registered.

Parameters:
listener - The listener.
See Also:
subscribe(java.lang.String, java.lang.Object[], java.lang.String, java.util.Date, java.util.Date, int, java.lang.String[], org.obe.spi.WorkflowContext), removeApplicationEventListener(org.obe.spi.event.ApplicationEventListener)

removeApplicationEventListener

public void removeApplicationEventListener(ApplicationEventListener listener)
Removes an application event listener. The event listener will no longer be notified of events, matching or otherwise.

Parameters:
listener - The listener.
See Also:
addApplicationEventListener(org.obe.spi.event.ApplicationEventListener)

fireApplicationEvent

public void fireApplicationEvent(ApplicationEvent event,
                                 java.lang.String[] correlationKeys)
Notifies listeners of an event which matches the specified correlation keys. This method is present solely to support custom event broker implementations. It should not be called by client code.

Parameters:
event - The matching event.
correlationKeys - The correlation keys from the matched subscription.
See Also:
AsyncFireApplicationEvent

publish

public void publish(java.lang.Object source,
                    java.util.Map attrs)
             throws RepositoryException,
                    EvaluatorException
Injects an application event for matching. This overload of the publish method provides a loosely coupled integration mechanism that imposes minimal requirements on the source application.

Matching subscriptions which do not specify an expiry date are cancelled when they have been fulfilled.

If contentType is not specified, the method infers it from the event data by calling @link #process(Object). Similarly, if schema is not specified, the method infers it from the event data. For a contentType of text/xml, the schema is of the form {<namespace>}<tag-name>, where <namespace> is either the PublicId or SystemId of a DTD if specified, or the namespace URI of the document element. If no <namespace> is present, the schema is simply <tag-name>. For a contentType of application/x-java-object, the schema is the fully qualified Java class name.

Parameters:
source - The source object which raised the event.
attrs - Additional metadata about the event data.
Throws:
RepositoryException
EvaluatorException
See Also:
publish(ApplicationEvent)

publish

public void publish(ApplicationEvent event)
             throws RepositoryException,
                    EvaluatorException
Injects an application event for matching. This overload of the publish method provides a tightly coupled integration mechanism that imposes certain requirements on the source application.

Matching subscriptions which do not specify an expiry date are cancelled when they have been fulfilled.

Parameters:
event - The application event.
Throws:
RepositoryException
EvaluatorException
See Also:
publish(Object,Map)

supportsKeyBasedSubscriptions

public boolean supportsKeyBasedSubscriptions()
Whether this event broker implementation supports key-based subscriptions.

Returns:
true if it does.

subscribe

public ApplicationEventBroker.ApplicationEventSubscription subscribe(java.lang.String eventType,
                                                                     java.lang.Object[] eventKeys,
                                                                     java.lang.String predicate,
                                                                     java.util.Date effective,
                                                                     java.util.Date expiry,
                                                                     int count,
                                                                     java.lang.String[] correlationKeys,
                                                                     WorkflowContext ctx)
                                                              throws RepositoryException
Subscribes to an application event. The event broker uses the specified event type, keys and predicate to match a particular event occurrence to the subscription.

The matching events and the correlation keys from the subscription are delivered to the external event listener that was registered in a prior call to addApplicationEventListener.

Parameters:
eventType - The name of the event type. Must be registered with the event broker.
eventKeys - The keys required to identify the particular event occurrence of interest. The keys act as a coarse grained filter that can be efficiently compared with the corresponding keys on an inbound event. Can be null, but beware the potential performance impact if predicate is not null, because the event broker would have to evaluate all such conditions for every occurrence of eventType.
predicate - An additional qualifying condition required to identify the particular event occurrence of interest. The predicate is evaluated against the inbound ApplicationEvent.
effective - The date/time at which the subscription becomes effective. Can be null, in which case the subscription becomes effective immediately.
expiry - The date/time at which the subscription expires. Can be null, in which case the subscription never expires.
count - The number of such events to deliver. The subscription automatically expires when the countth event has been delivered or when expiry elapses, whichever occurs sooner. Constraint: count == -1 || count >= 1.
correlationKeys - Contextual information that will be passed to the event listener when the event occurs. Typically contains unique keys for various workflow entities.
ctx - Workflow execution context.
Returns:
The event subscription.
Throws:
RepositoryException - if the subscription could not be created.
See Also:
addApplicationEventListener(org.obe.spi.event.ApplicationEventListener), unsubscribe(java.lang.String[], boolean)

subscribe

public ApplicationEventBroker.TemporalEventSubscription subscribe(java.lang.String eventType,
                                                                  java.util.Date effective,
                                                                  java.lang.String[] correlationKeys)
                                                           throws RepositoryException
Subscribes to a single timed event. The event broker schedules the delivery of an event of the specified type using the correlation keys supplied. Such subscriptions are always recoverable.

The matching event and the correlation keys from the subscription is delivered to the external event listener that was registered in a prior call to addApplicationEventListener.

Parameters:
eventType - The name of the event type.
effective - The date/time at which to deliver the event.
correlationKeys - Contextual information that will be passed to the event listener when the event occurs. Typically contains unique keys for various workflow entities.
Returns:
The event subscription.
Throws:
RepositoryException - if the subscription could not be created.
See Also:
subscribe(String,Date,Date,int,Duration,String,boolean,String[]), unsubscribe(java.lang.String[], boolean), addApplicationEventListener(org.obe.spi.event.ApplicationEventListener)

subscribe

public ApplicationEventBroker.TemporalEventSubscription subscribe(java.lang.String eventType,
                                                                  java.util.Date effective,
                                                                  java.util.Date expiry,
                                                                  int count,
                                                                  Duration interval,
                                                                  java.lang.String calendar,
                                                                  boolean recoverable,
                                                                  java.lang.String[] correlationKeys)
                                                           throws RepositoryException
Subscribes to a series of timed events. The event broker schedules the delivery of a series of up to count events of the specified eventType. The subscription expires when that number of events has been delivered or at the specified expiry date, whichever is sooner. The delivery time for the next event in the series is computed against the specified calendar by adding interval to the previous effective date.

The matching events and the correlation keys from the subscription are delivered to the external event listener that was registered in a prior call to addApplicationEventListener.

Parameters:
eventType - The name of the event type.
effective - The date/time at which to deliver the first event.
expiry - The date/time at which the subscription expires. Can be null.
count - The number of such events to deliver. The subscription automatically expires when the countth event has been delivered or when expiry elapses, whichever occurs sooner. Constraint: count == -1 || count >= 1.
interval - The interval between events in the series.
calendar - The name of the BusinessCalendar to use when performing temporal computations. Can be null.
recoverable - true if the temporal events are recoverable (i.e., must still be processed even if they occurred while the server was down).
correlationKeys - Contextual information that will be passed to the event listener when the event occurs. Typically contains unique keys for various workflow entities.
Returns:
The event subscription.
Throws:
RepositoryException - if the subscription could not be created.
See Also:
subscribe(String, Date, String[]), unsubscribe(java.lang.String[], boolean), addApplicationEventListener(org.obe.spi.event.ApplicationEventListener)

unsubscribe

public void unsubscribe(java.lang.String[] correlationKeys,
                        boolean exact)
                 throws RepositoryException
Cancels matching subscriptions. The subscriptions must have been established by a prior call to subscribe(java.lang.String, java.lang.Object[], java.lang.String, java.util.Date, java.util.Date, int, java.lang.String[], org.obe.spi.WorkflowContext).

Parameters:
correlationKeys - Keys identifying the subscriptions to cancel.
exact - true to cancel only those subscriptions whose correlationKeys match exactly in number and value. false permits all subscriptions within a particular scope to be cancelled. For example, {x,y} would match {x,y}, {x,y,z1} ... {x,y,zN} etc. inexactly, but would only match {x,y} exactly.
Throws:
RepositoryException - if the subscriptions could not be removed.
See Also:
subscribe(String,Object[],String,Date,Date,int,String[],WorkflowContext), subscribe(String, Date, String[]), subscribe(String, Date, Date, int, Duration, String, boolean, String[])


SourceForge.net Logo OBE-1.0 Copyright (c) 2002-2006 Adrian Price. All Rights Reserved.