Package org.eclipse.ecf.remoteservice.eventadmin

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

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

      • 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