| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <HTML> |
| <HEAD><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>ECF Shared Object Factory</title> |
| <style type="text/css">@import url("../../../../org.eclipse.platform.doc.isv/book.css");</style> |
| <style type="text/css">@import url("../../../../org.eclipse.platform.doc.isv/schema.css");</style> |
| </HEAD> |
| <BODY> |
| <H1 style="text-align:center">ECF Shared Object Factory</H1> |
| <p></p> |
| <h6 class="CaptionFigColumn SchemaHeader">Identifier: </h6>org.eclipse.ecf.sharedObjectFactory<p></p> |
| <h6 class="CaptionFigColumn SchemaHeader">Since: </h6>0.6.0 |
| <p></p> |
| |
| <h6 class="CaptionFigColumn SchemaHeader">Description: </h6>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 class="Example"><span class="code SchemaTag"> |
| 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; |
| } |
| </span></pre><p></p> |
| <h6 class="CaptionFigColumn SchemaHeader">Configuration Markup:</h6> |
| <p></p> |
| <p class="code SchemaDtd"><!ELEMENT <a name="e.extension">extension</a> (<a href="#e.sharedObjectFactory">sharedObjectFactory</a>+)></p> |
| <p class="code SchemaDtd"><!ATTLIST extension</p> |
| <p class="code SchemaDtdAttlist">point CDATA #REQUIRED</p> |
| <p class="code SchemaDtdAttlist">id CDATA #IMPLIED</p> |
| <p class="code SchemaDtdAttlist">name CDATA #IMPLIED></p> |
| <p></p> |
| <ul class="ConfigMarkupAttlistDesc"> |
| </ul> |
| <br><p class="code SchemaDtd"><!ELEMENT <a name="e.sharedObjectFactory">sharedObjectFactory</a> (<a href="#e.property">property</a>*)></p> |
| <p class="code SchemaDtd"><!ATTLIST sharedObjectFactory</p> |
| <p class="code SchemaDtdAttlist">class CDATA #REQUIRED</p> |
| <p class="code SchemaDtdAttlist">name CDATA #IMPLIED</p> |
| <p class="code SchemaDtdAttlist">description CDATA #IMPLIED></p> |
| <p></p> |
| <ul class="ConfigMarkupAttlistDesc"> |
| <li><b>class</b> - The fully qualified name of the class that implements the <b>org.eclipse.ecf.core.provider.ISharedObjectInstantiator</b> interface.</li> |
| <li><b>name</b> - 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</li> |
| <li><b>description</b> - </li> |
| </ul> |
| <br><p class="code SchemaDtd"><!ELEMENT <a name="e.property">property</a> EMPTY></p> |
| <p class="code SchemaDtd"><!ATTLIST property</p> |
| <p class="code SchemaDtdAttlist">name CDATA #REQUIRED</p> |
| <p class="code SchemaDtdAttlist">value CDATA #REQUIRED></p> |
| <p></p> |
| <p class="ConfigMarkupElementDesc"> |
| Property (name,value) associated with SharedObjectTypeDescription</p> |
| <br> |
| <ul class="ConfigMarkupAttlistDesc"> |
| <li><b>name</b> - The name of the property</li> |
| <li><b>value</b> - The value of the property</li> |
| </ul> |
| <br><h6 class="CaptionFigColumn SchemaHeader">Examples: </h6>Here's an example of an extension point declaration: |
| |
| <pre class="Example"><span class="code SchemaTag"> |
| <extension |
| point=</span><span class="code SchemaCstring">"org.eclipse.ecf.sharedobject.sharedObjectFactory"</span><span class="code SchemaTag">> |
| <sharedObjectFactory |
| class=</span><span class="code SchemaCstring">"org.eclipse.ecf.tests.provider.TestSharedObjectInstantiator"</span><span class="code SchemaTag"> |
| name=</span><span class="code SchemaCstring">"ecf.test.sharedobjectfactory"</span><span class="code SchemaTag">/> |
| </extension> |
| </span></pre> |
| |
| and the TestSharedObjectInstantiator is defined: |
| |
| <pre class="Example"><span class="code SchemaTag"> |
| 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(); |
| } |
| } |
| </span></pre> |
| |
| <h3>Example Usage of Container by Clients</h3> |
| |
| Clients may use the extension via calls such as: |
| |
| <pre class="Example"><span class="code SchemaTag"> |
| ISharedObject obj = SharedObjectFactory.getDefault().createSharedObject("ecf.test.sharedobjectfactory"); |
| </span></pre> |
| <p></p> |
| |
| <h6 class="CaptionFigColumn SchemaHeader">API Information: </h6>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 class="Example"><span class="code SchemaTag"> |
| 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); |
| } |
| </span></pre> |
| |
| See the "Examples" page for an example usage of the extension point. |
| <p></p> |
| |
| <br> |
| <p class="note SchemaCopyright"> |
| 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 |
| |
| </p> |
| </BODY> |
| </HTML> |
