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
Modifier and Type
Field
Description
`static final String`
`SCHEME_SEPARATOR`

## Constructor Summary

Constructors
Constructor
Description
`Namespace()`
`Namespace(String name, String desc)`

## Method Summary

Modifier and Type
Method
Description
`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.
`final 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 Details

### SCHEME_SEPARATOR

public static final String SCHEME_SEPARATOR

See Also:
  - Constant Field Values

## Constructor Details

### Namespace

public Namespace()

### Namespace

public Namespace(String name, String desc)

## Method Details

### 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`