Package org.eclipse.ecf.remoteservice.eventadmin

## Class DistributedEventAdmin

- java.lang.Object
- - org.eclipse.ecf.core.sharedobject.BaseSharedObject
  - - org.eclipse.ecf.remoteservice.eventadmin.DistributedEventAdmin

All Implemented Interfaces:
  `org.eclipse.core.runtime.IAdaptable`, `IIdentifiable`, `ISharedObject`, `org.osgi.service.event.EventAdmin`

    public class DistributedEventAdmin
    extends BaseSharedObject
    implements org.osgi.service.event.EventAdmin

### Field Summary

Fields
`protected BundleContext` `context`
`protected org.eclipse.ecf.internal.remoteservice.eventadmin.EventHandlerTracker` `eventHandlerTracker`
`protected static boolean` `ignoreSerializationExceptions`

### Fields inherited from class org.eclipse.ecf.core.sharedobject.BaseSharedObject

`DESTROYREMOTE_CODE, DESTROYSELFLOCAL_CODE`

### Constructor Summary

Constructors
`protected` `DistributedEventAdmin()`
`` `DistributedEventAdmin​(BundleContext context)` Create a Distributed EventAdmin implementation.
`` `DistributedEventAdmin​(BundleContext context, org.osgi.service.log.LogService log)` Create a Distributed EventAdmin implementation.

### Method Summary

All Methods Instance Methods Concrete Methods
`boolean` `addEventTopicFilters​(String[] filters)`
`protected org.osgi.service.event.Event` `createEventFromMessageData​(ID fromID, Object[] messageData)` Create a local `Event` from deserialized messageData.
`protected Object[]` `createMessageDataFromEvent​(ID target, org.osgi.service.event.Event eventToSend)` Create message data for deliver to a target (which could be `null` to designate multiple target receivers), The resulting Object[] must be Serializable and in a form that receivers can deserialize via `createEventFromMessageData(ID, Object[])` on the receiver.
`protected org.osgi.service.event.Event` `getEventToSend​(org.osgi.service.event.Event event)` Get the actual event to pass to `sendMessage(Event)`.
`protected SerializationHandler` `getSerializationHandler​(String topic)`
`protected ID` `getTarget​(org.osgi.service.event.Event eventToSend)` Get the target receiver for the eventToSend.
`protected void` `handleSendMessageException​(String message, org.osgi.service.event.Event eventToSend, Object[] messageParams, IOException exception)` Handle any exceptions occuring as part of Event serialization or message send.
`protected boolean` `handleSharedObjectMsg​(ID fromID, SharedObjectMsg msg)` Handle the shared object message.
`protected boolean` `handleSharedObjectMsgEvent​(ISharedObjectMessageEvent event)` Override of BaseSharedObject.handleSharedObjectMsgEvent.
`protected void` `localDispatch​(org.osgi.service.event.Event dispatchedEvent, boolean isAsync)` Locally dispatch an Event.
`protected void` `logError​(String message)` Log an error.
`protected void` `logError​(String message, Throwable exception)` Log an error.
`protected void` `logWarning​(String message)` Log a warning.
`protected void` `logWarning​(String message, Throwable exception)` Log a warning.
`protected void` `notifyPostLocalDispatch​(org.osgi.service.event.Event event)` Notification called after local dispatch has been done.
`protected void` `notifyPostSendMessage​(org.osgi.service.event.Event eventSent)` Method called after `sendMessage(Event)` is called (typically from within `postEvent(Event)`), but prior to local dispatch.
`protected org.osgi.service.event.Event` `notifyPreLocalDispatch​(org.osgi.service.event.Event event)` Method called from within `localDispatch(Event, boolean)` prior to actual deliver to matching `EventHandler`s.
`protected void` `notifyReceivedEvent​(ID fromID, org.osgi.service.event.Event receivedEvent)`
`void` `postEvent​(org.osgi.service.event.Event event)` Post an event for asynchronous delivery via this distributed event admin.
`boolean` `removeEventTopicFilters​(String[] filters)`
`void` `sendEvent​(org.osgi.service.event.Event event)` Send the given event synchronously.
`protected void` `sendMessage​(org.osgi.service.event.Event eventToSend)` Send the event as a shared object message.
`void` `start()` Start this distributed event admin instance.
`void` `stop()` Stop this distributed event admin instance.

### Methods inherited from class org.eclipse.ecf.core.sharedobject.BaseSharedObject

`addEventProcessor, clearEventProcessors, creationCompleted, destroyRemote, destroySelf, destroySelfLocal, dispose, fireEventProcessors, getAdapter, getConfig, getConnectedID, getContext, getGroupMemberIDs, getHomeContainerID, getID, getLocalContainerID, getProperties, getReplicaDescription, getReplicaDescriptions, getSharedObjectMsgFromEvent, handleEvent, handleEvents, handleSharedObjectCreateResponseEvent, handleSharedObjectMsg, handleUnhandledEvent, init, initialize, isConnected, isPrimary, log, log, removeEventProcessor, replicateToRemoteContainers, sendSharedObjectMsgTo, sendSharedObjectMsgToPrimary, sendSharedObjectMsgToSelf, trace, traceCatching, traceEntering, traceEntering, traceEntering, traceExiting, traceExiting`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### ignoreSerializationExceptions

    protected static boolean ignoreSerializationExceptions

Since:
  1.2
Restriction:
  protected non-final for unit tests only!!!

#### eventHandlerTracker

    protected org.eclipse.ecf.internal.remoteservice.eventadmin.EventHandlerTracker eventHandlerTracker

Since:
  1.2
Restriction:
  This field is not intended to be referenced by clients.

#### context

    protected BundleContext context

Since:
  1.2

### Constructor Detail

#### DistributedEventAdmin

    protected DistributedEventAdmin()

Restriction:

#### DistributedEventAdmin

    public DistributedEventAdmin​(BundleContext context,
                                 org.osgi.service.log.LogService log)

Create a Distributed EventAdmin implementation.

Parameters:
  `context` - the BundleContext to be used. Must not be `null`.
  `log` - the `LogService` to use. May be `null`. If `null`, then a LogTracker is created and used to find and use a `LogService`.
Since:
  1.1

#### DistributedEventAdmin

    public DistributedEventAdmin​(BundleContext context)

Create a Distributed EventAdmin implementation.

Parameters:
  `context` - the BundleContext to be used. Must not be `null`.
Since:
  1.1

### Method Detail

#### start

    public void start()

Start this distributed event admin instance. This method should be called prior to registering this object as an `EventAdmin` implementation with the OSGi service registry.

#### stop

    public void stop()

Stop this distributed event admin instance. This method should be called after unregistering the `ServiceRegistration` created on registration with the OSGi service registry.

#### sendEvent

    public void sendEvent​(org.osgi.service.event.Event event)

Send the given event synchronously. The default implementation of this method simply does a local-only dispatch to `EventHandler`s. It does not attempt to distribute the given event as does `postEvent(Event)`.

Specified by:
  `sendEvent` in interface `org.osgi.service.event.EventAdmin`
Parameters:
  `event` - the Event to send synchronously to local `EventHandler`s (only). Must not be `null`.

#### postEvent

    public void postEvent​(org.osgi.service.event.Event event)

Post an event for asynchronous delivery via this distributed event admin. This is the primary entry point for the distributed event admin implementation for asynchronous delivery to a set of receivers (known to the this shared object and it's enclosing `IContainer`. The event to post must not be `null`.

This implementation goes through the following steps

1. Call `getEventToSend(Event)`. If the Event returned from getEventToSend is `null`, then the following three method calls do not occur, and postEvent returns immediately.
2. Call `sendMessage(Event)` with the non-`null` result of `getEventToSend(Event)`
3. Call `notifyPostSendMessage(Event)`
4. Call `localDispatch(Event, boolean)`

Specified by:
  `postEvent` in interface `org.osgi.service.event.EventAdmin`
Parameters:
  `event` - the Event to send asynchronously to matching `EventHandler`s. Must not be `null`.
Since:
  1.1

#### sendMessage

    protected void sendMessage​(org.osgi.service.event.Event eventToSend)

Send the event as a shared object message. The given event will be serialized and sent via `BaseSharedObject.sendSharedObjectMsgTo(ID, SharedObjectMsg)`.

Prior to actual sending, the `getTarget(Event)` method will be called, to allow subclasses to determine the target receiver. Then the `createMessageDataFromEvent(ID, Event)` method is called, to create an Object[] of data for sending in the message. The Object[] returned from `createMessageDataFromEvent(ID, Event)` must be serializable. See `createMessageDataFromEvent(ID, Event)`.

Subclasses may override this method to customize or replace this sendMessage behavior.

If an exception occurs on serialization or sending, the `handleSendMessageException(String, Event, Object[], IOException)` method will be called to handle it.

Parameters:
  `eventToSend` - the event to send. Will not be `null`.
Since:
  1.1

#### createMessageDataFromEvent

    protected Object[] createMessageDataFromEvent​(ID target,
                                                  org.osgi.service.event.Event eventToSend)
                                           throws NotSerializableException

Create message data for deliver to a target (which could be `null` to designate multiple target receivers), The resulting Object[] must be Serializable and in a form that receivers can deserialize via `createEventFromMessageData(ID, Object[])` on the receiver.

The default implementation creates a single `EventMessage` instance and adds it to an Object[] of length 1.

Subclasses may override as appropriate to customize the serialization of the given eventToSend.

Subclasses may override as appropriate. If this method is overridden, then `createEventFromMessageData(ID, Object[])` should also be overridden as well on the receiver.

Parameters:
  `target` - the target `ID` that is the intended receiver returned from `getTarget(Event)`.
  `eventToSend` - the event to send. Will not be `null`.
Returns:
  Object[] the actual message data that will be serialized (must be Serializable to use in `sendMessage(Event)`). The default implementation creates a single `EventMessage` instance and adds it to an Object[] of length 1.
Throws:
  `NotSerializableException` - if the eventToSend cannot be serialized.
Since:
  1.1

#### getSerializationHandler

    protected SerializationHandler getSerializationHandler​(String topic)

Parameters:
  `topic` - topic
Returns:
  SerializationHandler the serialization handler associated with topic
Since:
  1.2

#### createEventFromMessageData

    protected org.osgi.service.event.Event createEventFromMessageData​(ID fromID,
                                                                      Object[] messageData)

Create a local `Event` from deserialized messageData. The fromID will be a non-`null` `ID` instance that is the container ID of the sender DistributedEventAdmin. The default implementation assumes that a single `EventMessage` is in the first array element of the messageData, casts the messageData[0] to EventMessage, and then returns eventMessage.getEvent().

Subclasses can override as appropriate. If this method is overridden, then `createMessageDataFromEvent(ID, Event)` should also be overridden as well on the sender.

Parameters:
  `fromID` - the ID of the message sender. Will not be `null`.
  `messageData` - Object[] received from fromID. Will be a deserialized local version of the Object[] from fromID.
Returns:
  Event to be delivered to local `EventHandler`s. Should not be `null`.
Since:
  1.1

#### handleSendMessageException

    protected void handleSendMessageException​(String message,
                                              org.osgi.service.event.Event eventToSend,
                                              Object[] messageParams,
                                              IOException exception)

Handle any exceptions occuring as part of Event serialization or message send. The default is to call `logError(String, Throwable)` with the eventToSend and messageParams appended to the message parameter.

Parameters:
  `message` - a message associated with the exception.
  `eventToSend` - the event that was to be sent.
  `messageParams` - the message params that were to be
  `exception` - exception
Since:
  1.1

#### getTarget

    protected ID getTarget​(org.osgi.service.event.Event eventToSend)

Get the target receiver for the eventToSend. The returned `ID` will be used to send a shared object message to either a single `IContainer`, or a group of `IContainer`s. To send to the entire group, this method should return `null`. The default implementation is to return `null`, meaning that the given eventToSend is to be sent to all receivers connected to this shared object's enclosing `IContainer`.

Parameters:
  `eventToSend` - the eventToSend. Will not be `null`.
Returns:
  ID the ID target for `sendMessage(Event)` to send to. May be `null`. `null` is the default implementation, meaning that the Event will be delivered to all members of the group known to this shared object's `IContainer`.
Since:
  1.1

#### getEventToSend

    protected org.osgi.service.event.Event getEventToSend​(org.osgi.service.event.Event event)

Get the actual event to pass to `sendMessage(Event)`. The default implementation of this method is to simply return the event passed in as the method argument.

Subclasses may override...to filter or transform the event prior to calling `sendMessage(Event)`.

Parameters:
  `event` - the event. Will not be `null`.
Returns:
  Event to send. By default, the event provided as the argument is returned.
Since:
  1.1

#### notifyPostSendMessage

    protected void notifyPostSendMessage​(org.osgi.service.event.Event eventSent)

Method called after `sendMessage(Event)` is called (typically from within `postEvent(Event)`), but prior to local dispatch. The default implementation is to do nothing.

Parameters:
  `eventSent` - the event that was sent. Will not be `null`.
Since:
  1.1

#### notifyPreLocalDispatch

    protected org.osgi.service.event.Event notifyPreLocalDispatch​(org.osgi.service.event.Event event)

Method called from within `localDispatch(Event, boolean)` prior to actual deliver to matching `EventHandler`s. The default implementation returns the given event. Subclasses may override as appropriate. If the returned Event is `null` then no local dispatch will occur for the given Event.

Subclasses may override as appropriate.

Parameters:
  `event` - the Event to dispatch. Will not be `null`.
Returns:
  Event the event to actually dispatch. If `null`, no local dispatch is done for this event.
Since:
  1.1

#### notifyPostLocalDispatch

    protected void notifyPostLocalDispatch​(org.osgi.service.event.Event event)

Notification called after local dispatch has been done. The default implemenation does nothing. Note that this method is called by the thread that calls `localDispatch(Event, boolean)`, and if the actual dispatch is done by another thread (i.e. second param to localDispatch is `true`), then the dispatch could occur before, after, or during the actual handling via the matching `EventHandler`s.

Subclasses may override as appropriate.

Parameters:
  `event` - the Event that was delivered to matching `EventHandler` s. Will not be `null`.
Since:
  1.1

#### localDispatch

    protected void localDispatch​(org.osgi.service.event.Event dispatchedEvent,
                                 boolean isAsync)

Locally dispatch an Event. This method is used to deliver an `Event` to matching `EventHandler`s that are registered in the local OSGi service registry.

Parameters:
  `dispatchedEvent` - the Event to dispatch. Will not be `null`.
  `isAsync` - `true` if the dispatch should be done asynchronously (non-blocking), `false` if the dispatch should be done synchronously.

#### handleSharedObjectMsg

    protected boolean handleSharedObjectMsg​(ID fromID,
                                            SharedObjectMsg msg)

Handle the shared object message. This method is called on receiver implementations of the DistributedEventAdmin, so that they can deliver to locally registered `EventHandler`s.

This implementation does the following:

1. Verifies that the value `SharedObjectMsg.getMethod()` matches the appropriate String.
2. Calls #createEventFromMessageData(ID, Object[]) to convert the message data (returned from #createMessageDataFromEvent(ID, Event) on the sender)
3. If the Event returned from #createEventFromMessageData(ID, Object[]) is non-`null`, then call
   1. #notifyReceivedEvent(ID, Event) to allow subclasses to be notified prior to local dispatch
   2. #localDispatch(Event, boolean) to actually do the local dispatch asynchronously

Overrides:
  `handleSharedObjectMsg` in class `BaseSharedObject`
Since:
  1.1

#### notifyReceivedEvent

    protected void notifyReceivedEvent​(ID fromID,
                                       org.osgi.service.event.Event receivedEvent)

Parameters:
  `fromID` - fromID
  `receivedEvent` - received event
Since:
  1.1

#### handleSharedObjectMsgEvent

    protected final boolean handleSharedObjectMsgEvent​(ISharedObjectMessageEvent event)

Override of BaseSharedObject.handleSharedObjectMsgEvent. Subclasses must not override this method.

Overrides:
  `handleSharedObjectMsgEvent` in class `BaseSharedObject`
Parameters:
  `event` - the event to handle
Returns:
  true if the provided event should receive no further processing. If false the provided Event should be passed to subsequent event processors.
Since:
  1.1

#### logWarning

    protected void logWarning​(String message)

Log a warning.

Subclasses may override as appropriate.

Parameters:
  `message` - the message to include in the warning. Should not be `null`.
Since:
  1.1

#### logWarning

    protected void logWarning​(String message,
                              Throwable exception)

Log a warning.

Subclasses may override as appropriate.

Parameters:
  `message` - the message to include in the warning. Should not be `null`.
  `exception` - the exception to include in the warning. May be `null`. If non-`null` then exception will be printed to System.out.
Since:
  1.1

#### logError

    protected void logError​(String message)

Log an error.

Subclasses may override as appropriate.

Parameters:
  `message` - the message to include in the error. Should not be `null`.
Since:
  1.1

#### logError

    protected void logError​(String message,
                            Throwable exception)

Log an error.

Subclasses may override as appropriate.

Parameters:
  `message` - the message to include in the error. Should not be `null`.
  `exception` - the exception to include in the warning. May be `null`. If non-`null` then exception will be printed to System.out.

#### addEventTopicFilters

    public boolean addEventTopicFilters​(String[] filters)

Parameters:
  `filters` - topic filters to add
Returns:
  boolean true if given filters added, false otherwise
Since:
  1.2

#### removeEventTopicFilters

    public boolean removeEventTopicFilters​(String[] filters)

Parameters:
  `filters` - topic filters to add
Returns:
  boolean true if given filters added, false otherwise
Since:
  1.2