org.eclipse.ecf.core.identity
Class Namespace

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

All Implemented Interfaces:

java.io.Serializable, org.eclipse.core.runtime.IAdaptable

Direct Known Subclasses:

DnsSdNamespace, FileTransferNamespace, GUID.GUIDNamespace, JSLPNamespace, LocalNamespace, LongID.LongNamespace, R_OSGiNamespace, R_OSGiRemoteServiceNamespace, RemoteServiceNamespace, RestNamespace, RpcNamespace, RSExampleNamespace, SoapNamespace, StringID.StringIDNamespace, TrivialNamespace, XMPPFileNamespace, XMPPNamespace, XMPPRoomNamespace, XMPPSNamespace, ZooDiscoveryNamespace

public abstract class Namespace
extends java.lang.Object
implements java.io.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

static java.lang.String

SCHEME_SEPARATOR

Constructor Summary

Namespace()

Namespace(java.lang.String name, java.lang.String desc)

Method Summary

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

Methods inherited from class java.lang.Object

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

Field Detail

SCHEME_SEPARATOR

public static final java.lang.String SCHEME_SEPARATOR

See Also:

Constant Field Values

Constructor Detail

Namespace

public Namespace()

Namespace

public Namespace(java.lang.String name,
                 java.lang.String desc)

Method Detail

initialize

public final boolean initialize(java.lang.String n,
                                java.lang.String desc)

equals

public boolean equals(java.lang.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 java.lang.Object

Parameters:

other - the Object to test for equality

hashCode

public int hashCode()

Hashcode implementation. Subclasses should not override.

Overrides:

hashCode in class java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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(java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.Object getAdapter(java.lang.Class adapter)

Specified by:

getAdapter in interface org.eclipse.core.runtime.IAdaptable

getInitStringFromExternalForm

protected java.lang.String getInitStringFromExternalForm(java.lang.Object[] args)

Since:

3.1

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object