Package org.eclipse.ecf.core.identity

## Class Namespace

- java.lang.Object
- - org.eclipse.ecf.core.identity.Namespace

All Implemented Interfaces:
  `Serializable`, `org.eclipse.core.runtime.IAdaptable`

Direct Known Subclasses:
  `DnsSdNamespace`, `FileTransferNamespace`, `GUID.GUIDNamespace`, `JSLPNamespace`, `LongID.LongNamespace`, `R_OSGiNamespace`, `R_OSGiRemoteServiceNamespace`, `RemoteServiceNamespace`, `RemoteServiceNamespace`, `RestNamespace`, `StringID.StringIDNamespace`, `URIID.URIIDNamespace`, `UuID.UuIDNamespace`, `ZooDiscoveryNamespace`

    public abstract class Namespace
    extends Object
    implements Serializable, org.eclipse.core.runtime.IAdaptable

Namespace base class.

This class and subclasses define a namespace for the creation and management of ID instances. Creation of ID instances is accomplished via the `createInstance(Object[])` method, implemented by subclasses of this Namespace superclass.

All Namespace instances must have a unique name passed to the Namespace upon construction.

Typically Namespace instances are created via plugins that define extensions of the org.eclipse.ecf.namespace extension point. For example, to define a new Namespace subclass XMPPNamespace with name "ecf.xmpp" and add it to the ECF extension registry:

            <extension
                 point="org.eclipse.ecf.namespace">
              <namespace
                    class="XMPPNamespace"
                    name="ecf.xmpp"/>
            </extension>

See Also:
  `ID`, Serialized Form

### Field Summary

Fields
`static String` `SCHEME_SEPARATOR`

### Constructor Summary

Constructors
`Namespace()`
`Namespace​(String name, String desc)`

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
`abstract ID` `createInstance​(Object[] parameters)` Make an instance of this namespace.
`boolean` `equals​(Object other)` Override of Object.equals.
`Object` `getAdapter​(Class adapter)`
`protected int` `getCompareToForObject​(BaseID first, BaseID second)` The default implementation of this method is to call first.namespaceCompareTo(second).
`String` `getDescription()` Get the description, associated with this Namespace.
`protected int` `getHashCodeForID​(BaseID id)` The default implementation of this method is to call id.namespaceHashCode().
`protected String` `getInitStringFromExternalForm​(Object[] args)`
`String` `getName()` Get the name of this namespace.
`protected String` `getNameForID​(BaseID id)` The default implementation of this method is to call id.namespaceGetName().
`abstract String` `getScheme()` Get the primary scheme associated with this namespace.
`Class<?>[][]` `getSupportedParameterTypes()` Get the supported parameter types for IDs created via subsequent calls to `createInstance(Object[])`.
`String[]` `getSupportedSchemes()` Get an array of schemes supported by this Namespace instance.
`int` `hashCode()` Hashcode implementation.
`boolean` `initialize​(String n, String desc)`
`protected boolean` `testIDEquals​(BaseID first, BaseID second)` Test whether two IDs are equal to one another.
`protected String` `toExternalForm​(BaseID id)` The default implementation of this method is to call id.namespaceToExternalForm().
`String` `toString()`

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

### Field Detail

#### SCHEME_SEPARATOR

    public static final String SCHEME_SEPARATOR

See Also:
  Constant Field Values

### Constructor Detail

#### Namespace

    public Namespace()

#### Namespace

    public Namespace​(String name,
                     String desc)

### Method Detail

#### initialize

    public final boolean initialize​(String n,
                                    String desc)

#### equals

    public boolean equals​(Object other)

Override of Object.equals. This equals method returns true if the provided Object is also a Namespace instance, and the names of the two instances match.

Overrides:
  `equals` in class `Object`
Parameters:
  `other` - the Object to test for equality

#### hashCode

    public int hashCode()

Hashcode implementation. Subclasses should not override.

Overrides:
  `hashCode` in class `Object`
Returns:
  int hashCode for this Namespace. Should be unique.

#### testIDEquals

    protected boolean testIDEquals​(BaseID first,
                                   BaseID second)

Test whether two IDs are equal to one another.

Parameters:
  `first` - the first ID. Must not be `null`.
  `second` - the second ID. Must not be `null`.
Returns:
  `true` if this ID is equal to the given ID. `false` otherwise.

#### getNameForID

    protected String getNameForID​(BaseID id)

The default implementation of this method is to call id.namespaceGetName(). Subclasses may override.

Parameters:
  `id` - the ID to get the name for. Must not be `null`.
Returns:
  String that is the unique name for the given id within this Namespace.

#### getCompareToForObject

    protected int getCompareToForObject​(BaseID first,
                                        BaseID second)

The default implementation of this method is to call first.namespaceCompareTo(second). Subclasses may override.

Parameters:
  `first` - the first id to compare. Must not be `null`.
  `second` - the second id to compare. Must not be `null`.
Returns:
  int as specified by `Comparable`.

#### getHashCodeForID

    protected int getHashCodeForID​(BaseID id)

The default implementation of this method is to call id.namespaceHashCode(). Subclasses may override.

Parameters:
  `id` - the id in this Namespace to get the hashcode for. Must not be `null`.
Returns:
  the hashcode for the given id. Returned value must be unique within this process.

#### toExternalForm

    protected String toExternalForm​(BaseID id)

The default implementation of this method is to call id.namespaceToExternalForm(). Subclasses may override.

Parameters:
  `id` - the id in this Namespace to convert to external form.
Returns:
  String that represents the given id in an external form. Note that this external form may at some later time be passed to `createInstance(Object[])` as a single String parameter, and should result in a valid ID instance of the appropriate Namespace.

#### getName

    public String getName()

Get the name of this namespace. Must not return `null`.

Returns:
  String name of Namespace instance. Must not return `null`, and the returned value should be a globally unique name for this Namespace subclass.

#### getDescription

    public String getDescription()

Get the description, associated with this Namespace. The returned value may be `null`.

Returns:
  the description associated with this Namespace. May be `null`.

#### createInstance

    public abstract ID createInstance​(Object[] parameters)
                               throws IDCreateException

Make an instance of this namespace. Namespace subclasses, provided by plugins must implement this method to construct ID instances for the given namespace.

See `getSupportedParameterTypes()` to get information relevant to deciding what parameter types are expected by this method.

Parameters:
  `parameters` - an Object[] of parameters for creating ID instances. May be null.
Returns:
  a non-null ID instance. The class used may extend BaseID or may implement the ID interface directly
Throws:
  `IDCreateException` - if construction fails

#### getScheme

    public abstract String getScheme()

Get the primary scheme associated with this namespace. Subclasses must provide an implementation that returns a non-`null` scheme identifier. Note that the returned scheme should not contain the Namespace.SCHEME_SEPARATOR (\":\").

Returns:
  a String scheme identifier. Must not be `null`.

#### getSupportedSchemes

    public String[] getSupportedSchemes()

Get an array of schemes supported by this Namespace instance. Subclasses may override to support multiple schemes.

Returns:
  String[] of schemes supported by this Namespace. Will not be `null`, but returned array may be of length 0.

#### getSupportedParameterTypes

    public Class<?>[][] getSupportedParameterTypes()

Get the supported parameter types for IDs created via subsequent calls to `createInstance(Object[])`. Callers may use this method to determine the available parameter types, and then create and pass in conforming Object arrays to to `createInstance(Object[])`.

An empty two-dimensional array (new Class[0][0]) is the default returned by this abstract superclass. This means that the Object [] passed to `createInstance(Object[])` will be ignored.

Subsclasses should override this method to specify the parameters that they will accept in calls to `createInstance(Object[])`. The rows of the returned Class array are the acceptable types for a given invocation of createInstance.

Consider the following example:

     public Class[][] getSupportedParameterTypes() {
            return new Class[][] { { String.class }, { String.class, String.class } };
     }

The above means that there are two acceptable values for the Object [] passed into `createInstance(Object[])`: 1) a single String, and 2) two Strings. These would therefore be acceptable as input to createInstance:

            ID newID1 = namespace.createInstance(new Object[] { "Hello" });
            ID newID2 = namespace.createInstance(new Object[] { "Hello", "There"}};

Returns:
  Class [][] an array of class []s. Rows of the returned two-dimensional array define the acceptable parameter types for a single call to `createInstance(Object[])`. If zero-length Class arrays are returned (i.e. Class[0][0]), then Object [] parameters to `createInstance(Object[])` will be ignored.

#### getAdapter

    public Object getAdapter​(Class adapter)

Specified by:
  `getAdapter` in interface `org.eclipse.core.runtime.IAdaptable`

#### getInitStringFromExternalForm

    protected String getInitStringFromExternalForm​(Object[] args)

Since:
  3.1

#### toString

    public String toString()

Overrides:
  `toString` in class `Object`