<!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 Container 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 Container Factory</H1>
<p></p>
<h6 class="CaptionFigColumn SchemaHeader">Identifier: </h6>org.eclipse.ecf.containerFactory<p></p>
<h6 class="CaptionFigColumn SchemaHeader">Since: </h6>0.0.1
<p></p>

<h6 class="CaptionFigColumn SchemaHeader">Description: </h6>This extension allows plugins to register themselves as 'providers' of ECF containers.  Once registered via this extension point, plugins can then provide there own implementations of  IContainer in response to client request of the ECF container factory (<b>org.eclipse.ecf.core.ContainerFactory</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>IContainer</b>.  When client requests are made to ECF ContainerFactory to create <b>IContainer</b> instances, those requests will be re-directed to the given IContainer implementer.<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.containerFactory">containerFactory</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.containerFactory">containerFactory</a> EMPTY&gt;</p>
<p class="code SchemaDtd">&lt;!ATTLIST containerFactory</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</p>
<p class="code SchemaDtdAttlist">server&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(true | false) </p>
<p class="code SchemaDtdAttlist">hidden&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(true | false) &gt;</p>
<p></p>
<p class="ConfigMarkupElementDesc">
The container factory extension point.  Can optionally contain a list of 'defaultargument' elements that describe the arguments to be passed to provider implementation</p>
<br>
<ul class="ConfigMarkupAttlistDesc">
<li><b>class</b> - The fully qualified name of the class implementing the <b>org.eclipse.ecf.core.provider.IContainerInstantiator</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 SharedFactory in order to be successfully registered in the container factory.  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> - A description of the container factory suitable for presentation in a user interface.</li>
<li><b>server</b> - Flag to indicate whether the factory is for creating servers.  Default is false.</li>
<li><b>hidden</b> - Flag for whether the given container factory should be hidden in the user interface.  Default is false.</li>
</ul>
<br><h6 class="CaptionFigColumn SchemaHeader">Examples: </h6>Here's an extension that associates a class org.eclipse.ecf.test.FooContainerFactory with name 'foo' in the ECF <b>ContainerFactory</b>:

<pre class="Example"><span class="code SchemaTag">
&lt;extension point=</span><span class="code SchemaCstring">&quot;org.eclipse.ecf.containerFactory&quot;</span><span class="code SchemaTag">&gt;
    &lt;containerFactory name=</span><span class="code SchemaCstring">&quot;foo&quot;</span><span class="code SchemaTag"> class=</span><span class="code SchemaCstring">&quot;org.eclipse.ecf.test.FooInstantiator&quot;</span><span class="code SchemaTag"> description=</span><span class="code SchemaCstring">&quot;My container factory&quot;</span><span class="code SchemaTag">/&gt;
&lt;/extension&gt;
</span></pre>

Here is some example code to implement this class:

<pre class="Example"><span class="code SchemaTag">
package org.eclipse.ecf.test;

import org.eclipse.ecf.core.IContainer;
import org.eclipse.ecf.core.ContainerInstantiationException;
import org.eclipse.ecf.core.provider.IContainerInstantiator;

public class FooInstantiator implements IContainerInstantiator {

    public FooInstantiator() {
        super();
    }
    public IContainer createInstance(ContainerTypeDescription description, Class[] argTypes, Object[] args)
            throws ContainerInstantiationException {
        // Create/return instance of FooContainer
        // Note that FooContainer class must
        // implement IContainer
        return new FooContainer();
    }
}
</span></pre>

In this example, the given class implements the <b>IContainerInstantiator</b>.createInstance method by creating and returning a new instance of FooInstantiator, a class also defined in the extension plugin.  As noted in the code, this class must implement <b>IContainer</b>, so that it can successfully be returned from createInstance.

<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>IContainer</b>:

<pre class="Example"><span class="code SchemaTag">
IContainer newContainer = ContainerFactory.getDefault().createContainer(&apos;foo&apos;); 
// Further use of newContainer instance here

</span></pre>
<p></p>

<h6 class="CaptionFigColumn SchemaHeader">API Information: </h6>The API for this extension point is provided by the <b>org.eclipse.ecf.core.ContainerFactory.getDefault()</b> methods.  Specifically, the 'createContainer' methods are to be used by clients.  The functionality provided by the extension point mechanism can be used at runtime via the <b>ContainerFactory.getDefault().addDescription(ContainerTypeDescription)</b> method.  Here is the IContainerFactory interface
contract:

<pre class="Example"><span class="code SchemaTag">
/**
 * Container factory contract {@link ContainerFactory} for default
 * implementation.
 */
public interface IContainerFactory {
 /**
  * Add a ContainerTypeDescription to the set of known ContainerDescriptions.
  * 
  * @param description
  *            the ContainerTypeDescription to add to this factory. Must not
  *            be null.
  * @return ContainerTypeDescription the old description of the same name,
  *         null if none found
  */
 public ContainerTypeDescription addDescription(ContainerTypeDescription description);

 /**
  * Get a collection of the ContainerDescriptions currently known to this
  * factory. This allows clients to query the factory to determine what if
  * any other ContainerDescriptions are currently registered with the
  * factory, and if so, what they are.
  * 
  * @return List of ContainerTypeDescription instances
  */
 public List /* ContainerTypeDescription */ getDescriptions();

 /**
  * Check to see if a given named description is already contained by this
  * factory
  * 
  * @param description
  *            the ContainerTypeDescription to look for
  * @return true if description is already known to factory, false otherwise
  */
 public boolean containsDescription(ContainerTypeDescription description);

 /**
  * Get the known ContainerTypeDescription given it&apos;s name.
  * 
  * @param name
  *            the name to use as key to find ContainerTypeDescription
  * @return ContainerTypeDescription found. Null if not found.
  */
 public ContainerTypeDescription getDescriptionByName(String name);

 /**
  * Make IContainer instance. Given a ContainerTypeDescription 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 ContainerDescriptions to find one of matching name&lt;/li&gt;
  * &lt;li&gt;if found, will retrieve or create an IContainerInstantiator for that
  * description&lt;/li&gt;
  * &lt;li&gt;Call the IContainerInstantiator.createInstance method to return an
  * instance of IContainer&lt;/li&gt;
  * &lt;/ul&gt;
  * 
  * @param description
  *            the ContainerTypeDescription to use to create the instance
  * @param parameters
  *            an Object [] of parameters passed to the createInstance method
  *            of the IContainerInstantiator
  * @return a valid instance of IContainer
  * @throws ContainerCreateException
  */
 public IContainer createContainer(ContainerTypeDescription description,
   Object[] parameters) throws ContainerCreateException;

 /**
  * Make IContainer instance. Given a ContainerTypeDescription name, this
  * method will
  * &lt;p&gt;
  * &lt;ul&gt;
  * &lt;li&gt;lookup the known ContainerDescriptions to find one of matching name&lt;/li&gt;
  * &lt;li&gt;if found, will retrieve or create an IContainerInstantiator for that
  * description&lt;/li&gt;
  * &lt;li&gt;Call the IContainerInstantiator.createInstance method to return an
  * instance of IContainer&lt;/li&gt;
  * &lt;/ul&gt;
  * 
  * @param descriptionName
  *            the ContainerTypeDescription name to lookup
  * @return a valid instance of IContainer
  * @throws ContainerCreateException
  */
 public IContainer createContainer(String descriptionName)
   throws ContainerCreateException;

 /**
  * Make IContainer instance. Given a ContainerTypeDescription name, this
  * method will
  * &lt;p&gt;
  * &lt;ul&gt;
  * &lt;li&gt;lookup the known ContainerDescriptions to find one of matching name&lt;/li&gt;
  * &lt;li&gt;if found, will retrieve or create an IContainerInstantiator for that
  * description&lt;/li&gt;
  * &lt;li&gt;Call the IContainerInstantiator.createInstance method to return an
  * instance of IContainer&lt;/li&gt;
  * &lt;/ul&gt;
  * 
  * @param descriptionName
  *            the ContainerTypeDescription name to lookup
  * @param parameters
  *            the Object [] of parameters passed to the
  *            IContainerInstantiator.createInstance method
  * @return a valid instance of IContainer
  * @throws ContainerCreateException
  */
 public IContainer createContainer(String descriptionName, Object[] parameters)
   throws ContainerCreateException;

 /**
  * Remove given description from set known to this factory.
  * 
  * @param description
  *            the ContainerTypeDescription to remove
  * @return the removed ContainerTypeDescription, null if nothing removed
  */
 public ContainerTypeDescription removeDescription(
   ContainerTypeDescription description);
}
</span></pre>
<p></p>

<h6 class="CaptionFigColumn SchemaHeader">Supplied Implementation: </h6>The supplied implementations of this extension point are:

org.eclipse.ecf.provider.generic.GenericContainerInstantiator
<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>