eclipse communication framework

an eclipse technology subproject
 Shared Object Containers

   Note: standalone bookmark for the ECF API (javadocs) web pages. Copy and paste: http://www.eclipse.org/ecf/org.eclipse.ecf.docs/api
 Shared Object Containers
An important sub-type of IContainer is the ISharedObjectContainer. ISharedObjectContainers provide a communications context for ISharedObject instances, which represent components that may be added and removed from the ISharedObjectContainer at runtime.

ISharedObjects represent communications components. Components use container-provided messaging to implement their communications, but are completely free to implement whatever other functionality is required by the enclosing application. All a given component must do is implement the ISharedObject interface, and add itself/be added to some instance of a container.

ECF itself defines the basic required interfaces for SharedObjectContainers and SharedObjects. ECF also provides implementations of various common communications protocols, in the form of specific type of containers, and various sorts of application-level communications (e.g conferencing or chat) via communications components implemented as ISharedObjects.

In some respects, the ECF container/shared object design resembles the design of other container architectures such a Servlet container. The difference, however, is that the ECF container model is based upon a group model of communication rather than client/server, where a given shared object can communicate with one or many remote processes either asynchronously and/or synchronously with a single primitive.
back to top
 SharedObjectContainer Lifecycle - DRAFT
SharedObjectContainers can provide access to arbitrary communications protocols. So, for example, communication with a remote instant messaging client, a server-based web service, or a distributed multi-point application can all be represented through an implementation of a SharedObjectContainer that understands the specific application-level protocol or protocols necessary to communicate with a given service or set of services. The primary role of the SharedObjectContainer is to provide SharedObjects with
  1. a consistent API for achieving secure access to a remote service
  2. a consistent API for sending and receiving asynchronous messages to/from an arbitrary communications service
  3. consistent information about message reliability and group membership
All ECF containers must implement ISharedObjectContainer. ECF also defines an extensible factory for creating ISharedObjectContainer instances called SharedObjectContainerFactory.

The lifecycle of a ISharedObjectContainer is typically as follows:
  1. An ISharedObjectContainer instance is created via SharedObjectContainerFactory.getDefault().createSharedObjectContainer()
  2. ISharedObjects are created and added to the ISharedObjectContainer
  3. The ISharedObjectContainer 'joins/connects' with a remote communications group via ISharedObjectContainer.joinGroup()
  4. The ISharedObject instances created/added in step #2 above send asynchronous messages and receive asynchronous events from the remote services
  5. ISharedObject implementation code presents/manages user interfaces, handles user input, keeps local state, communicates with replicas or external services, exposes/introduces local Eclipse-provided services to remotes, etc.
  6. When the ISharedObjectContainer is no longer needed for communication, the ISharedObjectContainer can be directed to leave the group, or leave the group on its own.
  7. When the ISharedObjectContainer is no longer needed at all the ISharedObjectContainer.dispose() method can be called to free any resources managed by the container or it's associated ISharedObjects.
back to top
 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.
back to top