ECF Shared Object Factory

Identifier:

org.eclipse.ecf.sharedObjectFactory

Since:

0.6.0

Description:

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;
}

Configuration Markup:

<!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>

class - The fully qualified name of the class that implements the org.eclipse.ecf.core.provider.ISharedObjectInstantiator interface.
name - An optional name for the extension. If no name is explicitly provided by the extension, the sharedObjectFactory class name is used as the name. Note that this name must not conflict with any other name in the ECF SharedObjectFactory in order to be successfully registered. Care should therefore be taken in selection of a name such that it does not conflict with other pre-existing names for this factory implementations
description -

<!ELEMENT property EMPTY>

<!ATTLIST property

name CDATA #REQUIRED

value CDATA #REQUIRED>

Property (name,value) associated with SharedObjectTypeDescription

name - The name of the property
value - The value of the property

Examples:

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");

API Information:

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.

Copyright (c) 2004 Composent, Inc. and others. This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which is available at https://www.eclipse.org/legal/epl-2.0/ SPDX-License-Identifier: EPL-2.0