Eclipse Communication Framework (ECF)

ISharedObject Lifecycle - DRAFT

ISharedObject Construction

A SharedObject can be instantiated two ways:
  1. By invoking one of the 'createSharedObject' methods of an ISharedObjectContainer. These methods require a SharedObjectDescription parameter (which among other things defines the class of object to instantiate).
  2. By calling the constructor of an object class which implements the ISharedObject interface outside of any container.

Initialization

After it has been constructed the container to which it was added will invoke the ISharedObject.init method passing a non-null ISharedObjectConfig. ISharedObjects created outside of a container, will have their ISharedObject.init method invoked immediately as part of being added to the container.
Although not required, a typical implementation of 'init' will cache the ISharedObjectConfig for later usage by the ISharedObject:
 public void init(ISharedObjectConfig config) throws
SharedObjectInitException {
this.config = config;
...
}
Note: The ISharedObjectConfig parameter provides the ISharedObject with access to it's container-provided context (ISharedObjectContext) via a call to ISharedObjectConfig.getContext(). The ISharedObject is not considered initialized until after the init method is completed, and therefore the ISharedObjectContext is not available until after the init method returns.

After init completes successfully, containers are required to immediately deliver an 'activated' event to the newly added ISharedObject via ISharedObject.handleEvent(SharedObjectActivatedEvent).

Relationship to its container

ISharedObjects can be created outside of a ISharedObjectContainer and then later added to it using the ISharedObjectContainer.getSharedObjectManager().addSharedObject() method.

The only semantics that an ISharedObjectContainer requires of ISharedObjects is that they implement the ISharedObject interface.

Communications

Sending Messages
Eclipse ECF provides the ISharedObject with a simple asynchronous messaging API to send/receive arbitrary messages via the container-provided ISharedObjectContext. On the ISharedObjectContext, are methods to send arbitrary messages to remotes (sendMessage). For details see the methods on ISharedObjectContext.
Receiving Events
Containers can asynchronously deliver messages to SharedObjects in the form of Events. When a message is received for a given ISharedObject, the enclosing container wraps that message in the form of an event of a certain type, and calls that ISharedObject's handleEvent method with the Event instance.

ISharedObject removal from a container

When an ISharedObject is removed from a container (or removes itself), it's enclosing container calls the ISharedObject.dispose() method.

Example Creation Code

Here is a code snippet that creates a container and adds a single shared object to that container:
ISharedObjectContainer container = SharedObjectContainerFactory.getDefault().createSharedObjectContainer('standalone');
ID newID = IDFactory.createStringID('foo');
SharedObjectDescription sd = new SharedObjectDescription(newID,TestSharedObject.class);
container.getSharedObjectManager().createSharedObject(sd,null);
Note this creates and adds to the container a ISharedObject instance of class "TestSharedObject". The TestSharedObject null constructor is called, followed by a call to ISharedObject.init(ISharedObjectConfig) by the enclosing container. The container also sends an 'activated' event to the ISharedObject by calling its handleEvent method with an event of type org.eclipse.ecf.core.events.SharedObjectActivatedEvent.