diff options
| author | slewis | 2005-06-01 06:36:26 +0000 |
|---|---|---|
| committer | slewis | 2005-06-01 06:36:26 +0000 |
| commit | a1b4364b0c733a7a29998d312704085beddf53b8 (patch) | |
| tree | 091a0d0c69ee2e242f033f393d02dd75903007e9 | |
| parent | b5ffa442c0a68b4e5302efb524c60f4567ce16d9 (diff) | |
| download | org.eclipse.ecf-a1b4364b0c733a7a29998d312704085beddf53b8.tar.gz org.eclipse.ecf-a1b4364b0c733a7a29998d312704085beddf53b8.tar.xz org.eclipse.ecf-a1b4364b0c733a7a29998d312704085beddf53b8.zip | |
schema docs for extension points
3 files changed, 449 insertions, 0 deletions
diff --git a/framework/bundles/org.eclipse.ecf/doc/org_eclipse_ecf_connectionFactory.html b/framework/bundles/org.eclipse.ecf/doc/org_eclipse_ecf_connectionFactory.html new file mode 100644 index 000000000..0539d3890 --- /dev/null +++ b/framework/bundles/org.eclipse.ecf/doc/org_eclipse_ecf_connectionFactory.html @@ -0,0 +1,146 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<title>ECF Connection Factory</title> +<style>@import url("file:/c:/eclipse3.1m7/eclipse/plugins/org.eclipse.platform_3.1.0/book.css");</style> +<style>@import url("file:/c:/eclipse3.1m7/eclipse/plugins/org.eclipse.platform.doc.isv_3.1.0/schema.css");</style> +</HEAD> +<BODY> +<H1><CENTER>ECF Connection Factory</CENTER></H1> +<p></p> +<h6 class=CaptionFigColumn id=header>Identifier: </h6>org.eclipse.ecf.comm<p></p> +<h6 class=CaptionFigColumn id=header>Since: </h6>0.2.0 +<p></p> + +<p> +<h6 class=CaptionFigColumn id=header>Description: </h6>This extension allows plugins to register themselves as 'providers' of ECF connection factories. Once registered via this extension point, plugins can provide implementations of custom ISynchAsynchConnection instances via the ECF connection factory (<b>org.eclipse.ecf.core.comm.ConnectionFactory</b>). +<p>Plugins using this extension point can define new implementation classes of the core ISynchAsynchConnection interface. When client requests are made to ECF to create <b>ISynchAsynchConnection</b> instances via the ConnectionFactory.makeSynchAsynchConnection() methods, requests to create instances of the appropriate type will be re-directed to the given extension.</p> +<p><h6 class=CaptionFigColumn id=header>Configuration Markup:</h6></p> +<p class=code id=dtd><!ELEMENT <a name="e.extension">extension</a> (<a href="#e.connectionFactory">connectionFactory</a>)></p> +<p class=code id=dtd><!ATTLIST extension</p> +<p class=code id=dtdAttlist>point CDATA #REQUIRED<p class=code id=dtdAttlist>id CDATA #IMPLIED<p class=code id=dtdAttlist>name CDATA #IMPLIED></p> +<p></p> +<ul class=ConfigMarkup id=attlistDesc> +</ul> +<br><p class=code id=dtd><!ELEMENT <a name="e.connectionFactory">connectionFactory</a> (<a href="#e.defaultargument">defaultargument</a>)></p> +<p class=code id=dtd><!ATTLIST connectionFactory</p> +<p class=code id=dtdAttlist>class CDATA #REQUIRED<p class=code id=dtdAttlist>name CDATA #IMPLIED<p class=code id=dtdAttlist>description CDATA #IMPLIED></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +Connection factory definition</p> +<br> +<ul class=ConfigMarkup id=attlistDesc> +<li><b>class</b> - Required class that provides implementation of connection factory. The class must implement <b>org.eclipse.ecf.core.comm.provider.ISynchAsynchConnectionInstantiator</b></li> +<li><b>name</b> - Optional name for connection factory. If this name is not explicitly given, the class will be used for the name.</li> +<li><b>description</b> - An optional description for the connection factory.</li> +</ul> +<br><p class=code id=dtd><!ELEMENT <a name="e.defaultargument">defaultargument</a> EMPTY></p> +<p class=code id=dtd><!ATTLIST defaultargument</p> +<p class=code id=dtdAttlist>type CDATA #IMPLIED<p class=code id=dtdAttlist>value CDATA #IMPLIED<p class=code id=dtdAttlist>name CDATA #IMPLIED></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +Default argument to be passed to makeInstance method. Value of this element (if any) is used to provide a default value for the given argument</p> +<br> +<ul class=ConfigMarkup id=attlistDesc> +<li><b>type</b> - The fully qualified type of the argument.</li> +<li><b>value</b> - The value for the default argument</li> +<li><b>name</b> - An optional name for the defaultargument</li> +</ul> +<br><p class=code id=dtd><!ELEMENT <a name="e.extension">extension</a> (<a href="#e.connectionFactory">connectionFactory</a>)></p> +<p class=code id=dtd><!ATTLIST extension</p> +<p class=code id=dtdAttlist>point CDATA #REQUIRED<p class=code id=dtdAttlist>id CDATA #IMPLIED<p class=code id=dtdAttlist>name CDATA #IMPLIED></p> +<p></p> +<ul class=ConfigMarkup id=attlistDesc> +</ul> +<br><p class=code id=dtd><!ELEMENT <a name="e.connectionFactory">connectionFactory</a> (<a href="#e.defaultargument">defaultargument</a>)></p> +<p class=code id=dtd><!ATTLIST connectionFactory</p> +<p class=code id=dtdAttlist>class CDATA #REQUIRED<p class=code id=dtdAttlist>name CDATA #IMPLIED<p class=code id=dtdAttlist>description CDATA #IMPLIED></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +Connection factory definition</p> +<br> +<ul class=ConfigMarkup id=attlistDesc> +<li><b>class</b> - Required class that provides implementation of connection factory. The class must implement <b>org.eclipse.ecf.core.comm.provider.ISynchAsynchConnectionInstantiator</b></li> +<li><b>name</b> - Optional name for connection factory. If this name is not explicitly given, the class will be used for the name.</li> +<li><b>description</b> - An optional description for the connection factory.</li> +</ul> +<br><p class=code id=dtd><!ELEMENT <a name="e.defaultargument">defaultargument</a> EMPTY></p> +<p class=code id=dtd><!ATTLIST defaultargument</p> +<p class=code id=dtdAttlist>type CDATA #IMPLIED<p class=code id=dtdAttlist>value CDATA #IMPLIED<p class=code id=dtdAttlist>name CDATA #IMPLIED></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +Default argument to be passed to makeInstance method. Value of this element (if any) is used to provide a default value for the given argument</p> +<br> +<ul class=ConfigMarkup id=attlistDesc> +<li><b>type</b> - The fully qualified type of the argument.</li> +<li><b>value</b> - The value for the default argument</li> +<li><b>name</b> - An optional name for the defaultargument</li> +</ul> +<br><h6 class=CaptionFigColumn id=header>Examples: </h6>Here's an extension that associates a class org.eclipse.ecf.test.FooContainerFactory with name 'foo' in the ECF <b>SharedObjectContainerFactory</b>: + +<pre> + <p class=code id=tag><extension + point=<p class=code id=cstring>"org.eclipse.ecf.connectionFactory"</p><p class=code id=tag>></p> + <p class=code id=tag><connectionFactory + class=<p class=code id=cstring>"org.eclipse.ecf.provider.comm.tcp.Client$Creator"</p><p class=code id=tag> + description=<p class=code id=cstring>"TCP Client Connection Factory"</p><p class=code id=tag> + name=<p class=code id=cstring>"org.eclipse.ecf.provider.comm.tcp.Client"</p><p class=code id=tag>></p> + <p class=code id=tag><defaultargument + value=<p class=code id=cstring>"10000"</p><p class=code id=tag> + type=<p class=code id=cstring>"java.lang.Integer"</p><p class=code id=tag> + name=<p class=code id=cstring>"keepAlive"</p><p class=code id=tag>/></p> + <p class=code id=tag></connectionFactory></p> + <p class=code id=tag></extension></p> +</pre> + +Here's an example implementation of this extension point: + +<pre> + public ISynchAsynchConnection makeInstance(ConnectionDescription description, + ISynchAsynchConnectionEventHandler handler, Class[] clazzes, + Object[] args) throws ConnectionInstantiationException { + try { + String [] argVals = description.getArgDefaults(); + Integer ka = null; + if (argVals != null && argVals.length != 0) { + String val = argVals[0]; + if (val != null) { + ka = new Integer(val); + } + } + if (args != null && args.length != 0) { + if (args[0] instanceof Integer) { + ka = (Integer) args[0]; + } else if (args[0] instanceof String) { + ka = new Integer((String) args[0]); + } + } + return new Client(handler, ka); + } catch (Exception e) { + throw new ConnectionInstantiationException( + "Exception in creating connection " + + Client.class.getName(), e); + } + } +</pre> +<p></p> + +<h6 class=CaptionFigColumn id=header>API Information: </h6>The API for this extension point is provided by the <b>org.eclipse.ecf.core.comm.ContainerFactory</b> static methods. Specifically, the 'makeSynchAsynchConnection' static methods are to be used by clients. The functionality provided by the extension point mechanism can be used at runtime via the <b>ConnectionFactory.addDescription(ConnectionDescription)</b> method. The available connection factories can be queried with the <b>ConnectionFactory.getDescriptions()</b> method. +<p></p> + +<h6 class=CaptionFigColumn id=header>Supplied Implementation: </h6>The supplied implementations of this extension point are: + +In org.eclipse.ecf.provider plugin: + +org.eclipse.ecf.provider.tcp.Client$Creator +<p></p> + +<br> +<p class=note id=copyright> +Copyright (c) 2005 Composent, Inc. and others. +All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html. Contributors: Composent, Inc. - initial API and implementation +<p></p> + +</p> +</BODY> +</HTML> diff --git a/framework/bundles/org.eclipse.ecf/doc/org_eclipse_ecf_containerFactory.html b/framework/bundles/org.eclipse.ecf/doc/org_eclipse_ecf_containerFactory.html new file mode 100644 index 000000000..c44a31de9 --- /dev/null +++ b/framework/bundles/org.eclipse.ecf/doc/org_eclipse_ecf_containerFactory.html @@ -0,0 +1,164 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<title>ECF Container Factory</title> +<style>@import url("file:/c:/eclipse3.1m7/eclipse/plugins/org.eclipse.platform_3.1.0/book.css");</style> +<style>@import url("file:/c:/eclipse3.1m7/eclipse/plugins/org.eclipse.platform.doc.isv_3.1.0/schema.css");</style> +</HEAD> +<BODY> +<H1><CENTER>ECF Container Factory</CENTER></H1> +<p></p> +<h6 class=CaptionFigColumn id=header>Identifier: </h6>org.eclipse.ecf.containerFactory<p></p> +<h6 class=CaptionFigColumn id=header>Since: </h6>0.0.1 +<p></p> + +<p> +<h6 class=CaptionFigColumn id=header>Description: </h6>This extension allows plugins to register themselves as 'providers' of ECF shared object containers. Once registered via this extension point, plugins can then provide there own implementations of ISharedObjectContainer in response to client request of the ECF container factory (<b>org.eclipse.ecf.core.SharedObjectContainerFactory</b>). +<p>Plugins using this extension point can define a new implementation of any desired communications protocol, and expose that protocol as an instance of an <b>ISharedObjectContainer</b>. When client requests are made to ECF SharedObjectContainerFactory to create <b>ISharedObjectContainer</b> instances, those requests will be re-directed to the given ISharedObjectContainer implementer.</p> +<p><h6 class=CaptionFigColumn id=header>Configuration Markup:</h6></p> +<p class=code id=dtd><!ELEMENT <a name="e.extension">extension</a> (<a href="#e.containerFactory">containerFactory</a>+)></p> +<p class=code id=dtd><!ATTLIST extension</p> +<p class=code id=dtdAttlist>point CDATA #REQUIRED<p class=code id=dtdAttlist>id CDATA #IMPLIED<p class=code id=dtdAttlist>name CDATA #IMPLIED></p> +<p></p> +<ul class=ConfigMarkup id=attlistDesc> +</ul> +<br><p class=code id=dtd><!ELEMENT <a name="e.containerFactory">containerFactory</a> (<a href="#e.defaultargument">defaultargument</a>* , <a href="#e.property">property</a>*)></p> +<p class=code id=dtd><!ATTLIST containerFactory</p> +<p class=code id=dtdAttlist>class CDATA #REQUIRED<p class=code id=dtdAttlist>name CDATA #IMPLIED<p class=code id=dtdAttlist>description CDATA #IMPLIED></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +The container factory extension point. Can optionally contain a list of 'defaultargument' elements that describe the arguments (and provide default values) to be passed to provider implementation</p> +<br> +<ul class=ConfigMarkup id=attlistDesc> +<li><b>class</b> - The class implementing the containerFactory extension point. The given class must implement the <b>org.eclipse.ecf.core.provider.ISharedObjectContainerInstantiator</b> interface</li> +<li><b>name</b> - An optional name for the extension. If no name is explicitly provided by the extension, the containerFactory class name is used as the name. Note that this name must <b>not</b> conflict with any other name in the ECF SharedObjectContainerFactory 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> - An optional description of the implementation of this extension point</li> +</ul> +<br><p class=code id=dtd><!ELEMENT <a name="e.defaultargument">defaultargument</a> EMPTY></p> +<p class=code id=dtd><!ATTLIST defaultargument</p> +<p class=code id=dtdAttlist>type CDATA #IMPLIED<p class=code id=dtdAttlist>value CDATA #IMPLIED<p class=code id=dtdAttlist>name CDATA #IMPLIED></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +Default argument to be passed to <b>org.eclipse.ecf.core.provider.makeInstance()</b> method. Value of this element (if any) is used to indicate a default value for the given argument</p> +<br> +<ul class=ConfigMarkup id=attlistDesc> +<li><b>type</b> - The fully qualified type of the default argument</li> +<li><b>value</b> - The value for the default argument</li> +<li><b>name</b> - An optional name for the defaultargument element</li> +</ul> +<br><p class=code id=dtd><!ELEMENT <a name="e.property">property</a> EMPTY></p> +<p class=code id=dtd><!ATTLIST property</p> +<p class=code id=dtdAttlist>name CDATA #REQUIRED<p class=code id=dtdAttlist>value CDATA #REQUIRED></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +Property (name,value) associated with SharedObjectContainerDescription</p> +<br> +<ul class=ConfigMarkup id=attlistDesc> +<li><b>name</b> - The name of the property</li> +<li><b>value</b> - The value of the property</li> +</ul> +<br><p class=code id=dtd><!ELEMENT <a name="e.extension">extension</a> (<a href="#e.containerFactory">containerFactory</a>+)></p> +<p class=code id=dtd><!ATTLIST extension</p> +<p class=code id=dtdAttlist>point CDATA #REQUIRED<p class=code id=dtdAttlist>id CDATA #IMPLIED<p class=code id=dtdAttlist>name CDATA #IMPLIED></p> +<p></p> +<ul class=ConfigMarkup id=attlistDesc> +</ul> +<br><p class=code id=dtd><!ELEMENT <a name="e.containerFactory">containerFactory</a> (<a href="#e.defaultargument">defaultargument</a>* , <a href="#e.property">property</a>*)></p> +<p class=code id=dtd><!ATTLIST containerFactory</p> +<p class=code id=dtdAttlist>class CDATA #REQUIRED<p class=code id=dtdAttlist>name CDATA #IMPLIED<p class=code id=dtdAttlist>description CDATA #IMPLIED></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +The container factory extension point. Can optionally contain a list of 'defaultargument' elements that describe the arguments (and provide default values) to be passed to provider implementation</p> +<br> +<ul class=ConfigMarkup id=attlistDesc> +<li><b>class</b> - The class implementing the containerFactory extension point. The given class must implement the <b>org.eclipse.ecf.core.provider.ISharedObjectContainerInstantiator</b> interface</li> +<li><b>name</b> - An optional name for the extension. If no name is explicitly provided by the extension, the containerFactory class name is used as the name. Note that this name must <b>not</b> conflict with any other name in the ECF SharedObjectContainerFactory 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> - An optional description of the implementation of this extension point</li> +</ul> +<br><p class=code id=dtd><!ELEMENT <a name="e.defaultargument">defaultargument</a> EMPTY></p> +<p class=code id=dtd><!ATTLIST defaultargument</p> +<p class=code id=dtdAttlist>type CDATA #IMPLIED<p class=code id=dtdAttlist>value CDATA #IMPLIED<p class=code id=dtdAttlist>name CDATA #IMPLIED></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +Default argument to be passed to <b>org.eclipse.ecf.core.provider.makeInstance()</b> method. Value of this element (if any) is used to indicate a default value for the given argument</p> +<br> +<ul class=ConfigMarkup id=attlistDesc> +<li><b>type</b> - The fully qualified type of the default argument</li> +<li><b>value</b> - The value for the default argument</li> +<li><b>name</b> - An optional name for the defaultargument element</li> +</ul> +<br><p class=code id=dtd><!ELEMENT <a name="e.property">property</a> EMPTY></p> +<p class=code id=dtd><!ATTLIST property</p> +<p class=code id=dtdAttlist>name CDATA #REQUIRED<p class=code id=dtdAttlist>value CDATA #REQUIRED></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +Property (name,value) associated with SharedObjectContainerDescription</p> +<br> +<ul class=ConfigMarkup id=attlistDesc> +<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 id=header>Examples: </h6>Here's an extension that associates a class org.eclipse.ecf.test.FooContainerFactory with name 'foo' in the ECF <b>SharedObjectContainerFactory</b>: + +<pre> +<p class=code id=tag><extension point=<p class=code id=cstring>"org.eclipse.ecf.containerFactory"</p><p class=code id=tag>></p> + <p class=code id=tag><containerFactory name=<p class=code id=cstring>"foo"</p><p class=code id=tag> class=<p class=code id=cstring>"org.eclipse.ecf.test.FooContainerFactory"</p><p class=code id=tag> description=<p class=code id=cstring>"My container factory"</p><p class=code id=tag>/></p> + <p class=code id=tag><defaultargument type=<p class=code id=cstring>"java.lang.String"</p><p class=code id=tag> value=<p class=code id=cstring>"defaultvalue"</p><p class=code id=tag> name=<p class=code id=cstring>"variablename"</p><p class=code id=tag>/></p> +<p class=code id=tag></extension></p> +</pre> + +Here is some example code to implement this class: + +<pre> +package org.eclipse.ecf.test; + +import org.eclipse.ecf.core.ISharedObjectContainer; +import org.eclipse.ecf.core.SharedObjectContainerInstantiationException; +import org.eclipse.ecf.core.provider.ISharedObjectContainerInstantiator; + +public class FooContainerFactory implements ISharedObjectContainerInstantiator { + + public FooContainerFactory() { + super(); + } + public ISharedObjectContainer makeInstance(SharedObjectContainterDescription description, Class[] argTypes, Object[] args) + throws SharedObjectContainerInstantiationException { + // Create/return instance of FooSharedObjectContainer + // Note that FooSharedObjectContainer class must + // implement ISharedObjectContainer + return new FooSharedObjectContainer(); + } +} +</pre> + +In this example, the given class implements the <b>ISharedObjectContainerInstantiator</b>.makeInstance method by creating and returning a new instance of FooSharedObjectContainer, a class also defined in the extension plugin. As noted in the code, this class must implement <b>ISharedObjectContainer</b>, so that it can successfully be returned from makeInstance. + +<h3>Example Usage of Container by Clients</h3> + +Clients that wish to use the 'foo' container implementation can do so simply by making the following call to create an <b>ISharedObjectContainer</b>: + +<pre> +ISharedObjectContainer newContainer = SharedObjectContainerFactory.makeSharedObjectContainer('foo'); +// Further use of newContainer instance here + +</pre> +<p></p> + +<h6 class=CaptionFigColumn id=header>API Information: </h6>The API for this extension point is provided by the <b>org.eclipse.ecf.core.SharedObjectContainerFactory</b> static methods. Specifically, the 'makeSharedObjectContainer' static methods are to be used by clients. The functionality provided by the extension point mechanism can be used at runtime via the <b>SharedObjectContainerFactory.addDescription(SharedObjectContainerDescription)</b> method. +<p></p> + +<h6 class=CaptionFigColumn id=header>Supplied Implementation: </h6>The supplied implementations of this extension point are: + +org.eclipse.ecf.provider.generic.ContainerInstantiator +<b>TEST</b>: org.eclipse.ecf.test.TestContainer +<p></p> + +<br> +<p class=note id=copyright> +Copyright (c) 2004 Composent, Inc. and others. +All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html. Contributors: Composent, Inc. - initial API and implementation +<p></p> + +</p> +</BODY> +</HTML> diff --git a/framework/bundles/org.eclipse.ecf/doc/org_eclipse_ecf_namespace.html b/framework/bundles/org.eclipse.ecf/doc/org_eclipse_ecf_namespace.html new file mode 100644 index 000000000..5e9216bc9 --- /dev/null +++ b/framework/bundles/org.eclipse.ecf/doc/org_eclipse_ecf_namespace.html @@ -0,0 +1,139 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +<title>ECF Namespace</title> +<style>@import url("file:/c:/eclipse3.1m7/eclipse/plugins/org.eclipse.platform_3.1.0/book.css");</style> +<style>@import url("file:/c:/eclipse3.1m7/eclipse/plugins/org.eclipse.platform.doc.isv_3.1.0/schema.css");</style> +</HEAD> +<BODY> +<H1><CENTER>ECF Namespace</CENTER></H1> +<p></p> +<h6 class=CaptionFigColumn id=header>Identifier: </h6>org.eclipse.ecf.namespace<p></p> +<h6 class=CaptionFigColumn id=header>Since: </h6>1.0.0 +<p></p> + +<p> +<h6 class=CaptionFigColumn id=header>Description: </h6>Extension point that allows other plugins to define new Namespaces for instantiating new types of identity. Plugins can register themselves as 'providers' for namespaces that they define, and will then be called when ECF clients use the <b>org.eclipse.ecf.core.identity.IDFactory.makeID</b> identity factory. +<p> +Plugins implementing this extension point must define an instantiatorClass that implements <b>org.eclipse.ecf.core.identity.provider.IDInstantiator</b>.</p> +<p><h6 class=CaptionFigColumn id=header>Configuration Markup:</h6></p> +<p class=code id=dtd><!ELEMENT <a name="e.extension">extension</a> (<a href="#e.namespace">namespace</a>+)></p> +<p class=code id=dtd><!ATTLIST extension</p> +<p class=code id=dtdAttlist>point CDATA #REQUIRED<p class=code id=dtdAttlist>id CDATA #IMPLIED<p class=code id=dtdAttlist>name CDATA #IMPLIED></p> +<p></p> +<ul class=ConfigMarkup id=attlistDesc> +</ul> +<br><p class=code id=dtd><!ELEMENT <a name="e.namespace">namespace</a> EMPTY></p> +<p class=code id=dtd><!ATTLIST namespace</p> +<p class=code id=dtdAttlist>instantiatorClass CDATA #REQUIRED<p class=code id=dtdAttlist>name CDATA #IMPLIED<p class=code id=dtdAttlist>namespaceClass CDATA #IMPLIED<p class=code id=dtdAttlist>description CDATA #IMPLIED></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +Element allowing extension plugins to define new namespaces</p> +<br> +<ul class=ConfigMarkup id=attlistDesc> +<li><b>instantiatorClass</b> - Required class name. <b>Must</b> implement <b>org.eclipse.identity.provider.IDInstantiator</b></li> +<li><b>name</b> - Optional name for new namespace. If not provided, the name will be assumed to be the fully qualified name of the instantiatorClass. Note that this name must <b>not</b> conflict with any other namespace name in the ECF IDFactory in order to be successfully registered. Care should therefore be taken in selection of a name such that it does not conflict with other implementations.</li> +<li><b>namespaceClass</b> - Optional class name of the Namespace class. Defaults to <b>org.eclipse.ecf.core.identity.Namespace</b>. Implementers may choose to create a subclass of the Namespace class, and can provide that class name here to use that class as the Namespace implementation. Note that the class, if provided, <b>must</b> extend <b>org.eclipse.ecf.core.identity.Namespace</b> and also must implement the two public constructors defined in the Namespace superclass.</li> +<li><b>description</b> - An optional description for the implementation of this extension point</li> +</ul> +<br><p class=code id=dtd><!ELEMENT <a name="e.extension">extension</a> (<a href="#e.namespace">namespace</a>+)></p> +<p class=code id=dtd><!ATTLIST extension</p> +<p class=code id=dtdAttlist>point CDATA #REQUIRED<p class=code id=dtdAttlist>id CDATA #IMPLIED<p class=code id=dtdAttlist>name CDATA #IMPLIED></p> +<p></p> +<ul class=ConfigMarkup id=attlistDesc> +</ul> +<br><p class=code id=dtd><!ELEMENT <a name="e.namespace">namespace</a> EMPTY></p> +<p class=code id=dtd><!ATTLIST namespace</p> +<p class=code id=dtdAttlist>instantiatorClass CDATA #REQUIRED<p class=code id=dtdAttlist>name CDATA #IMPLIED<p class=code id=dtdAttlist>namespaceClass CDATA #IMPLIED<p class=code id=dtdAttlist>description CDATA #IMPLIED></p> +<p></p> +<p class=ConfigMarkup id=elementDesc> +Element allowing extension plugins to define new namespaces</p> +<br> +<ul class=ConfigMarkup id=attlistDesc> +<li><b>instantiatorClass</b> - Required class name. <b>Must</b> implement <b>org.eclipse.identity.provider.IDInstantiator</b></li> +<li><b>name</b> - Optional name for new namespace. If not provided, the name will be assumed to be the fully qualified name of the instantiatorClass. Note that this name must <b>not</b> conflict with any other namespace name in the ECF IDFactory in order to be successfully registered. Care should therefore be taken in selection of a name such that it does not conflict with other implementations.</li> +<li><b>namespaceClass</b> - Optional class name of the Namespace class. Defaults to <b>org.eclipse.ecf.core.identity.Namespace</b>. Implementers may choose to create a subclass of the Namespace class, and can provide that class name here to use that class as the Namespace implementation. Note that the class, if provided, <b>must</b> extend <b>org.eclipse.ecf.core.identity.Namespace</b> and also must implement the two public constructors defined in the Namespace superclass.</li> +<li><b>description</b> - An optional description for the implementation of this extension point</li> +</ul> +<br><h6 class=CaptionFigColumn id=header>Examples: </h6>Here's an extension definition that associates an namespace instantiatorClass with namespace 'testid' in the ECF <b>org.eclipse.ecf.core.identity.IDFactory</b>: + +<pre> + <p class=code id=tag><extension point=<p class=code id=cstring>"org.eclipse.ecf.namespace"</p><p class=code id=tag>></p> + <p class=code id=tag><namespace name=<p class=code id=cstring>"testid"</p><p class=code id=tag> instantiatorClass=<p class=code id=cstring>"org.eclipse.ecf.test.FooIDInstantiator"</p><p class=code id=tag> description=<p class=code id=cstring>"my namespace implementation"</p><p class=code id=tag>/></p> + <p class=code id=tag></extension></p> +</pre> + +Here is some example code to implement this FooIDInstantiator class: + +<pre> +package org.eclipse.ecf.test; + +import org.eclipse.ecf.core.identity.ID; +import org.eclipse.ecf.core.identity.IDInstantiationException; +import org.eclipse.ecf.core.identity.Namespace; + +public class FooIDInstantiator implements + org.eclipse.ecf.core.identity.provider.IDInstantiator { + + public FooIDInstantiator() { + super(); + } + public ID makeInstance(Namespace ns, Class[] argTypes, Object[] args) + throws IDInstantiationException { + return new FooID(ns, (String) args[0]); + } +} +</pre> + +In this example, the given class implements the <b>IDInstantiator</b>.makeInstance method by creating and returning a new instance of FooID, a class also defined in the extension plugin. This class must implement <b>ID</b>, so that it can successfully be returned from makeInstance. + +<h3>Example Usage of IDFactory by Clients</h3> + +Clients that wish to use the 'testid' ID instantiator implementation can do so simply by making the following call to create an <b>IDFactory</b>: + +<pre> +ID newID = IDFactory.makeID('testid','email@emailserver.com'); +// Further use of newID instance here + +</pre> +<p></p> + +<h6 class=CaptionFigColumn id=header>API Information: </h6>The API for this extension point is provided by the <b>org.eclipse.ecf.core.IDFactory</b> static methods. Specifically, the 'makeID' static methods are to be used by clients. The functionality provided by the extension point mechanism can be used at runtime via the <b>IDFactory.addNamespace(Namespace)</b> method. +<p></p> + +<h6 class=CaptionFigColumn id=header>Supplied Implementation: </h6>The following implementations of this extension point are provided by ECF itself: +<p> +StringID -- A namespace of ID instances that are implemented by <b>org.eclipse.ecf.core.identity.StringID</b> +<p>Clients may use this namespace with calls to: +<pre> +ID newID = org.eclipse.ecf.core.identity.IDFactory.makeStringID('idstringvalue'); +</pre> +</p> +</p> +<p> +LongID -- A namespace of ID instances that are implemented by <b>org.eclipse.ecf.core.identity.LongID</b> +<p>Clients may use this namespace with calls to: +<pre> +ID newID = org.eclipse.ecf.core.identity.IDFactory.makeLongID(2004L); +</pre> +</p> +</p> +<p> +GUID -- A namespace of ID instances that are implemented by <b>org.eclipse.ecf.core.identity.GUID</b> +<p>Clients may use this namespace with calls to: +<pre> +ID newID = org.eclipse.ecf.core.identity.IDFactory.makeGUID(16); +</pre> +</p> +</p> +<p></p> + +<br> +<p class=note id=copyright> +Copyright (c) 2004 Composent, Inc. and others. +All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html. Contributors: Composent, Inc. - initial API and implementation +<p></p> + +</p> +</BODY> +</HTML> |