com.metamatrix.metadata.runtime.api
Interface MetadataID

All Superinterfaces:

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

All Known Subinterfaces:

DataTypeID, ElementID, GroupID, KeyID, ModelID, ProcedureID, VirtualDatabaseID

All Known Implementing Classes:

BasicDataTypeID, BasicElementID, BasicGroupID, BasicKeyID, BasicMetadataID, BasicModelID, BasicProcedureID, BasicVirtualDatabaseID

public interface MetadataID
extends java.lang.Cloneable, java.lang.Comparable, java.io.Serializable

The MetadataID class serves as the interface 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).

These classes are shipped between the client and RuntimeMetadata, so the MetadataID class is serializable. To speed serialization and decrease the overhead of shipping MetadataID 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 MetadataID 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.

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.
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.
java.lang.String	getPath() Obtain the path for this component.
int	hashCode() Returns the hash code value for this object.
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.

Method Detail

getFullName

java.lang.String getFullName()

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

Returns:

the full name for this identifier.

getName

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.

getPath

java.lang.String getPath()

Obtain the path for this component.

Returns:

the path

getNameComponent

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

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

int size()

Return the number of atomic name components in this identifier.

Returns:

the size of this identifier.

equals

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

int compareTo(java.lang.Object obj)

Compares this object to another. If the specified object is an instance of the MetadataID 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 MetadataID, 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 MetadataID 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

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

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

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

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

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

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

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.