org.eclipse.ecf.core.sharedobject

## Class BaseSharedObject

- java.lang.Object
- - org.eclipse.ecf.core.sharedobject.BaseSharedObject

All Implemented Interfaces:
  org.eclipse.core.runtime.IAdaptable, IIdentifiable, ISharedObject

Direct Known Subclasses:
  DistributedEventAdmin, OptimisticSharedObject, RegistrySharedObject, TransactionSharedObject

    public class BaseSharedObject
    extends Object
    implements ISharedObject, IIdentifiable

Base class for shared object classes. This base class provides a number of utility method for subclasses to use for tracing (e.g. `traceCatching(String, Throwable)`, `traceEntering(String)`, `traceExiting(String)`) logging (e.g. `log(int, String, Throwable)`), as well as methods to access the `ISharedObjectContext` for the shared object instance (e.g. `getID()`, `getHomeContainerID()`, `getContext()`, `getConfig()`, `getProperties()`, `isConnected()`, `isPrimary()`, etc). Also provided are a number of methods for sending messages to remote replica shared objects (e.g. `sendSharedObjectMsgTo(ID, SharedObjectMsg)`, `sendSharedObjectMsgToPrimary(SharedObjectMsg)`, `sendSharedObjectMsgToSelf(SharedObjectMsg)`) and methods for replicating oneself to remote containers (e.g. `replicateToRemoteContainers(ID[])`). Finally, object lifecycle methods are also provided (e.g. `initialize()`, `creationCompleted()`, `dispose(ID)`). Subclasses may use and override these methods as appropriate.

### Field Summary

Fields
`protected static int` `DESTROYREMOTE_CODE`
`protected static int` `DESTROYSELFLOCAL_CODE`

### Constructor Summary

Constructors
Constructor and Description
`BaseSharedObject()`

### Method Summary

All Methods Instance Methods Concrete Methods
`boolean` `addEventProcessor(IEventProcessor proc)` Add an event processor to the set of event processors available.
`void` `clearEventProcessors()` Clear event processors.
`protected void` `creationCompleted()` Called by replication strategy code (e.g.
`protected void` `destroyRemote(ID remoteID)`
`protected void` `destroySelf()` Destroy this shared object in the context of the current container.
`protected void` `destroySelfLocal()` Destroy the local copy of this shared object in the current container.
`void` `dispose(ID containerID)` Method called by the ISharedObjectContainer upon ISharedObject destruction.
`protected void` `fireEventProcessors(Event event)` Fire the current set of event processors with given event.
`Object` `getAdapter(Class adapter)`
`protected ISharedObjectConfig` `getConfig()` Get the config for this shared object.
`protected ID` `getConnectedID()`
`protected ISharedObjectContext` `getContext()` Get the shared object context for this object.
`protected ID[]` `getGroupMemberIDs()` Get IDs of remote containers currently in this group.
`protected ID` `getHomeContainerID()`
`ID` `getID()` Return the ID for this 'identifiable' object.
`protected ID` `getLocalContainerID()`
`protected Map<String,?>` `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(ID fromID, SharedObjectMsg msg)`
`protected boolean` `handleSharedObjectMsg(SharedObjectMsg msg)` SharedObjectMsg handler method.
`protected boolean` `handleSharedObjectMsgEvent(ISharedObjectMessageEvent event)` Handle a ISharedObjectMessageEvent.
`protected void` `handleUnhandledEvent(Event event)` Method called when an event is not handled by any event processor.
`void` `init(ISharedObjectConfig initData)` Initialize this ISharedObject.
`protected void` `initialize()` Initialize this shared object.
`protected boolean` `isConnected()`
`protected boolean` `isPrimary()`
`protected void` `log(int code, String method, Throwable e)`
`protected void` `log(String method, Throwable e)`
`boolean` `removeEventProcessor(IEventProcessor proc)` Remove an event processor from the set of event processors available to this object.
`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.
`protected void` `trace(String method, String message)`
`protected void` `traceCatching(String method, Throwable t)`
`protected void` `traceEntering(String methodName)`
`protected void` `traceEntering(String methodName, Object param)`
`protected void` `traceEntering(String methodName, Object[] params)`
`protected void` `traceExiting(String methodName)`
`protected void` `traceExiting(String methodName, Object result)`

### Methods inherited from class java.lang.Object

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

### Field Detail

#### DESTROYREMOTE_CODE

    protected static final int DESTROYREMOTE_CODE

See Also:
  Constant Field Values

#### DESTROYSELFLOCAL_CODE

    protected static final int DESTROYSELFLOCAL_CODE

See Also:
  Constant Field Values

### Constructor Detail

#### BaseSharedObject

    public BaseSharedObject()

### 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 Object getAdapter(Class adapter)

Specified by:
  `getAdapter` in interface `org.eclipse.core.runtime.IAdaptable`

#### handleEvent

    public void handleEvent(Event event)

Description copied from interface: `ISharedObject`
Handle Event passed to this IEventHandler.

Specified by:
  `handleEvent` in interface `ISharedObject`
Parameters:
  `event` - the Event for the implementer to handle

#### addEventProcessor

    public boolean addEventProcessor(IEventProcessor proc)

Add an event processor to the set of event processors available.

Parameters:
  `proc` - the event processor to add. Must not be `null`.
Returns:
  `true` if actually added, `false` otherwise.

#### removeEventProcessor

    public boolean removeEventProcessor(IEventProcessor proc)

Remove an event processor from the set of event processors available to this object.

Parameters:
  `proc` - the event processor to remove. Must not be `null`.
Returns:
  `true` if actually removed, `false` otherwise.

#### clearEventProcessors

    public void clearEventProcessors()

Clear event processors.

#### handleUnhandledEvent

    protected void handleUnhandledEvent(Event event)

Method called when an event is not handled by any event processor.

Parameters:
  `event` - the event that was not handled.

#### fireEventProcessors

    protected void fireEventProcessors(Event event)

Fire the current set of event processors with given event.

Parameters:
  `event` - the event to deliver to event processors.

#### handleEvents

    public void handleEvents(Event[] events)

Description copied from interface: `ISharedObject`
Handle Events passed to this IEventHandler.

Specified by:
  `handleEvents` in interface `ISharedObject`
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. May return `null`.

Specified by:
  `getID` in interface `IIdentifiable`
Returns:
  the ID for this identifiable object. May return `null`.

#### getConfig

    protected final ISharedObjectConfig getConfig()

Get the config for this shared object.

Returns:
  ISharedObjectConfig for this object. The ISharedObjectConfig is set within `init(ISharedObjectConfig)`. Will not be `null` as long as the init method is called prior to this method being called.

#### getContext

    protected final ISharedObjectContext getContext()

Get the shared object context for this object.

Returns:
  ISharedObjectContext the context. Will not be `null`.

#### getHomeContainerID

    protected ID getHomeContainerID()

Returns:
  ID that is the home container ID (primary) for this shared object. Will not be `null` as long as the `init(ISharedObjectConfig)` method has been called (by container) as a result of `ISharedObjectManager.addSharedObject(ID, ISharedObject, Map)`.

#### getLocalContainerID

    protected ID getLocalContainerID()

Returns:
  ID that is the local container ID for this shared object. Will be `null` if the shared object is *not* in a local container (i.e. has been removed from the container).

#### getConnectedID

    protected ID getConnectedID()

Returns:
  ID the connected ID for the container that contains this shared object. Will be non-`null` if the surrounding container is not currently connected.

#### isConnected

    protected final boolean isConnected()

Returns:
  `true` if the surrounding container is currently connected, `false` otherwise.

#### isPrimary

    protected final boolean isPrimary()

Returns:
  `true` if this shared object replica is the primary. The definition of primary is whether the `getLocalContainerID()` and `getHomeContainerID()` values are equal.

#### getProperties

    protected final Map<String,?> getProperties()

Returns:
  Map any properties associated with this shared object via the ISharedObjectConfig provided upon `init(ISharedObjectConfig)`.

#### destroySelf

    protected void destroySelf()

Destroy this shared object in the context of the current container. Destroys both local copy and any replicas present in remote containers.

#### destroySelfLocal

    protected void destroySelfLocal()

Destroy the local copy of this shared object in the current container.

#### destroyRemote

    protected void destroyRemote(ID remoteID)
                          throws IOException

Parameters:
  `remoteID` - the ID of the remote container where the replica should be destroyed.
Throws:
  `IOException` - if the destroy message cannot be sent (i.e. due to disconnection, etc).

#### sendSharedObjectMsgTo

    protected void sendSharedObjectMsgTo(ID toID,
                                         SharedObjectMsg msg)
                                  throws 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:
  `IOException` - thrown if the local container is not connected or unable to send for other reason

#### sendSharedObjectMsgToPrimary

    protected void sendSharedObjectMsgToPrimary(SharedObjectMsg msg)
                                         throws IOException

Send SharedObjectMsg to this shared object's primary instance.

Parameters:
  `msg` - the message instance to send
Throws:
  `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.

#### handleSharedObjectMsg

    protected boolean handleSharedObjectMsg(ID fromID,
                                            SharedObjectMsg msg)

Since:
  2.4

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

#### getGroupMemberIDs

    protected ID[] getGroupMemberIDs()

Get IDs of remote containers currently in this group. This method consults the current container context to retrieve the current group membership

Returns:
  ID[] of current group membership. Will not return null;
See Also:
  `ISharedObjectContext.getGroupMemberIDs()`

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

#### log

    protected void log(int code,
                       String method,
                       Throwable e)

#### log

    protected void log(String method,
                       Throwable e)

#### traceEntering

    protected void traceEntering(String methodName)

#### traceEntering

    protected void traceEntering(String methodName,
                                 Object[] params)

#### traceEntering

    protected void traceEntering(String methodName,
                                 Object param)

#### traceExiting

    protected void traceExiting(String methodName)

#### traceExiting

    protected void traceExiting(String methodName,
                                Object result)

#### traceCatching

    protected void traceCatching(String method,
                                 Throwable t)

#### trace

    protected void trace(String method,
                         String message)

Since:
  2.2