blob: f51df7ffc4fd23af2fd6f9d62c53d92ae9ddb1d1 [file] [log] [blame]
<!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:
* &lt;p&gt;
* &lt;/p&gt;
* &lt;p&gt;
* &lt;b&gt;
* SharedObjectFactory.getDefault().createSharedObject("foosharedobject",new
* String [] { java.lang.String }, new Object { "hello" });&lt;/b&gt;
* &lt;/p&gt;
* &lt;p&gt;
* &lt;/p&gt;
*
* @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">&lt;!ELEMENT <a name="e.extension">extension</a> (<a href="#e.sharedObjectFactory">sharedObjectFactory</a>+)&gt;</p>
<p class="code SchemaDtd">&lt;!ATTLIST extension</p>
<p class="code SchemaDtdAttlist">point&nbsp;CDATA #REQUIRED</p>
<p class="code SchemaDtdAttlist">id&nbsp;&nbsp;&nbsp;&nbsp;CDATA #IMPLIED</p>
<p class="code SchemaDtdAttlist">name&nbsp;&nbsp;CDATA #IMPLIED&gt;</p>
<p></p>
<ul class="ConfigMarkupAttlistDesc">
</ul>
<br><p class="code SchemaDtd">&lt;!ELEMENT <a name="e.sharedObjectFactory">sharedObjectFactory</a> (<a href="#e.property">property</a>*)&gt;</p>
<p class="code SchemaDtd">&lt;!ATTLIST sharedObjectFactory</p>
<p class="code SchemaDtdAttlist">class&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;CDATA #REQUIRED</p>
<p class="code SchemaDtdAttlist">name&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;CDATA #IMPLIED</p>
<p class="code SchemaDtdAttlist">description&nbsp;CDATA #IMPLIED&gt;</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">&lt;!ELEMENT <a name="e.property">property</a> EMPTY&gt;</p>
<p class="code SchemaDtd">&lt;!ATTLIST property</p>
<p class="code SchemaDtdAttlist">name&nbsp;&nbsp;CDATA #REQUIRED</p>
<p class="code SchemaDtdAttlist">value&nbsp;CDATA #REQUIRED&gt;</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">
&lt;extension
point=</span><span class="code SchemaCstring">&quot;org.eclipse.ecf.sharedobject.sharedObjectFactory&quot;</span><span class="code SchemaTag">&gt;
&lt;sharedObjectFactory
class=</span><span class="code SchemaCstring">&quot;org.eclipse.ecf.tests.provider.TestSharedObjectInstantiator&quot;</span><span class="code SchemaTag">
name=</span><span class="code SchemaCstring">&quot;ecf.test.sharedobjectfactory&quot;</span><span class="code SchemaTag">/&gt;
&lt;/extension&gt;
</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&apos;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
* &lt;p&gt;
* &lt;ul&gt;
* &lt;li&gt;lookup the known SharedObjectTypeDescriptions to find one of
* matching name&lt;/li&gt;
* &lt;li&gt;if found, will retrieve or create an ISharedObjectInstantiator for
* that description&lt;/li&gt;
* &lt;li&gt;Call the ISharedObjectInstantiator.createInstance method to return
* an instance of ISharedObject&lt;/li&gt;
* &lt;/ul&gt;
*
* @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
* &lt;p&gt;
* &lt;ul&gt;
* &lt;li&gt;lookup the known SharedObjectTypeDescriptions to find one of
* matching name&lt;/li&gt;
* &lt;li&gt;if found, will retrieve or create an ISharedObjectInstantiator for
* that description&lt;/li&gt;
* &lt;li&gt;Call the ISharedObjectInstantiator.createInstance method to return
* an instance of ISharedObject&lt;/li&gt;
* &lt;/ul&gt;
*
* @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
* &lt;p&gt;
* &lt;ul&gt;
* &lt;li&gt;lookup the known SharedObjectTypeDescriptions to find one of
* matching name&lt;/li&gt;
* &lt;li&gt;if found, will retrieve or create an ISharedObjectInstantiator for
* that description&lt;/li&gt;
* &lt;li&gt;Call the ISharedObjectInstantiator.createInstance method to return
* an instance of ISharedObject&lt;/li&gt;
* &lt;/ul&gt;
*
* @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>