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 and Description
protected org.osgi.framework.BundleContext	context
protected 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 and Description
protected	DistributedEventAdmin()
	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

Modifier and Type	Method and Description
boolean	addEventTopicFilters(java.lang.String[] filters)
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 SerializationHandler	getSerializationHandler(java.lang.String topic)
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.
boolean	removeEventTopicFilters(java.lang.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

DoNotReference

protected non-final for unit tests only!!!

eventHandlerTracker

protected EventHandlerTracker eventHandlerTracker

Since:

1.2

DoNotReference

This field is not intended to be referenced by clients.

context

protected org.osgi.framework.BundleContext context

Since:

1.2

Constructor Detail

DistributedEventAdmin

protected DistributedEventAdmin()

DoNotReference

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

getSerializationHandler

protected SerializationHandler getSerializationHandler(java.lang.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,
                                                                  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

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

addEventTopicFilters

public boolean addEventTopicFilters(java.lang.String[] filters)

Parameters:

filters - topic filters to add

Returns:

boolean true if given filters added, false otherwise

Since:

1.2

removeEventTopicFilters

public boolean removeEventTopicFilters(java.lang.String[] filters)

Parameters:

filters - topic filters to add

Returns:

boolean true if given filters added, false otherwise

Since:

1.2