Eclipse Communication Framework (ECF)
ISharedObject Lifecycle - DRAFT
ISharedObject Construction
A SharedObject can be instantiated two ways:
- 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).
- 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.