org.eclipse.ecf.core.sharedobject
Class AbstractSharedObject

java.lang.Object
  org.eclipse.ecf.core.sharedobject.AbstractSharedObject

All Implemented Interfaces:

org.eclipse.core.runtime.IAdaptable, IIdentifiable, ISharedObject, IEventHandler

Direct Known Subclasses:

OptimisticSharedObject, TransactionSharedObject

public class AbstractSharedObject
extends java.lang.Object
implements ISharedObject, IIdentifiable

Base class for shared object classes.

Constructor Summary

AbstractSharedObject()

Method Summary

protected boolean	addEventProcessor(IEventProcessor proc)
protected void	clearEventProcessors()
protected void	creationCompleted() Called by replication strategy code (e.g.
protected void	destroyRemote(ID remoteID)
protected void	destroySelf()
protected void	destroySelfLocal()
void	dispose(ID containerID) Method called by the ISharedObjectContainer upon ISharedObject destruction.
protected void	fireEventProcessors(Event event)
java.lang.Object	getAdapter(java.lang.Class adapter)
protected ISharedObjectConfig	getConfig()
protected ISharedObjectContext	getContext()
protected ID	getGroupID()
protected ID	getHomeContainerID()
ID	getID() Return the ID for this 'identifiable' object.
protected ID	getLocalContainerID()
protected java.util.Map	getProperties()
protected ReplicaSharedObjectDescription	getReplicaDescription(ID receiver) Get a ReplicaSharedObjectDescription for a replica to be created on a given receiver.
protected ReplicaSharedObjectDescription[]	getReplicaDescriptions(ID[] receivers) This method is called by replicateToRemoteContainers to determine the ReplicaSharedObjectDescriptions associated with the given receivers.
protected SharedObjectMsg	getSharedObjectMsgFromEvent(ISharedObjectMessageEvent event) Get SharedObjectMsg from ISharedObjectMessageEvent.
void	handleEvent(Event event) Handle Event passed to this IEventHandler.
void	handleEvents(Event[] events) Handle Events passed to this IEventHandler.
protected boolean	handleSharedObjectCreateResponseEvent(ISharedObjectCreateResponseEvent createResponseEvent) Handle a ISharedObjectCreateResponseEvent.
protected boolean	handleSharedObjectMsg(SharedObjectMsg msg) SharedObjectMsg handler method.
protected boolean	handleSharedObjectMsgEvent(ISharedObjectMessageEvent event) Handle a ISharedObjectMessageEvent.
protected void	handleUnhandledEvent(Event event)
void	init(ISharedObjectConfig initData) Initialize this ISharedObject.
protected void	initialize() Initialize this shared object.
protected boolean	isConnected()
protected boolean	isPrimary()
protected boolean	removeEventProcessor(IEventProcessor proc)
protected void	replicateToRemoteContainers(ID[] remoteContainers) Replicate this shared object to a given set of remote containers.
protected void	sendSharedObjectMsgTo(ID toID, SharedObjectMsg msg) Send SharedObjectMessage to container with given ID.
protected void	sendSharedObjectMsgToPrimary(SharedObjectMsg msg) Send SharedObjectMsg to this shared object's primary instance.
protected void	sendSharedObjectMsgToSelf(SharedObjectMsg msg) Send SharedObjectMsg to local shared object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractSharedObject

public AbstractSharedObject()

Method Detail

init

public final void init(ISharedObjectConfig initData)
                throws SharedObjectInitException

Description copied from interface: ISharedObject

Initialize this ISharedObject. The ISharedObjectContainer for this ISharedObject must call this method with a non-null instance of ISharedObjectConfig. ISharedObject implementations can use this initialization to perform any initialization necessary prior to receiving any events (via handleEvent/s). Note that the ISharedObjectContext provided via the ISharedObjectConfig.getSharedObjectContext() method is not guaranteed to allow any method calls until after this init() method call has completed.

Specified by:

init in interface ISharedObject

Parameters:

initData - the initialization data passed by the ISharedObjectContainer upon initialization

Throws:

SharedObjectInitException - thrown by ISharedObject to halt initialization. ISharedObjectContainers must respond to such an exception by halting the addition of the ISharedObject instance and treating it as not in the container.

initialize

protected void initialize()
                   throws SharedObjectInitException

Initialize this shared object. Subclasses may override as appropriate to define custom initialization behavior. If initialization should fail, then a SharedObjectInitException should be thrown by implementing code. Also, subclasses overriding this method should call super.initialize() before running their own code.

Throws:

SharedObjectInitException - if initialization should throw

creationCompleted

protected void creationCompleted()

Called by replication strategy code (e.g. two phase commit) when creation is completed (i.e. when transactional replication completed successfully). Subclasses that need to be notified when creation is completed should override this method.

dispose

public void dispose(ID containerID)

Description copied from interface: ISharedObject

Method called by the ISharedObjectContainer upon ISharedObject destruction. Once this method is called, no more Events will be passed to a ISharedObject until the init method is called again.

Specified by:

dispose in interface ISharedObject

Parameters:

containerID - the ID of the container that is disposing this ISharedObject

getAdapter

public java.lang.Object getAdapter(java.lang.Class adapter)

Specified by:

getAdapter in interface org.eclipse.core.runtime.IAdaptable

handleEvent

public void handleEvent(Event event)

Description copied from interface: IEventHandler

Handle Event passed to this IEventHandler.

Specified by:

handleEvent in interface IEventHandler

Parameters:

event - the Event for the implementer to handle

addEventProcessor

protected boolean addEventProcessor(IEventProcessor proc)

removeEventProcessor

protected boolean removeEventProcessor(IEventProcessor proc)

clearEventProcessors

protected void clearEventProcessors()

handleUnhandledEvent

protected void handleUnhandledEvent(Event event)

fireEventProcessors

protected void fireEventProcessors(Event event)

handleEvents

public void handleEvents(Event[] events)

Description copied from interface: IEventHandler

Handle Events passed to this IEventHandler.

Specified by:

handleEvents in interface IEventHandler

Parameters:

events - the Events [] for the implementer to handle

getID

public ID getID()

Description copied from interface: IIdentifiable

Return the ID for this 'identifiable' object. The returned ID should be unique within its namespace.

Specified by:

getID in interface IIdentifiable

Returns:

the ID for this identifiable object

getConfig

protected ISharedObjectConfig getConfig()

getContext

protected ISharedObjectContext getContext()

getHomeContainerID

protected ID getHomeContainerID()

getLocalContainerID

protected ID getLocalContainerID()

getGroupID

protected ID getGroupID()

isConnected

protected boolean isConnected()

isPrimary

protected boolean isPrimary()

getProperties

protected java.util.Map getProperties()

destroySelf

protected void destroySelf()

destroySelfLocal

protected void destroySelfLocal()

destroyRemote

protected void destroyRemote(ID remoteID)
                      throws java.io.IOException

Throws:

java.io.IOException

sendSharedObjectMsgTo

protected void sendSharedObjectMsgTo(ID toID,
                                     SharedObjectMsg msg)
                              throws java.io.IOException

Send SharedObjectMessage to container with given ID. The toID parameter may be null, and if null the message will be delivered to all containers in group. The second parameter may not be null.

Parameters:

toID - the target container ID for the SharedObjectMsg. If null, the given message is sent to all other containers currently in group

msg - the message instance to send

Throws:

java.io.IOException - thrown if the local container is not connected or unable to send for other reason

sendSharedObjectMsgToPrimary

protected void sendSharedObjectMsgToPrimary(SharedObjectMsg msg)
                                     throws java.io.IOException

Send SharedObjectMsg to this shared object's primary instance.

Parameters:

msg - the message instance to send

Throws:

java.io.IOException - throws if the local container is not connect or unable to send for other reason

sendSharedObjectMsgToSelf

protected void sendSharedObjectMsgToSelf(SharedObjectMsg msg)

Send SharedObjectMsg to local shared object. This places the given message at the end of this shared object's message queue for processing.

Parameters:

msg - the message instance to send.

getSharedObjectMsgFromEvent

protected SharedObjectMsg getSharedObjectMsgFromEvent(ISharedObjectMessageEvent event)

Get SharedObjectMsg from ISharedObjectMessageEvent. ISharedObjectMessageEvents can come from both local and remote sources. In the remote case, the SharedObjectMsg has to be retrieved from the RemoteSharedObjectEvent rather than the ISharedObjectMessageEvent.getData() directly. This method will provide a non-null SharedObjectMsg if it's provided either via remotely or locally. Returns null if the given event does not provide a valid SharedObjectMsg.

Parameters:

event -

Returns:

SharedObjectMsg the SharedObjectMsg delivered by the given event

handleSharedObjectMsgEvent

protected boolean handleSharedObjectMsgEvent(ISharedObjectMessageEvent event)

Handle a ISharedObjectMessageEvent. This method will be automatically called by the SharedObjectMsgEventProcessor when a ISharedObjectMessageEvent is received. The SharedObjectMsgEventProcessor is associated with this object via the initialize() method

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.

handleSharedObjectCreateResponseEvent

protected boolean handleSharedObjectCreateResponseEvent(ISharedObjectCreateResponseEvent createResponseEvent)

Handle a ISharedObjectCreateResponseEvent. This handler is called by handleSharedObjectMsgEvent when the ISharedObjectMessageEvent is of type ISharedObjectCreateResponseEvent. This default implementation simply returns false. Subclasses may override as appropriate. Note that if return value is true, it will prevent subsequent event processors from having a chance to process event

Parameters:

createResponseEvent - the ISharedObjectCreateResponseEvent received

Returns:

true if the provided event should receive no further processing. If false the provided Event should be passed to subsequent event processors.

handleSharedObjectMsg

protected boolean handleSharedObjectMsg(SharedObjectMsg msg)

SharedObjectMsg handler method. This method will be called by handleSharedObjectMsgEvent(ISharedObjectMessageEvent) when a SharedObjectMsg is received either from a local source or a remote source. This default implementation simply returns false so that other processing of of the given msg can occur. Subclasses should override this behavior to define custom logic for handling SharedObjectMsgs.

Parameters:

msg - the SharedObjectMsg received

Returns:

true if the msg has been completely handled and subsequent processing should stop. False if processing should continue

getReplicaDescription

protected ReplicaSharedObjectDescription getReplicaDescription(ID receiver)

Get a ReplicaSharedObjectDescription for a replica to be created on a given receiver.

Parameters:

receiver - the receiver the ReplicaSharedObjectDescription is for

Returns:

ReplicaSharedObjectDescription to be associated with given receiver. A non-null ReplicaSharedObjectDescription must be returned.

getReplicaDescriptions

protected ReplicaSharedObjectDescription[] getReplicaDescriptions(ID[] receivers)

This method is called by replicateToRemoteContainers to determine the ReplicaSharedObjectDescriptions associated with the given receivers. Receivers may be null (meaning that all in group are to be receivers), and if so then this method should return a ReplicaSharedObjectDescription [] of length 1 with a single ReplicaSharedObjectDescription that will be used for all receivers. If receivers is non-null, then the ReplicaSharedObjectDescription [] result must be of same length as the receivers array. This method calls the getReplicaDescription method to create a replica description for each receiver. If this method returns null, null replication is done.

Parameters:

receivers - an ID[] of the intended receivers for the resulting ReplicaSharedObjectDescriptions. If null, then the entire current group is assumed to be the target, and this method should return a ReplicaSharedObjectDescriptions array of length 1, with a single ReplicaSharedObjectDescriptions for all target receivers.

Returns:

ReplicaSharedObjectDescription[] to determine replica descriptions for each receiver. A null return value indicates that no replicas are to be created. If the returned array is not null, then it must be of same length as the receivers parameter.

replicateToRemoteContainers

protected void replicateToRemoteContainers(ID[] remoteContainers)

Replicate this shared object to a given set of remote containers. This method will invoke the method getReplicaDescriptions in order to determine the set of ReplicaSharedObjectDescriptions to send to remote containers.

Parameters:

remoteContainers - the set of remote containers to replicate to. If null, all containers in the current group are sent a message to create a replica of this shared object.