Java tutorial
/* * Copyright (c) 1999, 2019, Oracle and/or its affiliates. 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. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.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. * * <h2>Compound Name Syntax</h2> * 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 separates 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. * *<h2>Multithreaded Access</h2> * A {@code CompoundName} instance is not synchronized against concurrent * multithreaded access. Multiple threads trying to access and modify a * {@code CompoundName} 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. */ private 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 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}. */ 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 do 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<String> 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 do 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<String> 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 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 {@code Properties}, followed by * the number of components (an {@code int}), and the individual * components (each a {@code String}). */ private void writeObject(java.io.ObjectOutputStream s) throws java.io.IOException { s.writeObject(mySyntax); s.writeInt(size()); Enumeration<String> 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(); } } */ }