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
Modifier and Type
Field
Description
`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
Modifier
Constructor
Description
`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

Modifier and Type
Method
Description
`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 final 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 Details

### 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 Details

### 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 Details

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