org.apache.cayenne.event
Class EventBridge

java.lang.Object
  extended by org.apache.cayenne.event.EventBridge
All Implemented Interfaces:
java.util.EventListener
Direct Known Subclasses:
JavaGroupsBridge, JMSBridge, XMPPBridge

public abstract class EventBridge
extends java.lang.Object
implements java.util.EventListener

An object that passes events between a local EventManager and some other event dispatch mechanism. The most common example is sending local events to remote JVMs and receiving remote events dispatched by those VMs. EventBridge makes possible to connect a network of regular EventManagers in a single "virtual" distributed EventManager.

EventBridge encapsulates a transport agreed upon by all paries (such as JMS) and maintains an array of "local" subjects to communicate with local EventManager, and a single "remote" subject - to use for "external" communications that are transport-specific.

Subclasses that require special setup to listen for external events should implement startupExternal() method accordingly.

This class is an example of "bridge" design pattern, hence the name.

Since:
1.1
Author:
Andrus Adamchik

Field Summary
protected  EventManager eventManager
           
protected  java.lang.Object externalEventSource
           
protected  java.lang.String externalSubject
           
protected  java.util.Collection localSubjects
           
protected  int mode
           
static int RECEIVE_EXTERNAL
           
static int RECEIVE_LOCAL
           
static int RECEIVE_LOCAL_EXTERNAL
           
static java.lang.String VM_ID
          Deprecated. unused since 1.2
static java.lang.String VM_ID_PROPERRTY
          Deprecated. unused since 1.2
 
Constructor Summary
EventBridge(java.util.Collection localSubjects, java.lang.String externalSubject)
          Creates an EventBridge with multiple local subjects and a single external subject.
EventBridge(EventSubject localSubject, java.lang.String externalSubject)
          Creates an EventBridge with a single local subject.
 
Method Summary
static java.lang.String convertToExternalSubject(EventSubject localSubject)
          A utility method that performs consistent translation from an EventSubject to a String that can be used by external transport as subject for distributed communications.
 EventManager getEventManager()
          Returns local EventManager used by the bridge.
 java.lang.Object getExternalEventSource()
          Returns an object used as a source of local events posted in response to remote events.
 java.lang.String getExternalSubject()
          Returns a String subject used to post distributed events.
 EventSubject getLocalSubject()
          Deprecated. since 1.2 EventBridge supports multiple local subjects, so use 'getLocalSubjects()' instead. This method returns the first subject from the subject array for backwards compatibility.
 java.util.Collection getLocalSubjects()
          Returns a Collection of local EventSubjects.
 boolean isRunning()
          Returns true if this bridge is active.
protected  void onExternalEvent(CayenneEvent event)
          Helper method intended to be called explicitly by subclasses to asynchronously post an event obtained from a remote source.
 void onLocalEvent(CayenneEvent event)
          Deprecated. Unused since 1.2, as event dispatch is done via internal listeners.
 boolean receivesExternalEvents()
          Returns true if the bridge is configured to receive external events.
 boolean receivesLocalEvents()
          Returns true if the bridge is configured to receive local events from its internal EventManager.
protected abstract  void sendExternalEvent(CayenneEvent localEvent)
          Sends a Cayenne event over the transport supported by this bridge.
 void shutdown()
          Stops listening for events on both local and external interfaces.
protected abstract  void shutdownExternal()
          Shuts down the external interface of the EventBridge, cleaning up and releasing any resources used to communicate external events.
 void startup(EventManager eventManager, int mode)
          Starts EventBridge in the specified mode and locally listening to all event sources that post on a preconfigured subject.
 void startup(EventManager eventManager, int mode, java.lang.Object localEventSource)
          Starts EventBridge in the specified mode and locally listening to a specified event source.
 void startup(EventManager eventManager, int mode, java.lang.Object localEventSource, java.lang.Object remoteEventSource)
          Starts EventBridge in the specified mode.
protected abstract  void startupExternal()
          Starts an external interface of the EventBridge.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VM_ID

public static final java.lang.String VM_ID
Deprecated. unused since 1.2

VM_ID_PROPERRTY

public static final java.lang.String VM_ID_PROPERRTY
Deprecated. unused since 1.2
See Also:
Constant Field Values

RECEIVE_LOCAL

public static final int RECEIVE_LOCAL
See Also:
Constant Field Values

RECEIVE_EXTERNAL

public static final int RECEIVE_EXTERNAL
See Also:
Constant Field Values

RECEIVE_LOCAL_EXTERNAL

public static final int RECEIVE_LOCAL_EXTERNAL
See Also:
Constant Field Values

externalSubject

protected java.lang.String externalSubject

localSubjects

protected java.util.Collection localSubjects

eventManager

protected EventManager eventManager

mode

protected int mode

externalEventSource

protected java.lang.Object externalEventSource
Constructor Detail

EventBridge

public EventBridge(EventSubject localSubject,
                   java.lang.String externalSubject)
Creates an EventBridge with a single local subject.


EventBridge

public EventBridge(java.util.Collection localSubjects,
                   java.lang.String externalSubject)
Creates an EventBridge with multiple local subjects and a single external subject.

Since:
1.2
Method Detail

convertToExternalSubject

public static java.lang.String convertToExternalSubject(EventSubject localSubject)
A utility method that performs consistent translation from an EventSubject to a String that can be used by external transport as subject for distributed communications. Substitutes all chars that can be incorrectly interpreted by whoever (JNDI, ...?).


getExternalSubject

public java.lang.String getExternalSubject()
Returns a String subject used to post distributed events.


isRunning

public boolean isRunning()
Returns true if this bridge is active.

Since:
1.2

getLocalSubject

public EventSubject getLocalSubject()
Deprecated. since 1.2 EventBridge supports multiple local subjects, so use 'getLocalSubjects()' instead. This method returns the first subject from the subject array for backwards compatibility.

Returns a subject used for events within the local JVM.


getLocalSubjects

public java.util.Collection getLocalSubjects()
Returns a Collection of local EventSubjects.

Since:
1.2

getEventManager

public EventManager getEventManager()
Returns local EventManager used by the bridge. Returned value will be null before the bridge is started and after it is shutdown.

Since:
1.2

getExternalEventSource

public java.lang.Object getExternalEventSource()
Returns an object used as a source of local events posted in response to remote events. If externalEventSource wasn't setup during bridge startup (or if the bridge is not started), returns this object.

Since:
1.2

receivesLocalEvents

public boolean receivesLocalEvents()
Returns true if the bridge is configured to receive local events from its internal EventManager.


receivesExternalEvents

public boolean receivesExternalEvents()
Returns true if the bridge is configured to receive external events.


startup

public void startup(EventManager eventManager,
                    int mode)
             throws java.lang.Exception
Starts EventBridge in the specified mode and locally listening to all event sources that post on a preconfigured subject. Remote events reposted locally will have this EventBridge as their source.

Parameters:
eventManager - EventManager used to send and receive local events.
mode - One of the possible modes of operation - RECEIVE_EXTERNAL, RECEIVE_LOCAL, RECEIVE_LOCAL_EXTERNAL.
Throws:
java.lang.Exception

startup

public void startup(EventManager eventManager,
                    int mode,
                    java.lang.Object localEventSource)
             throws java.lang.Exception
Starts EventBridge in the specified mode and locally listening to a specified event source. Remote events reposted locally will have this EventBridge as their source.

Parameters:
eventManager - EventManager used to send and receive local events.
mode - One of the possible modes of operation - RECEIVE_EXTERNAL, RECEIVE_LOCAL, RECEIVE_LOCAL_EXTERNAL.
localEventSource - If not null, only events originating from localEventSource object will be processed by this bridge.
Throws:
java.lang.Exception

startup

public void startup(EventManager eventManager,
                    int mode,
                    java.lang.Object localEventSource,
                    java.lang.Object remoteEventSource)
             throws java.lang.Exception
Starts EventBridge in the specified mode.

Parameters:
eventManager - EventManager used to send and receive local events.
mode - One of the possible modes of operation - RECEIVE_EXTERNAL, RECEIVE_LOCAL, RECEIVE_LOCAL_EXTERNAL.
localEventSource - If not null, only events originating from localEventSource object will be processed by this bridge.
remoteEventSource - If not null, remoteEventSource object will be used as standby source of local events posted by this EventBridge in response to remote events.
Throws:
java.lang.Exception
Since:
1.2

startupExternal

protected abstract void startupExternal()
                                 throws java.lang.Exception
Starts an external interface of the EventBridge.

Throws:
java.lang.Exception

shutdown

public void shutdown()
              throws java.lang.Exception
Stops listening for events on both local and external interfaces.

Throws:
java.lang.Exception

shutdownExternal

protected abstract void shutdownExternal()
                                  throws java.lang.Exception
Shuts down the external interface of the EventBridge, cleaning up and releasing any resources used to communicate external events.

Throws:
java.lang.Exception

onExternalEvent

protected void onExternalEvent(CayenneEvent event)
Helper method intended to be called explicitly by subclasses to asynchronously post an event obtained from a remote source. Subclasses do not have to use this method, but they probably should for consistency.


onLocalEvent

public void onLocalEvent(CayenneEvent event)
                  throws java.lang.Exception
Deprecated. Unused since 1.2, as event dispatch is done via internal listeners.

Invoked by local EventManager when a local event of interest occurred. Internally delegates to "sendExternalEvent" abstract method.

Throws:
java.lang.Exception

sendExternalEvent

protected abstract void sendExternalEvent(CayenneEvent localEvent)
                                   throws java.lang.Exception
Sends a Cayenne event over the transport supported by this bridge.

Throws:
java.lang.Exception


Copyright © 2001-2006 Apache.org All Rights Reserved.