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