ECF Container Factory

Identifier:

org.eclipse.ecf.containerFactory

Since:

0.0.1

Description:

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 (org.eclipse.ecf.core.ContainerFactory).

Plugins using this extension point can define a new implementation of any desired communications protocol, and expose that protocol as an instance of an IContainer. When client requests are made to ECF ContainerFactory to create IContainer instances, those requests will be re-directed to the given IContainer implementer.

Configuration Markup:

<!ELEMENT extension (containerFactory+)>

<!ATTLIST extension

point CDATA #REQUIRED

id CDATA #IMPLIED

name CDATA #IMPLIED>

<!ELEMENT containerFactory EMPTY>

<!ATTLIST containerFactory

class CDATA #REQUIRED

name CDATA #IMPLIED

description CDATA #IMPLIED

server (true | false)

hidden (true | false) >

The container factory extension point. Can optionally contain a list of 'defaultargument' elements that describe the arguments to be passed to provider implementation

class - The fully qualified name of the class implementing the org.eclipse.ecf.core.provider.IContainerInstantiator interface.
name - 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 not 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
description - A description of the container factory suitable for presentation in a user interface.
server - Flag to indicate whether the factory is for creating servers. Default is false.
hidden - Flag for whether the given container factory should be hidden in the user interface. Default is false.

Examples:

Here's an extension that associates a class org.eclipse.ecf.test.FooContainerFactory with name 'foo' in the ECF ContainerFactory:


<extension point="org.eclipse.ecf.containerFactory">
    <containerFactory name="foo" class="org.eclipse.ecf.test.FooInstantiator" description="My container factory"/>
</extension>

Here is some example code to implement this class:


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();
    }
}

In this example, the given class implements the IContainerInstantiator.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 IContainer, so that it can successfully be returned from createInstance.

Example Usage of Container by Clients

Clients that wish to use the 'foo' container implementation can do so simply by making the following call to create an IContainer:


IContainer newContainer = ContainerFactory.getDefault().createContainer('foo'); 
// Further use of newContainer instance here

API Information:

The API for this extension point is provided by the org.eclipse.ecf.core.ContainerFactory.getDefault() 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 ContainerFactory.getDefault().addDescription(ContainerTypeDescription) method. Here is the IContainerFactory interface contract:


/**
 * 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'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
  * <p>
  * <ul>
  * <li>lookup the known ContainerDescriptions to find one of matching name</li>
  * <li>if found, will retrieve or create an IContainerInstantiator for that
  * description</li>
  * <li>Call the IContainerInstantiator.createInstance method to return an
  * instance of IContainer</li>
  * </ul>
  * 
  * @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
  * <p>
  * <ul>
  * <li>lookup the known ContainerDescriptions to find one of matching name</li>
  * <li>if found, will retrieve or create an IContainerInstantiator for that
  * description</li>
  * <li>Call the IContainerInstantiator.createInstance method to return an
  * instance of IContainer</li>
  * </ul>
  * 
  * @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
  * <p>
  * <ul>
  * <li>lookup the known ContainerDescriptions to find one of matching name</li>
  * <li>if found, will retrieve or create an IContainerInstantiator for that
  * description</li>
  * <li>Call the IContainerInstantiator.createInstance method to return an
  * instance of IContainer</li>
  * </ul>
  * 
  * @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);
}

Supplied Implementation:

The supplied implementations of this extension point are: org.eclipse.ecf.provider.generic.GenericContainerInstantiator

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