/*

 * Copyright (c) 1999, 2013, 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 border="1" cellpadding=3 summary="examples showing string form of composite name and its corresponding structural form (CompositeName)">

<tr>

<th>String Name</th>

<th>CompositeName</th>

</tr>

<tr>

<td>

""

</td>

<td>{} (the empty name == new CompositeName("") == new CompositeName())

</td>

</tr>

<tr>

<td>

"x"

</td>

<td>{"x"}

</td>

</tr>

<tr>

<td>

"x/y"

</td>

<td>{"x", "y"}</td>

</tr>

<tr>

<td>"x/"</td>

<td>{"x", ""}</td>

</tr>

<tr>

<td>"/x"</td>

<td>{"", "x"}</td>

</tr>

<tr>

<td>"/"</td>

<td>{""}</td>

</tr>

<tr>

<td>"//"</td>

<td>{"", ""}</td>

</tr>

<tr><td>"/x/"</td>

<td>{"", "x", ""}</td>

</tr>

<tr><td>"x//y"</td>

<td>{"x", "", "y"}</td>

</tr>

</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 border="1" cellpadding=3 summary="composition examples showing string names and composite names">

<tr>

<th>String Names</th>

<th>CompositeNames</th>

</tr>

<tr>

<td>

"x/y"           + "/"   = x/y/

</td>

<td>

{"x", "y"}      + {""}  = {"x", "y", ""}

</td>

</tr>

<tr>

<td>

""              + "x"   = "x"

</td>

<td>

{}              + {"x"} = {"x"}

</td>

</tr>

<tr>

<td>

"/"             + "x"   = "/x"

</td>

<td>

{""}            + {"x"} = {"", "x"}

</td>

</tr>

<tr>

<td>

"x"   + ""      + ""    = "x"

</td>

<td>

{"x"} + {}      + {}    = {"x"}

</td>

</tr>

</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.