* The components of a compound name are numbered. The indexes of a * compound name with N components range from 0 up to, but not including, N. * This range may be written as [0,N). * The most significant component is at index 0. * An empty compound name has no components. * *
* The string form of the compound name follows the syntax described above. * When the components of the compound name are turned into their * string representation, the reserved syntax rules described above are * applied (e.g. embedded separators are escaped or quoted) * so that when the same string is parsed, it will yield the same components * of the original compound name. * *
syntax.
*/
public CompoundName(String n, Properties syntax) throws InvalidNameException {
if (syntax == null) {
throw new NullPointerException();
}
mySyntax = syntax;
impl = new NameImpl(syntax, n);
}
/**
* Generates the string representation of this compound name, using
* the syntax rules of the compound name. The syntax rules
* are described in the class description.
* An empty component is represented by an empty string.
*
* The string representation thus generated can be passed to
* the CompoundName constructor with the same syntax properties
* to create a new equivalent compound name.
*
* @return A non-null string representation of this compound name.
*/
public String toString() {
return (impl.toString());
}
/**
* Determines whether obj is syntactically equal to this compound name.
* If obj is null or not a CompoundName, false is returned.
* Two compound names are equal if each component in one is "equal"
* to the corresponding component in the other.
** Equality is also defined in terms of the syntax of this compound name. * The default implementation of CompoundName uses the syntax properties * jndi.syntax.ignorecase and jndi.syntax.trimblanks when comparing * two components for equality. If case is ignored, two strings * with the same sequence of characters but with different cases * are considered equal. If blanks are being trimmed, leading and trailing * blanks are ignored for the purpose of the comparison. *
* Both compound names must have the same number of components. *
* Implementation note: Currently the syntax properties of the two compound * names are not compared for equality. They might be in the future. * * @param obj The possibly null object to compare against. * @return true if obj is equal to this compound name, false otherwise. * @see #compareTo(java.lang.Object obj) */ public boolean equals(Object obj) { // %%% check syntax too? return (obj != null && obj instanceof CompoundName && impl.equals(((CompoundName)obj).impl)); } /** * Computes the hash code of this compound name. * The hash code is the sum of the hash codes of the "canonicalized" * forms of individual components of this compound name. * Each component is "canonicalized" according to the * compound name's syntax before its hash code is computed. * For a case-insensitive name, for example, the uppercased form of * a name has the same hash code as its lowercased equivalent. * * @return An int representing the hash code of this name. */ public int hashCode() { return impl.hashCode(); } /** * Creates a copy of this compound name. * Changes to the components of this compound name won't * affect the new copy and vice versa. * The clone and this compound name share the same syntax. * * @return A non-null copy of this compound name. */ public Object clone() { return (new CompoundName(getAll(), mySyntax)); } /** * Compares this CompoundName with the specified Object for order. * Returns a * negative integer, zero, or a positive integer as this Name is less * than, equal to, or greater than the given Object. *
* If obj is null or not an instance of CompoundName, ClassCastException * is thrown. *
* See equals() for what it means for two compound names to be equal. * If two compound names are equal, 0 is returned. *
* Ordering of compound names depend on the syntax of the compound name. * By default, they follow lexicographical rules for string comparison * with the extension that this applies to all the components in the * compound name and that comparison of individual components is * affected by the jndi.syntax.ignorecase and jndi.syntax.trimblanks * properties, identical to how they affect equals(). * If this compound name is "lexicographically" lesser than obj, * a negative number is returned. * If this compound name is "lexicographically" greater than obj, * a positive number is returned. *
* Implementation note: Currently the syntax properties of the two compound
* names are not compared when checking order. They might be in the future.
* @param obj The non-null object to compare against.
* @return a negative integer, zero, or a positive integer as this Name
* is less than, equal to, or greater than the given Object.
* @exception ClassCastException if obj is not a CompoundName.
* @see #equals(java.lang.Object)
*/
public int compareTo(Object obj) {
if (!(obj instanceof CompoundName)) {
throw new ClassCastException("Not a CompoundName");
}
return impl.compareTo(((CompoundName)obj).impl);
}
/**
* Retrieves the number of components in this compound name.
*
* @return The nonnegative number of components in this compound name.
*/
public int size() {
return (impl.size());
}
/**
* Determines whether this compound name is empty.
* A compound name is empty if it has zero components.
*
* @return true if this compound name is empty, false otherwise.
*/
public boolean isEmpty() {
return (impl.isEmpty());
}
/**
* Retrieves the components of this compound name as an enumeration
* of strings.
* The effects of updates to this compound name on this enumeration
* is undefined.
*
* @return A non-null enumeration of the components of this
* compound name. Each element of the enumeration is of class String.
*/
public Enumeration
* Implementation note: Currently the syntax properties of n
* are not used when doing the comparison. They might be in the future.
* @param n The possibly null compound name to check.
* @return true if n is a CompoundName and
* is a prefix of this compound name, false otherwise.
*/
public boolean startsWith(Name n) {
if (n instanceof CompoundName) {
return (impl.startsWith(n.size(), n.getAll()));
} else {
return false;
}
}
/**
* Determines whether a compound name is a suffix of this compound name.
* A compound name 'n' is a suffix if it is equal to
* getSuffix(size()-n.size())--in other words, this
* compound name ends with 'n'.
* If n is null or not a compound name, false is returned.
*
* Implementation note: Currently the syntax properties of n
* are not used when doing the comparison. They might be in the future.
* @param n The possibly null compound name to check.
* @return true if n is a CompoundName and
* is a suffix of this compound name, false otherwise.
*/
public boolean endsWith(Name n) {
if (n instanceof CompoundName) {
return (impl.endsWith(n.size(), n.getAll()));
} else {
return false;
}
}
/**
* Adds the components of a compound name -- in order -- to the end of
* this compound name.
*
* Implementation note: Currently the syntax properties of suffix
* is not used or checked. They might be in the future.
* @param suffix The non-null components to add.
* @return The updated CompoundName, not a new one. Cannot be null.
* @exception InvalidNameException If suffix is not a compound name,
* or if the addition of the components violates the syntax
* of this compound name (e.g. exceeding number of components).
*/
public Name addAll(Name suffix) throws InvalidNameException {
if (suffix instanceof CompoundName) {
impl.addAll(suffix.getAll());
return this;
} else {
throw new InvalidNameException("Not a compound name: " +
suffix.toString());
}
}
/**
* Adds the components of a compound name -- in order -- at a specified
* position within this compound name.
* Components of this compound name at or after the index of the first
* new component are shifted up (away from index 0)
* to accommodate the new components.
*
* Implementation note: Currently the syntax properties of suffix
* is not used or checked. They might be in the future.
*
* @param n The non-null components to add.
* @param posn The index in this name at which to add the new
* components. Must be in the range [0,size()].
* @return The updated CompoundName, not a new one. Cannot be null.
* @exception ArrayIndexOutOfBoundsException
* If posn is outside the specified range.
* @exception InvalidNameException If n is not a compound name,
* or if the addition of the components violates the syntax
* of this compound name (e.g. exceeding number of components).
*/
public Name addAll(int posn, Name n) throws InvalidNameException {
if (n instanceof CompoundName) {
impl.addAll(posn, n.getAll());
return this;
} else {
throw new InvalidNameException("Not a compound name: " +
n.toString());
}
}
/**
* Adds a single component to the end of this compound name.
*
* @param comp The non-null component to add.
* @return The updated CompoundName, not a new one. Cannot be null.
* @exception InvalidNameException If adding comp at end of the name
* would violate the compound name's syntax.
*/
public Name add(String comp) throws InvalidNameException{
impl.add(comp);
return this;
}
/**
* Adds a single component at a specified position within this
* compound name.
* Components of this compound name at or after the index of the new
* component are shifted up by one (away from index 0)
* to accommodate the new component.
*
* @param comp The non-null component to add.
* @param posn The index at which to add the new component.
* Must be in the range [0,size()].
* @exception ArrayIndexOutOfBoundsException
* If posn is outside the specified range.
* @return The updated CompoundName, not a new one. Cannot be null.
* @exception InvalidNameException If adding comp at the specified position
* would violate the compound name's syntax.
*/
public Name add(int posn, String comp) throws InvalidNameException{
impl.add(posn, comp);
return this;
}
/**
* Deletes a component from this compound name.
* The component of this compound name at position 'posn' is removed,
* and components at indices greater than 'posn'
* are shifted down (towards index 0) by one.
*
* @param posn The index of the component to delete.
* Must be in the range [0,size()).
* @return The component removed (a String).
* @exception ArrayIndexOutOfBoundsException
* If posn is outside the specified range (includes case where
* compound name is empty).
* @exception InvalidNameException If deleting the component
* would violate the compound name's syntax.
*/
public Object remove(int posn) throws InvalidNameException {
return impl.remove(posn);
}
/**
* Overridden to avoid implementation dependency.
* @serialData The syntax Properties, followed by
* the number of components (an int), and the individual
* components (each a String).
*/
private void writeObject(java.io.ObjectOutputStream s)
throws java.io.IOException {
s.writeObject(mySyntax);
s.writeInt(size());
Enumeration