diff options
2 files changed, 78 insertions, 5 deletions
diff --git a/framework/bundles/org.eclipse.ecf.identity/src/org/eclipse/ecf/core/identity/BaseID.java b/framework/bundles/org.eclipse.ecf.identity/src/org/eclipse/ecf/core/identity/BaseID.java index c386cb8f1..c4378c6c9 100644 --- a/framework/bundles/org.eclipse.ecf.identity/src/org/eclipse/ecf/core/identity/BaseID.java +++ b/framework/bundles/org.eclipse.ecf.identity/src/org/eclipse/ecf/core/identity/BaseID.java @@ -95,14 +95,43 @@ public abstract class BaseID implements ID { return namespace.toExternalForm(this); } + /** + * Called by {@link Namespace#getCompareToForObject(BaseID, BaseID)}. + * + * @param o the other ID to compare to. Will not be <code>null</code>. + * @return the appropriate value as per {@link Comparable} contract. + */ protected abstract int namespaceCompareTo(BaseID o); + /** + * Called by {@link Namespace#testIDEquals(BaseID, BaseID)}. + * @param o the other ID to test against. May be <code>null</code>. + * @return <code>true</code> if this ID is equal to the given ID. <code>false</code> otherwise. + */ protected abstract boolean namespaceEquals(BaseID o); + /** + * Called by {@link Namespace#getNameForID(BaseID)}. + * + * @return String name for this ID. Must not be <code>null</code>. Value returned should be unique within this Namespace. + */ protected abstract String namespaceGetName(); + /** + * Called by {@link Namespace#getHashCodeForID(BaseID)}. + * + * @return int hashCode for this ID. Returned value must be unique within this process. + */ protected abstract int namespaceHashCode(); + /** + * Called by {@link Namespace#toExternalForm(BaseID)}. + * + * @return String that represents this ID. Default implementation is to return + * <pre> + * namespace.getScheme() + Namespace.SCHEME_SEPARATOR + namespaceGetName(); + * </pre> + */ protected String namespaceToExternalForm() { return namespace.getScheme() + Namespace.SCHEME_SEPARATOR + namespaceGetName(); } diff --git a/framework/bundles/org.eclipse.ecf.identity/src/org/eclipse/ecf/core/identity/Namespace.java b/framework/bundles/org.eclipse.ecf.identity/src/org/eclipse/ecf/core/identity/Namespace.java index 74e69bd93..0378a8221 100644 --- a/framework/bundles/org.eclipse.ecf.identity/src/org/eclipse/ecf/core/identity/Namespace.java +++ b/framework/bundles/org.eclipse.ecf.identity/src/org/eclipse/ecf/core/identity/Namespace.java @@ -13,7 +13,7 @@ import org.eclipse.core.runtime.*; import org.eclipse.ecf.internal.core.identity.Activator; /** - * Namespace base class + * Namespace base class. * <p> * This class and subclasses define a namespace for the creation and management * of ID instances. Creation of ID instances is accomplished via the @@ -87,10 +87,21 @@ public abstract class Namespace implements Serializable, IAdaptable { return ((Namespace) other).name.equals(name); } + /** + * Hashcode implementation. Subclasses should not override. + * + * @return int hashCode for this Namespace. Should be unique. + */ public int hashCode() { return hashCode; } + /** + * Test whether two IDs are equal to one another. + * @param first the first ID. Must not be <code>null</code>. + * @param second the second ID. Must not be <code>null</code>. + * @return <code>true</code> if this ID is equal to the given ID. <code>false</code> otherwise. + */ protected boolean testIDEquals(BaseID first, BaseID second) { // First check that namespaces are the same and non-null Namespace sn = second.getNamespace(); @@ -99,18 +110,49 @@ public abstract class Namespace implements Serializable, IAdaptable { return first.namespaceEquals(second); } + /** + * The default implementation of this method is to call id.namespaceGetName(). Subclasses may + * override. + * + * @param id the ID to get the name for. Must not be <code>null</code>. + * @return String that is the unique name for the given id within this Namespace. + */ protected String getNameForID(BaseID id) { return id.namespaceGetName(); } + /** + * The default implementation of this method is to call first.namespaceCompareTo(second). Subclasses may + * override. + * + * @param first the first id to compare. Must not be <code>null</code>. + * @param second the second id to compare. Must not be <code>null</code>. + * @return int as specified by {@link Comparable}. + */ protected int getCompareToForObject(BaseID first, BaseID second) { return first.namespaceCompareTo(second); } + /** + * The default implementation of this method is to call id.namespaceHashCode(). Subclasses may + * override. + * + * @param id the id in this Namespace to get the hashcode for. Must not be <code>null</code>. + * @return the hashcode for the given id. Returned value must be unique within this process. + */ protected int getHashCodeForID(BaseID id) { return id.namespaceHashCode(); } + /** + * The default implementation of this method is to call id.namespaceToExternalForm(). Subclasses may + * override. + * + * @param id the id in this Namespace to convert to external form. + * @return String that represents the given id in an external form. Note that + * this external form may at some later time be passed to {@link #createInstance(Object[])} as a single + * String parameter, and should result in a valid ID instance of the appropriate Namespace. + */ protected String toExternalForm(BaseID id) { return id.namespaceToExternalForm(); } @@ -118,7 +160,8 @@ public abstract class Namespace implements Serializable, IAdaptable { /** * Get the name of this namespace. Must not return <code>null</code>. * - * @return String name of Namespace instance + * @return String name of Namespace instance. Must not return <code>null</code>, and + * the returned value should be a globally unique name for this Namespace subclass. * */ public String getName() { @@ -127,9 +170,9 @@ public abstract class Namespace implements Serializable, IAdaptable { /** * Get the description, associated with this Namespace. The returned value - * may be null. + * may be <code>null</code>. * - * @return the description associated with this Namespace + * @return the description associated with this Namespace. May be <code>null</code>. */ public String getDescription() { return description; @@ -160,7 +203,8 @@ public abstract class Namespace implements Serializable, IAdaptable { /** * Get the primary scheme associated with this namespace. Subclasses must * provide an implementation that returns a non-<code>null</code> scheme - * identifier. + * identifier. Note that the returned scheme should <b>not</b> contain the + * Namespace.SCHEME_SEPARATOR (\":\"). * * @return a String scheme identifier. Must not be <code>null</code>. */ |