sharedobjectcontainerdocumentation.html

<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>ECF Shared Object Containers Documentation</title>
<link rel="stylesheet" href="http://www.eclipse.org/default_style.css" type="text/css">
</head>
<body bgcolor="#FFFFFF">
<a name="top"></a>
</table>
<table border=0 cellspacing=5 cellpadding=2 width="100%">
  <tbody>
    <tr>
      <td width="69%" class="bannertext">
        <font class="indextop style2">eclipse communication framework</font>
        <br><br>
        <font class="indexsub">an eclipse technology subproject</font>
      </td>
      <td width="31%">
        <div align="center">
          <img src="../images/Idea.jpg" width="120" height="86" hspace="50" align="middle">
        </div>
      </td>
    </tr>
  </tbody>
</table>
<table border=0 cellspacing=5 cellpadding=2 width="100%" >
  <tr>
    <td align=left valign=top bgcolor="#0080C0"><b><font color="#FFFFFF" face="Arial,Helvetica">
    &nbsp;Shared Object Containers</font></b></td>
  </tr>
  <tr>
    <td>
      <ul>
        <li><a href="#SharedObjectContainer Lifecycle">SharedObjectContainer Lifecycle</a></li>
		<li><a href="#ISharedObject Lifecycle">ISharedObject Lifecycle</a></li>
        <li><a href="org.eclipse.ecf.docs/api">ECF API (javadocs)</a></li>
      </ul>
      <p>&nbsp;&nbsp;&nbsp;<strong>Note:</strong> standalone bookmark for the ECF API (javadocs) web pages. Copy and paste:
	  http://www.eclipse.org/ecf/org.eclipse.ecf.docs/api</p>
    </td>
  </tr>
  <tr>
    <td ALIGN=left VALIGN=top BGCOLOR="#0080C0"><b><font color="#FFFFFF" face="Arial,Helvetica">
    &nbsp;<a name="Shared Object Containers"></a>Shared Object Containers</font></b></td>
  </tr>
  <tr>
    <td>
       An important sub-type of IContainer is the <b><a href="http://www.eclipse.org/ecf/org.eclipse.ecf.docs/api/org/eclipse/ecf/core/ISharedObjectContainer.html">ISharedObjectContainer</a></b>.
       ISharedObjectContainers provide a communications context for ISharedObject instances, which represent
       components that may be added and removed from the ISharedObjectContainer at runtime.
       <br><br>
       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.
              <br><br>
       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.
       <br><br>
       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.
	   <br><a href="#top"><i>back to top</i></a>
            </td>
  </tr>
  <tr>
    <td ALIGN=left VALIGN=top BGCOLOR="#0080C0"><b><font color="#FFFFFF" face="Arial,Helvetica">
    &nbsp;<a name="SharedObjectContainer Lifecycle"></a>SharedObjectContainer Lifecycle - DRAFT</font></b></td>
  </tr>


  <tr>
  <td>
  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
  <ol><li>a consistent API for achieving secure access to a remote service</li><li>a
  consistent API for sending and receiving asynchronous messages to/from an arbitrary communications
  service</li><li>consistent information about message reliability and group membership
  </li></ol>
All ECF containers must implement <a href="org.eclipse.ecf.docs/api/org/eclipse/ecf/core/ISharedObjectContainer.html">ISharedObjectContainer</a>.  ECF also defines an extensible factory for
creating ISharedObjectContainer instances called <a href="org.eclipse.ecf.docs/api/org/eclipse/ecf/core/SharedObjectContainerFactory.html">SharedObjectContainerFactory</a>.
<br><br>
The lifecycle of a ISharedObjectContainer is typically as follows:
<ol><li>
An ISharedObjectContainer instance is created via SharedObjectContainerFactory.getDefault().createSharedObjectContainer()
</li><li>
ISharedObjects are created and added to the ISharedObjectContainer
</li><li>
The ISharedObjectContainer 'joins/connects' with a remote communications group via
ISharedObjectContainer.joinGroup()
</li><li>
The ISharedObject instances created/added in step #2 above send asynchronous messages and receive asynchronous
events from the remote services
</li><li>
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.
</li><li>
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.
</li><li>
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.
</li>
</ol>
<a href="#top"><i>back to top</i></a>
  </td>
  </tr>
  <tr>
    <td ALIGN=left VALIGN=top BGCOLOR="#0080C0"><b><font color="#FFFFFF" face="Arial,Helvetica">
    &nbsp;<a name="ISharedObject Lifecycle"></a>ISharedObject Lifecycle - DRAFT</font></b></td>
  </tr>
  <tr>
  <td>
<h4>ISharedObject Construction</h4>

A SharedObject can be instantiated two ways:

<ol><li>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).
</li><li>By calling the constructor of an object class which implements the ISharedObject interface outside of any container.
</li></ol>

<h4>Initialization</h4>

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.
<br>
Although not required, a typical implementation of 'init' will cache the ISharedObjectConfig for later usage by the ISharedObject:
<br>
<pre>
 public void init(ISharedObjectConfig config) throws
	SharedObjectInitException {
	this.config = config;
  	...
 }
</pre>
<b>Note</b>: The ISharedObjectConfig parameter provides the ISharedObject with access to it's
container-provided context (<a href="org.eclipse.ecf.docs/api/org/eclipse/ecf/core/ISharedObjectContext.html">ISharedObjectContext</a>) 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.
<br><br>
After init completes successfully, containers are required to immediately deliver an 'activated' event to the newly added
ISharedObject via ISharedObject.handleEvent(SharedObjectActivatedEvent).
<h4>Relationship to its container</h4>
ISharedObjects can be created outside of a ISharedObjectContainer and then later added to it using the
ISharedObjectContainer.getSharedObjectManager().addSharedObject() method.
<br><br>
The only semantics that an ISharedObjectContainer requires of ISharedObjects is that they implement the ISharedObject interface.
<h4>Communications</h4>
<h5>Sending Messages</h5>
Eclipse ECF provides the ISharedObject with a simple asynchronous messaging API to send/receive
arbitrary messages via the container-provided <a href="org.eclipse.ecf.docs/api/org/eclipse/ecf/core/ISharedObjectContext.html">ISharedObjectContext</a>.  On the
ISharedObjectContext, are methods to send arbitrary messages to remotes (sendMessage).  For details see
the methods on <a href="org.eclipse.ecf.docs/api/org/eclipse/ecf/core/ISharedObjectContext.html">ISharedObjectContext</a>.
<br>
<h5>Receiving Events</h5>
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.
<h4>ISharedObject removal from a container</h4>
When an ISharedObject is removed from a container (or removes itself), it's enclosing container calls the
ISharedObject.dispose() method.
<h4>Example Creation Code</h4>
Here is a code snippet that creates a container and adds a single shared object to that container:
<pre>
ISharedObjectContainer container = SharedObjectContainerFactory.getDefault().createSharedObjectContainer('standalone');
ID newID = IDFactory.createStringID('foo');
SharedObjectDescription sd = new SharedObjectDescription(newID,TestSharedObject.class);
container.getSharedObjectManager().createSharedObject(sd,null);
</pre>
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.
<br><a href="#top"><i>back to top</i></a>
  </td>
  </tr>
</table>

</body>
</html>