org.apache.cayenne.event

## Class EventBridge

- java.lang.Object
- - org.apache.cayenne.event.EventBridge

- All Implemented Interfaces:
    EventListener
  Direct Known Subclasses:
    JavaGroupsBridge, JMSBridge, XMPPBridge

      public abstract class EventBridge
      extends Object
      implements 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

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected EventManager` | `eventManager`
    `protected Object` | `externalEventSource`
    `protected String` | `externalSubject`
    `protected Collection<EventSubject>` | `localSubjects`
    `protected int` | `mode`
    `static int` | `RECEIVE_EXTERNAL`
    `static int` | `RECEIVE_LOCAL`
    `static int` | `RECEIVE_LOCAL_EXTERNAL`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `EventBridge(Collection<EventSubject> localSubjects, String externalSubject)` Creates an EventBridge with multiple local subjects and a single external subject.
    `EventBridge(EventSubject localSubject, String externalSubject)` Creates an EventBridge with a single local subject.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static 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.
    `Object` | `getExternalEventSource()` Returns an object used as a source of local events posted in response to remote events.
    `String` | `getExternalSubject()` Returns a String subject used to post distributed events.
    `Collection<EventSubject>` | `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.
    `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, Object localEventSource)` Starts EventBridge in the specified mode and locally listening to a specified event source.
    `void` | `startup(EventManager eventManager, int mode, Object localEventSource, 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

    - #### 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 String externalSubject

    - #### localSubjects

          protected Collection<EventSubject> localSubjects

    - #### eventManager

          protected EventManager eventManager

    - #### mode

          protected int mode

    - #### externalEventSource

          protected Object externalEventSource

  - ### Constructor Detail

    - #### EventBridge

          public EventBridge(EventSubject localSubject,
                     String externalSubject)

      Creates an EventBridge with a single local subject.

    - #### EventBridge

          public EventBridge(Collection<EventSubject> localSubjects,
                     String externalSubject)

      Creates an EventBridge with multiple local subjects and a single external subject.
      Since:
        1.2

  - ### Method Detail

    - #### convertToExternalSubject

          public static 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 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

    - #### getLocalSubjects

          public Collection<EventSubject> 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 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 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:
        `Exception`

    - #### startup

          public void startup(EventManager eventManager,
                     int mode,
                     Object localEventSource)
                       throws 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:
        `Exception`

    - #### startup

          public void startup(EventManager eventManager,
                     int mode,
                     Object localEventSource,
                     Object remoteEventSource)
                       throws 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:
        `Exception`
      Since:
        1.2

    - #### startupExternal

          protected abstract void startupExternal()
                                           throws Exception

      Starts an external interface of the EventBridge.
      Throws:
        `Exception`

    - #### shutdown

          public void shutdown()
                        throws Exception

      Stops listening for events on both local and external interfaces.
      Throws:
        `Exception`

    - #### shutdownExternal

          protected abstract void shutdownExternal()
                                            throws Exception

      Shuts down the external interface of the EventBridge, cleaning up and releasing any resources used to communicate external events.
      Throws:
        `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.

    - #### sendExternalEvent

          protected abstract void sendExternalEvent(CayenneEvent localEvent)
                                             throws Exception

      Sends a Cayenne event over the transport supported by this bridge.
      Throws:
        `Exception`

Copyright © 2001–2014 Apache Cayenne. All rights reserved.