| <?xml version='1.0' encoding='UTF-8'?> |
| <!-- Schema file written by PDE --> |
| <schema targetNamespace="org.eclipse.ecf" xmlns="http://www.w3.org/2001/XMLSchema"> |
| <annotation> |
| <appInfo> |
| <meta.schema plugin="org.eclipse.ecf" id="sharedObjectFactory" name="ECF Shared Object Factory"/> |
| </appInfo> |
| <documentation> |
| ECF Shared Object Factory extension point (<b>org.eclipse.ecf.sharedObjectFactory</b>. This extension point allows implmenters to define an <b>org.eclipse.ecf.core.sharedobject.provider.ISharedObjectInstantiator</b> that will be responsible for creating |
| <b>org.eclipse.ecf.core.sharedobject.ISharedObject</b> instances when requested by clients. Here is the <b>ISharedObjectInstantiator</b> that |
| extensions must implement: |
| |
| <pre> |
| 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; |
| } |
| </pre> |
| </documentation> |
| </annotation> |
| |
| <element name="extension"> |
| <annotation> |
| <appInfo> |
| <meta.element /> |
| </appInfo> |
| </annotation> |
| <complexType> |
| <sequence> |
| <element ref="sharedObjectFactory" minOccurs="1" maxOccurs="unbounded"/> |
| </sequence> |
| <attribute name="point" type="string" use="required"> |
| <annotation> |
| <documentation> |
| |
| </documentation> |
| </annotation> |
| </attribute> |
| <attribute name="id" type="string"> |
| <annotation> |
| <documentation> |
| |
| </documentation> |
| </annotation> |
| </attribute> |
| <attribute name="name" type="string"> |
| <annotation> |
| <documentation> |
| |
| </documentation> |
| </annotation> |
| </attribute> |
| </complexType> |
| </element> |
| |
| <element name="sharedObjectFactory"> |
| <complexType> |
| <sequence> |
| <element ref="property" minOccurs="0" maxOccurs="unbounded"/> |
| </sequence> |
| <attribute name="class" type="string" use="required"> |
| <annotation> |
| <documentation> |
| The fully qualified name of the class that implements the <b>org.eclipse.ecf.core.provider.ISharedObjectInstantiator</b> interface. |
| </documentation> |
| <appInfo> |
| <meta.attribute kind="java" basedOn="org.eclipse.ecf.core.sharedobject.provider.ISharedObjectInstantiator"/> |
| </appInfo> |
| </annotation> |
| </attribute> |
| <attribute name="name" type="string"> |
| <annotation> |
| <documentation> |
| 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 <b>not</b> 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 |
| </documentation> |
| </annotation> |
| </attribute> |
| <attribute name="description" type="string"> |
| <annotation> |
| <documentation> |
| |
| </documentation> |
| </annotation> |
| </attribute> |
| </complexType> |
| </element> |
| |
| <element name="property"> |
| <annotation> |
| <documentation> |
| Property (name,value) associated with SharedObjectTypeDescription |
| </documentation> |
| </annotation> |
| <complexType> |
| <attribute name="name" type="string" use="required"> |
| <annotation> |
| <documentation> |
| The name of the property |
| </documentation> |
| </annotation> |
| </attribute> |
| <attribute name="value" type="string" use="required"> |
| <annotation> |
| <documentation> |
| The value of the property |
| </documentation> |
| </annotation> |
| </attribute> |
| </complexType> |
| </element> |
| |
| <annotation> |
| <appInfo> |
| <meta.section type="since"/> |
| </appInfo> |
| <documentation> |
| 0.6.0 |
| </documentation> |
| </annotation> |
| |
| <annotation> |
| <appInfo> |
| <meta.section type="examples"/> |
| </appInfo> |
| <documentation> |
| Here's an example of an extension point declaration: |
| |
| <pre> |
| <extension |
| point="org.eclipse.ecf.sharedobject.sharedObjectFactory"> |
| <sharedObjectFactory |
| class="org.eclipse.ecf.tests.provider.TestSharedObjectInstantiator" |
| name="ecf.test.sharedobjectfactory"/> |
| </extension> |
| </pre> |
| |
| and the TestSharedObjectInstantiator is defined: |
| |
| <pre> |
| 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(); |
| } |
| } |
| </pre> |
| |
| <h3>Example Usage of Container by Clients</h3> |
| |
| Clients may use the extension via calls such as: |
| |
| <pre> |
| ISharedObject obj = SharedObjectFactory.getDefault().createSharedObject("ecf.test.sharedobjectfactory"); |
| </pre> |
| </documentation> |
| </annotation> |
| |
| <annotation> |
| <appInfo> |
| <meta.section type="apiInfo"/> |
| </appInfo> |
| <documentation> |
| The API for accessing the functionality provided via extensions is via <b>org.eclipse.ecf.core.sharedobject.SharedObjectFactory.getDefault()</b> methods. Specifically, the <b>org.eclipse.ecf.core.sharedobject.ISharedObjectFactory.createSharedObject()</b> methods are to be used to create shared |
| object instances, where extensions implement the actual shared object creation |
| |
| Here is the <b>org.eclipse.ecf.core.sharedobject.ISharedObjectFactory</b> contract implemented by the <b>org.eclipse.ecf.core.sharedobject.SharedObjectFactory</b>: |
| |
| <pre> |
| 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); |
| } |
| </pre> |
| |
| See the "Examples" page for an example usage of the extension point. |
| </documentation> |
| </annotation> |
| |
| |
| <annotation> |
| <appInfo> |
| <meta.section type="copyright"/> |
| </appInfo> |
| <documentation> |
| 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 |
| |
| </documentation> |
| </annotation> |
| |
| </schema> |
