--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.naming/share/classes/javax/naming/CompositeName.java Tue Sep 12 19:03:39 2017 +0200
@@ -0,0 +1,636 @@
+/*
+ * Copyright (c) 1999, 2017, 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 composite name -- a sequence of
+ * component names spanning multiple namespaces.
+ * Each component is a string name from the namespace of a
+ * naming system. If the component comes from a hierarchical
+ * namespace, that component can be further parsed into
+ * its atomic parts by using the CompoundName class.
+ *<p>
+ * The components of a composite name are numbered. The indexes of a
+ * composite 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 composite name has no components.
+ *
+ * <h1>JNDI Composite Name Syntax</h1>
+ * JNDI defines a standard string representation for composite names. This
+ * representation is the concatenation of the components of a composite name
+ * from left to right using the component separator (a forward
+ * slash character (/)) to separate each component.
+ * The JNDI syntax defines the following meta characters:
+ * <ul>
+ * <li>escape (backward slash \),
+ * <li>quote characters (single (') and double quotes (")), and
+ * <li>component separator (forward slash character (/)).
+ * </ul>
+ * Any occurrence of a leading quote, an escape preceding any meta character,
+ * an escape at the end of a component, or a component separator character
+ * in an unquoted component must be preceded by an escape character when
+ * that component is being composed into a composite name string.
+ * Alternatively, to avoid adding escape characters as described,
+ * the entire component can be quoted using matching single quotes
+ * or matching double quotes. A single quote occurring within a double-quoted
+ * component is not considered a meta character (and need not be escaped),
+ * and vice versa.
+ *<p>
+ * When two composite names are compared, the case of the characters
+ * is significant.
+ *<p>
+ * A leading component separator (the composite name string begins with
+ * a separator) denotes a leading empty component (a component consisting
+ * of an empty string).
+ * A trailing component separator (the composite name string ends with
+ * a separator) denotes a trailing empty component.
+ * Adjacent component separators denote an empty component.
+ *
+ *<h1>Composite Name Examples</h1>
+ *This table shows examples of some composite names. Each row shows
+ *the string form of a composite name and its corresponding structural form
+ *({@code CompositeName}).
+ *
+<table class="striped"><caption style="display:none">examples showing string
+ form of composite name and its corresponding structural form (CompositeName)</caption>
+<thead>
+<tr>
+<th scope="col">String Name</th>
+<th scope="col">CompositeName</th>
+</tr>
+</thead>
+<tbody style="text-align:left">
+<tr>
+<th scope="row">
+""
+</th>
+<td>{} (the empty name == new CompositeName("") == new CompositeName())
+</td>
+</tr>
+
+<tr>
+<th scope="row">
+"x"
+</th>
+<td>{"x"}
+</td>
+</tr>
+
+<tr>
+<th scope="row">
+"x/y"
+</th>
+<td>{"x", "y"}</td>
+</tr>
+
+<tr>
+<th scope="row">"x/"</th>
+<td>{"x", ""}</td>
+</tr>
+
+<tr>
+<th scope="row">"/x"</th>
+<td>{"", "x"}</td>
+</tr>
+
+<tr>
+<th scope="row">"/"</th>
+<td>{""}</td>
+</tr>
+
+<tr>
+<th scope="row">"//"</th>
+<td>{"", ""}</td>
+</tr>
+
+<tr><th scope="row">"/x/"</th>
+<td>{"", "x", ""}</td>
+</tr>
+
+<tr><th scope="row">"x//y"</th>
+<td>{"x", "", "y"}</td>
+</tr>
+</tbody>
+</table>
+ *
+ *<h1>Composition Examples</h1>
+ * Here are some composition examples. The right column shows composing
+ * string composite names while the left column shows composing the
+ * corresponding {@code CompositeName}s. Notice that composing the
+ * string forms of two composite names simply involves concatenating
+ * their string forms together.
+
+<table class="striped"><caption style="display:none">composition examples
+ showing string names and composite names</caption>
+<thead>
+<tr>
+<th scope="col">String Names</th>
+<th scope="col">CompositeNames</th>
+</tr>
+</thead>
+
+<tbody style="text-align:left">
+<tr>
+<th scope="row">
+"x/y" + "/" = x/y/
+</th>
+<td>
+{"x", "y"} + {""} = {"x", "y", ""}
+</td>
+</tr>
+
+<tr>
+<th scope="row">
+"" + "x" = "x"
+</th>
+<td>
+{} + {"x"} = {"x"}
+</td>
+</tr>
+
+<tr>
+<th scope="row">
+"/" + "x" = "/x"
+</th>
+<td>
+{""} + {"x"} = {"", "x"}
+</td>
+</tr>
+
+<tr>
+<th scope="row">
+"x" + "" + "" = "x"
+</th>
+<td>
+{"x"} + {} + {} = {"x"}
+</td>
+</tr>
+</tbody>
+</table>
+ *
+ *<h1>Multithreaded Access</h1>
+ * A {@code CompositeName} instance is not synchronized against concurrent
+ * multithreaded access. Multiple threads trying to access and modify a
+ * {@code CompositeName} should lock the object.
+ *
+ * @author Rosanna Lee
+ * @author Scott Seligman
+ * @since 1.3
+ */
+
+
+public class CompositeName implements Name {
+
+ private transient NameImpl impl;
+ /**
+ * Constructs a new composite name instance using the components
+ * specified by 'comps'. This protected method is intended
+ * to be used by subclasses of CompositeName when they override
+ * methods such as clone(), getPrefix(), getSuffix().
+ *
+ * @param comps A non-null enumeration containing the components for the new
+ * composite name. Each element is of class String.
+ * The enumeration will be consumed to extract its
+ * elements.
+ */
+ protected CompositeName(Enumeration<String> comps) {
+ impl = new NameImpl(null, comps); // null means use default syntax
+ }
+
+ /**
+ * Constructs a new composite name instance by parsing the string n
+ * using the composite name syntax (left-to-right, slash separated).
+ * The composite name syntax is described in detail in the class
+ * description.
+ *
+ * @param n The non-null string to parse.
+ * @exception InvalidNameException If n has invalid composite name syntax.
+ */
+ public CompositeName(String n) throws InvalidNameException {
+ impl = new NameImpl(null, n); // null means use default syntax
+ }
+
+ /**
+ * Constructs a new empty composite name. Such a name returns true
+ * when <code>isEmpty()</code> is invoked on it.
+ */
+ public CompositeName() {
+ impl = new NameImpl(null); // null means use default syntax
+ }
+
+ /**
+ * Generates the string representation of this composite name.
+ * The string representation consists of enumerating in order
+ * each component of the composite name and separating
+ * each component by a forward slash character. Quoting and
+ * escape characters are applied where necessary according to
+ * the JNDI syntax, which is described in the class description.
+ * An empty component is represented by an empty string.
+ *
+ * The string representation thus generated can be passed to
+ * the CompositeName constructor to create a new equivalent
+ * composite name.
+ *
+ * @return A non-null string representation of this composite name.
+ */
+ public String toString() {
+ return impl.toString();
+ }
+
+ /**
+ * Determines whether two composite names are equal.
+ * If obj is null or not a composite name, false is returned.
+ * Two composite names are equal if each component in one is equal
+ * to the corresponding component in the other. This implies
+ * both have the same number of components, and each component's
+ * equals() test against the corresponding component in the other name
+ * returns true.
+ *
+ * @param obj The possibly null object to compare against.
+ * @return true if obj is equal to this composite name, false otherwise.
+ * @see #hashCode
+ */
+ public boolean equals(Object obj) {
+ return (obj != null &&
+ obj instanceof CompositeName &&
+ impl.equals(((CompositeName)obj).impl));
+ }
+
+ /**
+ * Computes the hash code of this composite name.
+ * The hash code is the sum of the hash codes of individual components
+ * of this composite name.
+ *
+ * @return An int representing the hash code of this name.
+ * @see #equals
+ */
+ public int hashCode() {
+ return impl.hashCode();
+ }
+
+
+ /**
+ * Compares this CompositeName 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 CompositeName, ClassCastException
+ * is thrown.
+ * <p>
+ * See equals() for what it means for two composite names to be equal.
+ * If two composite names are equal, 0 is returned.
+ * <p>
+ * Ordering of composite names follows the lexicographical rules for
+ * string comparison, with the extension that this applies to all
+ * the components in the composite name. The effect is as if all the
+ * components were lined up in their specified ordered and the
+ * lexicographical rules applied over the two line-ups.
+ * If this composite name is "lexicographically" lesser than obj,
+ * a negative number is returned.
+ * If this composite name is "lexicographically" greater than obj,
+ * a positive number is returned.
+ * @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 CompositeName.
+ */
+ public int compareTo(Object obj) {
+ if (!(obj instanceof CompositeName)) {
+ throw new ClassCastException("Not a CompositeName");
+ }
+ return impl.compareTo(((CompositeName)obj).impl);
+ }
+
+ /**
+ * Generates a copy of this composite name.
+ * Changes to the components of this composite name won't
+ * affect the new copy and vice versa.
+ *
+ * @return A non-null copy of this composite name.
+ */
+ public Object clone() {
+ return (new CompositeName(getAll()));
+ }
+
+ /**
+ * Retrieves the number of components in this composite name.
+ *
+ * @return The nonnegative number of components in this composite name.
+ */
+ public int size() {
+ return (impl.size());
+ }
+
+ /**
+ * Determines whether this composite name is empty. A composite name
+ * is empty if it has zero components.
+ *
+ * @return true if this composite name is empty, false otherwise.
+ */
+ public boolean isEmpty() {
+ return (impl.isEmpty());
+ }
+
+ /**
+ * Retrieves the components of this composite name as an enumeration
+ * of strings.
+ * The effects of updates to this composite name on this enumeration
+ * is undefined.
+ *
+ * @return A non-null enumeration of the components of
+ * this composite name. Each element of the enumeration is of
+ * class String.
+ */
+ public Enumeration<String> getAll() {
+ return (impl.getAll());
+ }
+
+ /**
+ * Retrieves a component of this composite name.
+ *
+ * @param posn The 0-based index of the component to retrieve.
+ * Must be in the range [0,size()).
+ * @return The non-null component at index posn.
+ * @exception ArrayIndexOutOfBoundsException if posn is outside the
+ * specified range.
+ */
+ public String get(int posn) {
+ return (impl.get(posn));
+ }
+
+ /**
+ * Creates a composite name whose components consist of a prefix of the
+ * components in this composite name. Subsequent changes to
+ * this composite name does not affect the name that is returned.
+ *
+ * @param posn The 0-based index of the component at which to stop.
+ * Must be in the range [0,size()].
+ * @return A composite 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 CompositeName(comps));
+ }
+
+ /**
+ * Creates a composite name whose components consist of a suffix of the
+ * components in this composite name. Subsequent changes to
+ * this composite 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 composite name consisting of the components at indexes in
+ * the range [posn,size()). If posn is equal to
+ * size(), an empty composite 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 CompositeName(comps));
+ }
+
+ /**
+ * Determines whether a composite name is a prefix of this composite name.
+ * A composite name 'n' is a prefix if it is equal to
+ * getPrefix(n.size())--in other words, this composite name
+ * starts with 'n'. If 'n' is null or not a composite name, false is returned.
+ *
+ * @param n The possibly null name to check.
+ * @return true if n is a CompositeName and
+ * is a prefix of this composite name, false otherwise.
+ */
+ public boolean startsWith(Name n) {
+ if (n instanceof CompositeName) {
+ return (impl.startsWith(n.size(), n.getAll()));
+ } else {
+ return false;
+ }
+ }
+
+ /**
+ * Determines whether a composite name is a suffix of this composite name.
+ * A composite name 'n' is a suffix if it is equal to
+ * getSuffix(size()-n.size())--in other words, this
+ * composite name ends with 'n'.
+ * If n is null or not a composite name, false is returned.
+ *
+ * @param n The possibly null name to check.
+ * @return true if n is a CompositeName and
+ * is a suffix of this composite name, false otherwise.
+ */
+ public boolean endsWith(Name n) {
+ if (n instanceof CompositeName) {
+ return (impl.endsWith(n.size(), n.getAll()));
+ } else {
+ return false;
+ }
+ }
+
+ /**
+ * Adds the components of a composite name -- in order -- to the end of
+ * this composite name.
+ *
+ * @param suffix The non-null components to add.
+ * @return The updated CompositeName, not a new one. Cannot be null.
+ * @exception InvalidNameException If suffix is not a composite name.
+ */
+ public Name addAll(Name suffix)
+ throws InvalidNameException
+ {
+ if (suffix instanceof CompositeName) {
+ impl.addAll(suffix.getAll());
+ return this;
+ } else {
+ throw new InvalidNameException("Not a composite name: " +
+ suffix.toString());
+ }
+ }
+
+ /**
+ * Adds the components of a composite name -- in order -- at a specified
+ * position within this composite name.
+ * Components of this composite name at or after the index of the first
+ * new component are shifted up (away from index 0)
+ * to accommodate the new components.
+ *
+ * @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 CompositeName, not a new one. Cannot be null.
+ * @exception InvalidNameException If n is not a composite name.
+ * @exception ArrayIndexOutOfBoundsException
+ * If posn is outside the specified range.
+ */
+ public Name addAll(int posn, Name n)
+ throws InvalidNameException
+ {
+ if (n instanceof CompositeName) {
+ impl.addAll(posn, n.getAll());
+ return this;
+ } else {
+ throw new InvalidNameException("Not a composite name: " +
+ n.toString());
+ }
+ }
+
+ /**
+ * Adds a single component to the end of this composite name.
+ *
+ * @param comp The non-null component to add.
+ * @return The updated CompositeName, not a new one. Cannot be null.
+ * @exception InvalidNameException If adding comp at end of the name
+ * would violate the 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
+ * composite name.
+ * Components of this composite 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()].
+ * @return The updated CompositeName, not a new one. Cannot be null.
+ * @exception ArrayIndexOutOfBoundsException
+ * If posn is outside the specified range.
+ * @exception InvalidNameException If adding comp at the specified position
+ * would violate the name's syntax.
+ */
+ public Name add(int posn, String comp)
+ throws InvalidNameException
+ {
+ impl.add(posn, comp);
+ return this;
+ }
+
+ /**
+ * Deletes a component from this composite name.
+ * The component of this composite 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
+ * composite name is empty).
+ * @exception InvalidNameException If deleting the component
+ * would violate the name's syntax.
+ */
+ public Object remove(int posn) throws InvalidNameException{
+ return impl.remove(posn);
+ }
+
+ /**
+ * Overridden to avoid implementation dependency.
+ * @serialData The number of components (an {@code int}) followed by
+ * the individual components (each a {@code String}).
+ */
+ private void writeObject(java.io.ObjectOutputStream s)
+ throws java.io.IOException {
+ 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 {
+ impl = new NameImpl(null); // null means use default syntax
+ 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 = 1667768148915813118L;
+
+/*
+ // %%% Test code for serialization.
+ public static void main(String[] args) throws Exception {
+ CompositeName c = new CompositeName("aaa/bbb");
+ java.io.FileOutputStream f1 = new java.io.FileOutputStream("/tmp/ser");
+ java.io.ObjectOutputStream s1 = new java.io.ObjectOutputStream(f1);
+ s1.writeObject(c);
+ s1.close();
+ java.io.FileInputStream f2 = new java.io.FileInputStream("/tmp/ser");
+ java.io.ObjectInputStream s2 = new java.io.ObjectInputStream(f2);
+ c = (CompositeName)s2.readObject();
+
+ System.out.println("Size: " + c.size());
+ System.out.println("Size: " + c.snit);
+ }
+*/
+
+/*
+ %%% Testing code
+ public static void main(String[] args) {
+ try {
+ for (int i = 0; i < args.length; i++) {
+ Name name;
+ Enumeration e;
+ System.out.println("Given name: " + args[i]);
+ name = new CompositeName(args[i]);
+ e = name.getComponents();
+ while (e.hasMoreElements()) {
+ System.out.println("Element: " + e.nextElement());
+ }
+ System.out.println("Constructed name: " + name.toString());
+ }
+ } catch (Exception ne) {
+ ne.printStackTrace();
+ }
+ }
+*/
+}