| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2007. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| <meta http-equiv="Content-Language" content="en-us"> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" |
| type="text/css"> |
| <style type="text/css"> |
| td {border-top: solid thin black;} |
| img[alt] {background-color:#ffdddd;} |
| tr {vertical-align: top;} |
| </style> |
| <script language="JavaScript" type="text/javascript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"> </script> |
| </head> |
| <body> |
| <h1><img src="../../intro/css/images/ecf_intro.gif">Eclipse Communication Framework (ECF)</h1> |
| <p> |
| <h2>ISharedObject Lifecycle - DRAFT</h2> |
| <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<br> SharedObjectInitException {<br> this.config = config;<br> ...<br> }<br></pre> |
| <b>Note</b>: The ISharedObjectConfig parameter provides the |
| ISharedObject with access to it's |
| container-provided context (<a |
| href="http://www.eclipse.org/ecf/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="http://www.eclipse.org/ecf/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="http://www.eclipse.org/ecf/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');<br>ID newID = IDFactory.createStringID('foo');<br>SharedObjectDescription sd = new SharedObjectDescription(newID,TestSharedObject.class);<br>container.getSharedObjectManager().createSharedObject(sd,null);<br></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> |
| </body> |
| </html> |