# ECF Namespace

###### Identifier:

org.eclipse.ecf.identity.namespace

###### Since:

0.4.0

###### Description:

Extension point that allows other plugins to define new Namespaces. Namespaces are used by the IDFactory for creating new ID instances. Plugins may define extension Namespace implementation, which will then be used to construct ID instances within than Namespace when clients use the default ECF identity factory (accessed via org.eclipse.ecf.core.identity.IDFactory.getDefault()).

Plugins implementing this extension point must define a Namespace class that extends org.eclipse.ecf.core.identity.Namespace. The class attribute of the namespace extension must provide a valid Namespace subclass. The name attribute defines the namespace name. If the name attribute is not present, then the Namespace class will be used as the Namespace name. The optional description attribute is an optional arbitrary description for the Namespace.

###### Configuration Markup:

<!ELEMENT extension (namespace+)>

<!ATTLIST extension

point CDATA #REQUIRED

id CDATA #IMPLIED

name CDATA #IMPLIED

>

<!ELEMENT namespace EMPTY>

<!ATTLIST namespace

name CDATA #IMPLIED

class CDATA #REQUIRED

description CDATA #IMPLIED

>

Element allowing plugins to define new ECF Namespaces. Plugins wishing to define new Namespaces must provide an extension of this extension point.

- name - Optional name for new Namespace. If not provided, the name will be assumed to be the value provided by the 'class' attribute for this extension point. Note that this name must not 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 namespace name such that it does not conflict with other implementations.
- class - The fully qualified name of a class that extends org.eclipse.ecf.core.identity.Namespace.
- description - An optional description for the Namespace extension

###### Examples:

Here's an extension definition that associates an namespace class with namespace 'testid':

       <extension point="org.eclipse.ecf.identity.namespace">
          <namespace name="testnamespace" class="org.eclipse.ecf.test.FooNamespace" description="my namespace implementation"/>
       </extension>

Here is some example code to implement this FooNamespace class:

    package org.eclipse.ecf.test;

    import org.eclipse.ecf.core.identity.ID;
    import org.eclipse.ecf.core.identity.IDCreateException;
    import org.eclipse.ecf.core.identity.Namespace;

    public class FooNamespace extends
            org.eclipse.ecf.core.identity.Namespace {

        public ID createInstance(Class[] argTypes, Object[] args)
                throws IDCreateException {
            return new FooID((String) args[0]);
        }
    }

In this example, the FooNamespace class implements the abstract Namesapce.createInstance method by creating and returning a new instance of FooID, a class also defined by the extension plugin. This class must implement ID, so that it can successfully be returned from the Namespace.createInstance call.

### Example Usage of IDFactory by Clients

Clients that wish to use the 'testnamespace' Namespace implementation can do so simply by making the following call to create an IDFactory:

    ID newID = IDFactory.getDefault().createID("testnamespace","email@emailserver.com");

Another example would be:

    ID newID = IDFactory.getDefault().createID(new URI("testnamespace:email@emailserver.com"));

###### API Information:

The client API for this extension point is provided by the org.eclipse.ecf.core.IIDFactory.createID methods. A valid IIDFactory is provided by the by the static org.eclipse.ecf.core.identityIDFactory.getDefault() method.

###### Supplied Implementation:

The following implementations of this extension point are provided by ECF itself:

StringID -- A namespace of ID instances that are implemented by org.eclipse.ecf.core.identity.StringID

Clients may use this namespace with calls to:

    ID newID = org.eclipse.ecf.core.identity.IDFactory.createStringID('idstringvalue');

LongID -- A namespace of ID instances that are implemented by org.eclipse.ecf.core.identity.LongID

Clients may use this namespace with calls to:

    ID newID = org.eclipse.ecf.core.identity.IDFactory.createLongID(2004L);

GUID -- A namespace of ID instances that are implemented by org.eclipse.ecf.core.identity.GUID

Clients may use this namespace with calls to:

    ID newID = org.eclipse.ecf.core.identity.IDFactory.createGUID(16);

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