org.eclipse.ecf.remoteservice.eventadmin
Class DistributedEventAdmin

java.lang.Object
  extended by org.eclipse.ecf.core.sharedobject.BaseSharedObject
      extended by 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 inherited from class org.eclipse.ecf.core.sharedobject.BaseSharedObject
DESTROYREMOTE_CODE, DESTROYSELFLOCAL_CODE
 
Constructor Summary
DistributedEventAdmin(org.osgi.framework.BundleContext context)
          Create a Distributed EventAdmin implementation.
DistributedEventAdmin(org.osgi.framework.BundleContext context, org.osgi.service.log.LogService log)
          Create a Distributed EventAdmin implementation.
 
Method Summary
protected  org.osgi.service.event.Event createEventFromMessageData(ID fromID, java.lang.Object[] messageData)
          Create a local Event from deserialized messageData.
protected  java.lang.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  ID getTarget(org.osgi.service.event.Event eventToSend)
          Get the target receiver for the eventToSend.
protected  void handleSendMessageException(java.lang.String message, org.osgi.service.event.Event eventToSend, java.lang.Object[] messageParams, java.io.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(java.lang.String message)
          Log an error.
protected  void logError(java.lang.String message, java.lang.Throwable exception)
          Log an error.
protected  void logWarning(java.lang.String message)
          Log a warning.
protected  void logWarning(java.lang.String message, java.lang.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 EventHandlers.
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.
 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
 

Constructor Detail

DistributedEventAdmin

public DistributedEventAdmin(org.osgi.framework.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(org.osgi.framework.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 EventHandlers. 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 EventHandlers (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 EventHandlers. 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 java.lang.Object[] createMessageDataFromEvent(ID target,
                                                        org.osgi.service.event.Event eventToSend)
                                                 throws java.io.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:
java.io.NotSerializableException - if the eventToSend cannot be serialized.
Since:
1.1

createEventFromMessageData

protected org.osgi.service.event.Event createEventFromMessageData(ID fromID,
                                                                  java.lang.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 EventHandlers. Should not be null.
Since:
1.1

handleSendMessageException

protected void handleSendMessageException(java.lang.String message,
                                          org.osgi.service.event.Event eventToSend,
                                          java.lang.Object[] messageParams,
                                          java.io.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
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 IContainers. 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 EventHandlers. 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 EventHandlers.

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 EventHandlers 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 EventHandlers.

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

Since:
1.1

notifyReceivedEvent

protected void notifyReceivedEvent(ID fromID,
                                   org.osgi.service.event.Event receivedEvent)
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(java.lang.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(java.lang.String message,
                          java.lang.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(java.lang.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(java.lang.String message,
                        java.lang.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.