null.
+ * @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 null.
+ * @return true if this ID is equal to the given ID. false otherwise.
+ */
protected abstract boolean namespaceEquals(BaseID o);
+ /**
+ * Called by {@link Namespace#getNameForID(BaseID)}.
+ *
+ * @return String name for this ID. Must not be null. 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
+ * + * namespace.getScheme() + Namespace.SCHEME_SEPARATOR + namespaceGetName(); + *+ */ 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. *
* 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 null.
+ * @param second the second ID. Must not be null.
+ * @return true if this ID is equal to the given ID. false 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 null.
+ * @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 null.
+ * @param second the second id to compare. Must not be null.
+ * @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 null.
+ * @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 null.
*
- * @return String name of Namespace instance
+ * @return String name of Namespace instance. Must not return null, 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 null.
*
- * @return the description associated with this Namespace
+ * @return the description associated with this Namespace. May be null.
*/
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-null scheme
- * identifier.
+ * identifier. Note that the returned scheme should not contain the
+ * Namespace.SCHEME_SEPARATOR (\":\").
*
* @return a String scheme identifier. Must not be null.
*/
--
cgit v1.2.3