com.metamatrix.common.namedobject
Class BaseID

java.lang.Object
  com.metamatrix.common.namedobject.BaseID

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.lang.Comparable

Direct Known Subclasses:

ComponentObjectID, ComponentTypeDefnID, ComponentTypeID, PropDefnAllowedValueID

public abstract class BaseID
extends java.lang.Object
implements java.lang.Cloneable, java.lang.Comparable, java.io.Serializable

The BaseID class serves as the abstract base class for identifiers of objects. This class provides the method signatures common to all ID classes as well as the majority of the implementation, and defines an identification name as a list of one or more non-zero length atomic name components delimeted by a '.' (similar to JNDI names).

Because it is possible and likely that MetaMatrix client applications will construct new instances of identifier classes, these ID concepts in this framework are implemented as classes.

These classes are shipped between the client and Configuration Service, so the BaseID class is serializable. To speed serialization and decrease the overhead of shipping BaseID across the network using RMI, several instance variables that may not be required by all users are made transient and recomputed as needed.

Additionally, because IDs are designed to be used as primary keys, the hashCode, equals and compareTo methods are all consistent and optimized for fast performance. This is in part accomplished by caching the hash code value, which is tolerable since all BaseID subclasses are immutable: they cannot be modified after they have been created.

Finally, several key methods that are very commonly used and that will not be overridden in subclasses are marked as final as an inlining hint to the compiler.

See Also:

Serialized Form

Field Summary

protected java.util.List	atomicNames Ordered list of atomic name components.
static java.lang.String	DELIMITER The character that delimits the atomic components of the name
protected java.lang.String	fullName The fully-qualified name of the node.
static java.lang.String	WILDCARD The wildcard character.

Constructor Summary

	BaseID(java.lang.String fullName) Create an instance with the specified full name.
protected	BaseID(java.lang.String fullName, int checkLevel)

Method Summary

java.lang.Object	clone() Return a deep cloned instance of this object.
int	compareTo(java.lang.Object obj) Compares this object to another.
int	compareToByName(java.lang.Object obj) Compares this object to another lexicographically.
protected int	computeHashCode() Return a new hash code value for this instance.
boolean	equals(java.lang.Object obj) Returns true if the specified object is semantically equal to this instance.
java.lang.String	getFullName() Obtain the full name for the object that this identifier represents.
java.lang.String	getName() Obtain the last name component this identifier.
java.lang.String	getNameComponent(int index) Obtain the specified component of the name.
java.util.List	getNameComponents() Obtain the list of atomic name components for this ID.
java.lang.String	getParentFullName() Return the full name of the parent.
int	hashCode() Returns the hash code value for this object.
boolean	hasParent()
int	size() Return the number of atomic name components in this identifier.
java.lang.String	toString() Returns a string representing the current state of the object.
protected void	updateHashCode() Update the currently cached hash code value with a newly computed one.

Methods inherited from class java.lang.Object

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

Field Detail

DELIMITER

public static final java.lang.String DELIMITER

The character that delimits the atomic components of the name

WILDCARD

public static final java.lang.String WILDCARD

The wildcard character.

See Also:

Constant Field Values

fullName

protected java.lang.String fullName

The fully-qualified name of the node. Will never be null.

atomicNames

protected transient java.util.List atomicNames

Ordered list of atomic name components. This is transient to reduce the overhead of passing superfluous information in an RMI request.

Constructor Detail

BaseID

public BaseID(java.lang.String fullName)

Create an instance with the specified full name. The full name must be one or more atomic name components delimited by this class' delimeter character.

Parameters:

fullName - the string form of the full name from which this object is to be created; never null and never zero-length.

Throws:

java.lang.IllegalArgumentException - if the full name is null

BaseID

protected BaseID(java.lang.String fullName,
                 int checkLevel)

Method Detail

getFullName

public final java.lang.String getFullName()

Obtain the full name for the object that this identifier represents.

Returns:

the full name for this identifier.

getName

public java.lang.String getName()

Obtain the last name component this identifier. This last name component is the logical name for the object that this identifier represents.

Returns:

the name for this identifier.

getNameComponent

public final java.lang.String getNameComponent(int index)

Obtain the specified component of the name.

Parameters:

the - index of the atomic name component to return; must be less than the result of the method size in order to be valid.

Returns:

the full name for this identifier.

Throws:

java.lang.IndexOutOfBoundsException - if the index is not valid and is out of the bounds of this name.

getNameComponents

public java.util.List getNameComponents()

Obtain the list of atomic name components for this ID.

Returns:

the unmodifiable list of String objects.

Throws:

java.lang.IndexOutOfBoundsException - if the index is not valid and is out of the bounds of this name.

size

public final int size()

Return the number of atomic name components in this identifier.

Returns:

the size of this identifier.

equals

public boolean equals(java.lang.Object obj)

Returns true if the specified object is semantically equal to this instance. Note: this method is consistent with compareTo().

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object that this instance is to be compared to.

Returns:

whether the object is equal to this object.

compareTo

public int compareTo(java.lang.Object obj)

Compares this object to another. If the specified object is an instance of the BaseID class, then this method compares the name; otherwise, it throws a ClassCastException (as instances are comparable only to instances of the same class). Note: this method is consistent with equals(), meaning that (compare(x, y)==0) == (x.equals(y)).

The algorithm that this method follows is based primarily upon the hash code. When two instances of BaseID, objects A and B, are being compared, this method first compares the (cached) hash code of the two objects. If the two hash codes are not equal, the method returns the difference in the hash codes (namely A.hashCode() - B.hashCode()). If, however, the two hash code values are equivalent, then the two BaseID instances are potentially equivalent, and the full names of the BaseIDs are compared (ignoring case) to determine actual result.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

obj - the object that this instance is to be compared to.

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object, respectively.

Throws:

java.lang.IllegalArgumentException - if the specified object reference is null

java.lang.ClassCastException - if the specified object's type prevents it from being compared to this instance.

compareToByName

public int compareToByName(java.lang.Object obj)

Compares this object to another lexicographically. If the specified object is an instance of the same class, then this method compares the name; otherwise, it throws a ClassCastException (as instances are comparable only to instances of the same class). Note: this method is consistent with equals().

Parameters:

obj - the object that this instance is to be compared to.

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object, respectively.

Throws:

java.lang.IllegalArgumentException - if the specified object reference is null

java.lang.ClassCastException - if the specified object's type prevents it from being compared to this instance.

hashCode

public final int hashCode()

Returns the hash code value for this object.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code value for this object.

toString

public final java.lang.String toString()

Returns a string representing the current state of the object.

Overrides:

toString in class java.lang.Object

Returns:

the string representation of this instance.

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Return a deep cloned instance of this object. Subclasses must override this method.

Overrides:

clone in class java.lang.Object

Returns:

the object that is the clone of this instance.

Throws:

java.lang.CloneNotSupportedException - if this object cannot be cloned (i.e., only objects in Defaults cannot be cloned).

getParentFullName

public java.lang.String getParentFullName()

Return the full name of the parent. This is a convenience method to return the list of atomic name components that excludes this ID's last atomic name component.

Returns:

the full name of the parent, or null if this ID has no parent.

hasParent

public boolean hasParent()

updateHashCode

protected final void updateHashCode()

Update the currently cached hash code value with a newly computed one. This method should be called in any subclass method that updates any field. This includes constructors.

The implementation of this method invokes the computeHashCode method, which is likely overridden in subclasses.

computeHashCode

protected int computeHashCode()

Return a new hash code value for this instance. If subclasses provide additional and non-transient fields, they should override this method using the following template:

 protected int computeHashCode() {
      int result = super.computeHashCode();
      result = HashCodeUtil.hashCode(result, ... );
      result = HashCodeUtil.hashCode(result, ... );
      return result;
 }
 

Any specialized implementation must not rely upon the hashCode method.

Note that this method does not and cannot actually update the hash code value. Rather, this method is called by the updateHashCode method.

Returns:

the new hash code for this instance.