--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/javax/naming/CompoundName.java Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,624 @@
+/*
+ * Copyright 1999-2004 Sun Microsystems, Inc. All Rights Reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Sun designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Sun in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ * CA 95054 USA or visit www.sun.com if you need additional information or
+ * have any questions.
+ */
+
+package javax.naming;
+
+import java.util.Enumeration;
+import java.util.Properties;
+
+/**
+ * This class represents a compound name -- a name from
+ * a hierarchical name space.
+ * Each component in a compound name is an atomic name.
+ * <p>
+ * 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.
+ *<p>
+ * <h4>Compound Name Syntax</h4>
+ * The syntax of a compound name is specified using a set of properties:
+ *<dl>
+ * <dt>jndi.syntax.direction
+ * <dd>Direction for parsing ("right_to_left", "left_to_right", "flat").
+ * If unspecified, defaults to "flat", which means the namespace is flat
+ * with no hierarchical structure.
+ *
+ * <dt>jndi.syntax.separator
+ * <dd>Separator between atomic name components.
+ * Required unless direction is "flat".
+ *
+ * <dt>jndi.syntax.ignorecase
+ * <dd>If present, "true" means ignore the case when comparing name
+ * components. If its value is not "true", or if the property is not
+ * present, case is considered when comparing name components.
+ *
+ * <dt>jndi.syntax.escape
+ * <dd>If present, specifies the escape string for overriding separator,
+ * escapes and quotes.
+ *
+ * <dt>jndi.syntax.beginquote
+ * <dd>If present, specifies the string delimiting start of a quoted string.
+ *
+ * <dt>jndi.syntax.endquote
+ * <dd>String delimiting end of quoted string.
+ * If present, specifies the string delimiting the end of a quoted string.
+ * If not present, use syntax.beginquote as end quote.
+ * <dt>jndi.syntax.beginquote2
+ * <dd>Alternative set of begin/end quotes.
+ *
+ * <dt>jndi.syntax.endquote2
+ * <dd>Alternative set of begin/end quotes.
+ *
+ * <dt>jndi.syntax.trimblanks
+ * <dd>If present, "true" means trim any leading and trailing whitespaces
+ * in a name component for comparison purposes. If its value is not
+ * "true", or if the property is not present, blanks are significant.
+ * <dt>jndi.syntax.separator.ava
+ * <dd>If present, specifies the string that separates
+ * attribute-value-assertions when specifying multiple attribute/value
+ * pairs. (e.g. "," in age=65,gender=male).
+ * <dt>jndi.syntax.separator.typeval
+ * <dd>If present, specifies the string that separators attribute
+ * from value (e.g. "=" in "age=65")
+ *</dl>
+ * These properties are interpreted according to the following rules:
+ *<ol>
+ *<li>
+ * In a string without quotes or escapes, any instance of the
+ * separator delimits two atomic names. Each atomic name is referred
+ * to as a <em>component</em>.
+ *<li>
+ * A separator, quote or escape is escaped if preceded immediately
+ * (on the left) by the escape.
+ *<li>
+ * If there are two sets of quotes, a specific begin-quote must be matched
+ * by its corresponding end-quote.
+ *<li>
+ * A non-escaped begin-quote which precedes a component must be
+ * matched by a non-escaped end-quote at the end of the component.
+ * A component thus quoted is referred to as a
+ * <em>quoted component</em>. It is parsed by
+ * removing the being- and end- quotes, and by treating the intervening
+ * characters as ordinary characters unless one of the rules involving
+ * quoted components listed below applies.
+ *<li>
+ * Quotes embedded in non-quoted components are treated as ordinary strings
+ * and need not be matched.
+ *<li>
+ * A separator that is escaped or appears between non-escaped
+ * quotes is treated as an ordinary string and not a separator.
+ *<li>
+ * An escape string within a quoted component acts as an escape only when
+ * followed by the corresponding end-quote string.
+ * This can be used to embed an escaped quote within a quoted component.
+ *<li>
+ * An escaped escape string is not treated as an escape string.
+ *<li>
+ * An escape string that does not precede a meta string (quotes or separator)
+ * and is not at the end of a component is treated as an ordinary string.
+ *<li>
+ * A leading separator (the compound name string begins with
+ * a separator) denotes a leading empty atomic component (consisting
+ * of an empty string).
+ * A trailing separator (the compound name string ends with
+ * a separator) denotes a trailing empty atomic component.
+ * Adjacent separators denote an empty atomic component.
+ *</ol>
+ * <p>
+ * 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.
+ *<p>
+ *<h4>Multithreaded Access</h4>
+ * A <tt>CompoundName</tt> instance is not synchronized against concurrent
+ * multithreaded access. Multiple threads trying to access and modify a
+ * <tt>CompoundName</tt> should lock the object.
+ *
+ * @author Rosanna Lee
+ * @author Scott Seligman
+ * @since 1.3
+ */
+
+public class CompoundName implements Name {
+
+ /**
+ * Implementation of this compound name.
+ * This field is initialized by the constructors and cannot be null.
+ * It should be treated as a read-only variable by subclasses.
+ */
+ protected transient NameImpl impl;
+ /**
+ * Syntax properties for this compound name.
+ * This field is initialized by the constructors and cannot be null.
+ * It should be treated as a read-only variable by subclasses.
+ * Any necessary changes to mySyntax should be made within constructors
+ * and not after the compound name has been instantiated.
+ */
+ protected transient Properties mySyntax;
+
+ /**
+ * Constructs a new compound name instance using the components
+ * specified in comps and syntax. This protected method is intended to be
+ * to be used by subclasses of CompoundName when they override
+ * methods such as clone(), getPrefix(), getSuffix().
+ *
+ * @param comps A non-null enumeration of the components to add.
+ * Each element of the enumeration is of class String.
+ * The enumeration will be consumed to extract its
+ * elements.
+ * @param syntax A non-null properties that specify the syntax of
+ * this compound name. See class description for
+ * contents of properties.
+ */
+ protected CompoundName(Enumeration<String> comps, Properties syntax) {
+ if (syntax == null) {
+ throw new NullPointerException();
+ }
+ mySyntax = syntax;
+ impl = new NameImpl(syntax, comps);
+ }
+
+ /**
+ * Constructs a new compound name instance by parsing the string n
+ * using the syntax specified by the syntax properties supplied.
+ *
+ * @param n The non-null string to parse.
+ * @param syntax A non-null list of properties that specify the syntax of
+ * this compound name. See class description for
+ * contents of properties.
+ * @exception InvalidNameException If 'n' violates the syntax specified
+ * by <code>syntax</code>.
+ */
+ 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.
+ *<p>
+ * 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.
+ *<p>
+ * Both compound names must have the same number of components.
+ *<p>
+ * 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.
+ * <p>
+ * If obj is null or not an instance of CompoundName, ClassCastException
+ * is thrown.
+ * <p>
+ * See equals() for what it means for two compound names to be equal.
+ * If two compound names are equal, 0 is returned.
+ *<p>
+ * 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.
+ *<p>
+ * 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<String> getAll() {
+ return (impl.getAll());
+ }
+
+ /**
+ * Retrieves a component of this compound name.
+ *
+ * @param posn The 0-based index of the component to retrieve.
+ * Must be in the range [0,size()).
+ * @return The component at index posn.
+ * @exception ArrayIndexOutOfBoundsException if posn is outside the
+ * specified range.
+ */
+ public String get(int posn) {
+ return (impl.get(posn));
+ }
+
+ /**
+ * Creates a compound name whose components consist of a prefix of the
+ * components in this compound name.
+ * The result and this compound name share the same syntax.
+ * Subsequent changes to
+ * this compound name does not affect the name that is returned and
+ * vice versa.
+ *
+ * @param posn The 0-based index of the component at which to stop.
+ * Must be in the range [0,size()].
+ * @return A compound name consisting of the components at indexes in
+ * the range [0,posn).
+ * @exception ArrayIndexOutOfBoundsException
+ * If posn is outside the specified range.
+ */
+ public Name getPrefix(int posn) {
+ Enumeration comps = impl.getPrefix(posn);
+ return (new CompoundName(comps, mySyntax));
+ }
+
+ /**
+ * Creates a compound name whose components consist of a suffix of the
+ * components in this compound name.
+ * The result and this compound name share the same syntax.
+ * Subsequent changes to
+ * this compound name does not affect the name that is returned.
+ *
+ * @param posn The 0-based index of the component at which to start.
+ * Must be in the range [0,size()].
+ * @return A compound name consisting of the components at indexes in
+ * the range [posn,size()). If posn is equal to
+ * size(), an empty compound name is returned.
+ * @exception ArrayIndexOutOfBoundsException
+ * If posn is outside the specified range.
+ */
+ public Name getSuffix(int posn) {
+ Enumeration comps = impl.getSuffix(posn);
+ return (new CompoundName(comps, mySyntax));
+ }
+
+ /**
+ * Determines whether a compound name is a prefix of this compound name.
+ * A compound name 'n' is a prefix if it is equal to
+ * getPrefix(n.size())--in other words, this compound name
+ * starts with 'n'.
+ * If n is null or not a compound name, false is returned.
+ *<p>
+ * 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 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.
+ *<p>
+ * 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.
+ *<p>
+ * 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.
+ *<p>
+ * 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 <tt>Properties</tt>, followed by
+ * the number of components (an <tt>int</tt>), and the individual
+ * components (each a <tt>String</tt>).
+ */
+ private void writeObject(java.io.ObjectOutputStream s)
+ throws java.io.IOException {
+ s.writeObject(mySyntax);
+ s.writeInt(size());
+ Enumeration comps = getAll();
+ while (comps.hasMoreElements()) {
+ s.writeObject(comps.nextElement());
+ }
+ }
+
+ /**
+ * Overridden to avoid implementation dependency.
+ */
+ private void readObject(java.io.ObjectInputStream s)
+ throws java.io.IOException, ClassNotFoundException {
+ mySyntax = (Properties)s.readObject();
+ impl = new NameImpl(mySyntax);
+ int n = s.readInt(); // number of components
+ try {
+ while (--n >= 0) {
+ add((String)s.readObject());
+ }
+ } catch (InvalidNameException e) {
+ throw (new java.io.StreamCorruptedException("Invalid name"));
+ }
+ }
+
+ /**
+ * Use serialVersionUID from JNDI 1.1.1 for interoperability
+ */
+ private static final long serialVersionUID = 3513100557083972036L;
+
+/*
+// For testing
+
+ public static void main(String[] args) {
+ Properties dotSyntax = new Properties();
+ dotSyntax.put("jndi.syntax.direction", "right_to_left");
+ dotSyntax.put("jndi.syntax.separator", ".");
+ dotSyntax.put("jndi.syntax.ignorecase", "true");
+ dotSyntax.put("jndi.syntax.escape", "\\");
+// dotSyntax.put("jndi.syntax.beginquote", "\"");
+// dotSyntax.put("jndi.syntax.beginquote2", "'");
+
+ Name first = null;
+ try {
+ for (int i = 0; i < args.length; i++) {
+ Name name;
+ Enumeration e;
+ System.out.println("Given name: " + args[i]);
+ name = new CompoundName(args[i], dotSyntax);
+ if (first == null) {
+ first = name;
+ }
+ e = name.getComponents();
+ while (e.hasMoreElements()) {
+ System.out.println("Element: " + e.nextElement());
+ }
+ System.out.println("Constructed name: " + name.toString());
+
+ System.out.println("Compare " + first.toString() + " with "
+ + name.toString() + " = " + first.compareTo(name));
+ }
+ } catch (Exception ne) {
+ ne.printStackTrace();
+ }
+ }
+*/
+}