ECF Shared Object Factory

org.eclipse.ecf.sharedObjectFactory

0.6.0

ECF Shared Object Factory extension point (org.eclipse.ecf.sharedObjectFactory. This extension point allows implmenters to define an org.eclipse.ecf.core.sharedobject.provider.ISharedObjectInstantiator that will be responsible for creating org.eclipse.ecf.core.sharedobject.ISharedObject instances when requested by clients. Here is the ISharedObjectInstantiator that extensions must implement:
public interface ISharedObjectInstantiator {
 /**
  * Create instance of ISharedObject. This is the interface that plugin
  * implementations must implement for the sharedObjectFactory extension
  * point. The caller may optionally specify both argument types and
  * arguments that will be passed into this method (and therefore to the
  * provider implementation implementing this method). For example:
  * 

<p>

*

</p>

*

<p>

*

<b>

* SharedObjectFactory.getDefault().createSharedObject("foosharedobject",new * String [] { java.lang.String }, new Object { "hello" });

</b>

*

</p>

*

<p>

*

</p>

* * @param typeDescription * the SharedObjectTypeDescription associated with the registered * shared object provider implementation plugin * @param args * arguments specified by the caller. May be null if no arguments * are passed in by caller to * SharedObjectFactory.getDefault().createSharedObject(...) * @return ISharedObject instance. The provider implementation must return a * valid object implementing ISharedObject OR throw a * SharedObjectCreateException * @throws SharedObjectCreateException * if shared object instance cannot be created */ public ISharedObject createInstance( SharedObjectTypeDescription typeDescription, Object[] args) throws SharedObjectCreateException; }

<!ELEMENT extension (sharedObjectFactory+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT sharedObjectFactory (property*)>

<!ATTLIST sharedObjectFactory

class       CDATA #REQUIRED

name        CDATA #IMPLIED

description CDATA #IMPLIED>


<!ELEMENT property EMPTY>

<!ATTLIST property

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Property (name,value) associated with SharedObjectTypeDescription



Here's an example of an extension point declaration:
   

<extension point=

"org.eclipse.ecf.sharedobject.sharedObjectFactory"

>

<sharedObjectFactory class=

"org.eclipse.ecf.tests.provider.TestSharedObjectInstantiator"

name=

"ecf.test.sharedobjectfactory"

/>

</extension>

and the TestSharedObjectInstantiator is defined:
public class TestSharedObjectInstantiator implements ISharedObjectInstantiator {

 public ISharedObject createInstance(SharedObjectTypeDescription description, Object[] args) throws SharedObjectCreateException {
  System.out.println("createInstance("+description+","+((args==null)?"null":Arrays.asList(args).toString()));
  return new TestSharedObject();
 }
}

Example Usage of Container by Clients

Clients may use the extension via calls such as:
ISharedObject obj = SharedObjectFactory.getDefault().createSharedObject("ecf.test.sharedobjectfactory");

The API for accessing the functionality provided via extensions is via org.eclipse.ecf.core.sharedobject.SharedObjectFactory.getDefault() methods. Specifically, the org.eclipse.ecf.core.sharedobject.ISharedObjectFactory.createSharedObject() methods are to be used to create shared object instances, where extensions implement the actual shared object creation Here is the org.eclipse.ecf.core.sharedobject.ISharedObjectFactory contract implemented by the org.eclipse.ecf.core.sharedobject.SharedObjectFactory:
public interface ISharedObjectFactory {
 /*
  * Add a SharedObjectTypeDescription to the set of known
  * SharedObjectTypeDescriptions.
  * 
  * @param scd the SharedObjectTypeDescription to add to this factory @return
  * SharedObjectTypeDescription the old description of the same name, null if
  * none found
  */
 public SharedObjectTypeDescription addDescription(
   SharedObjectTypeDescription description);

 /**
  * Get a collection of the SharedObjectTypeDescriptions currently known to
  * this factory. This allows clients to query the factory to determine what
  * if any other SharedObjectTypeDescriptions are currently registered with
  * the factory, and if so, what they are.
  * 
  * @return List of SharedObjectTypeDescription instances. Will not be null.
  */
 public List getDescriptions();

 /**
  * Check to see if a given named description is already contained by this
  * factory
  * 
  * @param description
  *            the SharedObjectTypeDescription to look for
  * @return true if description is already known to factory, false otherwise
  */
 public boolean containsDescription(SharedObjectTypeDescription description);

 /**
  * Get the known SharedObjectTypeDescription given it's name.
  * 
  * @param name
  * @return SharedObjectTypeDescription found. Null if description not found.
  * @throws SharedObjectCreateException
  */
 public SharedObjectTypeDescription getDescriptionByName(String name)
   throws SharedObjectCreateException;

 /**
  * Create ISharedObject instance. Given a SharedObjectTypeDescription
  * object, a String [] of argument types, and an Object [] of parameters,
  * this method will
  * 

<p>

*

<ul>

*

<li>

lookup the known SharedObjectTypeDescriptions to find one of * matching name

</li>

*

<li>

if found, will retrieve or create an ISharedObjectInstantiator for * that description

</li>

*

<li>

Call the ISharedObjectInstantiator.createInstance method to return * an instance of ISharedObject

</li>

*

</ul>

* * @param typeDescription * the SharedObjectTypeDescription to use to create the instance * @param args * an Object [] of arguments passed to the createInstance method * of the ISharedObjectInstantiator * @return a valid instance of ISharedObject. Will not be null. * @throws SharedObjectCreateException * if shared object cannot be created */ public ISharedObject createSharedObject( SharedObjectTypeDescription typeDescription, Object[] args) throws SharedObjectCreateException; /** * Create ISharedObject instance. Given a SharedObjectTypeDescription name, * this method will *

<p>

*

<ul>

*

<li>

lookup the known SharedObjectTypeDescriptions to find one of * matching name

</li>

*

<li>

if found, will retrieve or create an ISharedObjectInstantiator for * that description

</li>

*

<li>

Call the ISharedObjectInstantiator.createInstance method to return * an instance of ISharedObject

</li>

*

</ul>

* * @param descriptionName * the SharedObjectTypeDescription name to lookup * @return a valid instance of ISharedObject. Will not be null. * @throws SharedObjectCreateException */ public ISharedObject createSharedObject(String descriptionName) throws SharedObjectCreateException; /** * Create ISharedObject instance. Given a SharedObjectTypeDescription name, * this method will *

<p>

*

<ul>

*

<li>

lookup the known SharedObjectTypeDescriptions to find one of * matching name

</li>

*

<li>

if found, will retrieve or create an ISharedObjectInstantiator for * that description

</li>

*

<li>

Call the ISharedObjectInstantiator.createInstance method to return * an instance of ISharedObject

</li>

*

</ul>

* * @param descriptionName * the SharedObjectTypeDescription name to lookup * @param args * the Object [] of arguments passed to the * ISharedObjectInstantiator.createInstance method * @return a valid instance of IContainer. Will not be null. * @throws SharedObjectCreateException */ public ISharedObject createSharedObject(String descriptionName, Object[] args) throws SharedObjectCreateException; /** * Remove given description from set known to this factory. * * @param scd * the SharedObjectTypeDescription to remove * @return the removed SharedObjectTypeDescription, null if nothing removed */ public SharedObjectTypeDescription removeDescription( SharedObjectTypeDescription scd); }
See the "Examples" page for an example usage of the extension point.