/*
 * Copyright (c) 1999, 2004, 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;

The Name interface represents a generic name -- an ordered sequence of components. It can be a composite name (names that span multiple namespaces), or a compound name (names that are used within individual hierarchical naming systems). 
 There can be different implementations of Name; for example, composite names, URLs, or namespace-specific compound names. 
 The components of a name are numbered.  The indexes of a 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 name has no components.
 None of the methods in this interface accept null as a valid
value for a parameter that is a name or a name component.
Likewise, methods that return a name or name component never return null.
 An instance of a Name may not be synchronized against concurrent multithreaded access if that access is not read-only. 
Author:
Rosanna Lee, Scott Seligman, R. Vasudevan
Since:
1.3/**
 * The {@code Name} interface represents a generic name -- an ordered
 * sequence of components.  It can be a composite name (names that
 * span multiple namespaces), or a compound name (names that are
 * used within individual hierarchical naming systems).
 *
 * <p> There can be different implementations of {@code Name}; for example,
 * composite names, URLs, or namespace-specific compound names.
 *
 * <p> The components of a name are numbered.  The indexes of a 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 name has no components.
 *
 * <p> None of the methods in this interface accept null as a valid
 * value for a parameter that is a name or a name component.
 * Likewise, methods that return a name or name component never return null.
 *
 * <p> An instance of a {@code Name} may not be synchronized against
 * concurrent multithreaded access if that access is not read-only.
 *
 * @author Rosanna Lee
 * @author Scott Seligman
 * @author R. Vasudevan
 * @since 1.3
 */

public interface Name
    extends Cloneable, java.io.Serializable, Comparable<Object>
{

   
The class fingerprint that is set to indicate
serialization compatibility with a previous
version of the class.
/**
    * The class fingerprint that is set to indicate
    * serialization compatibility with a previous
    * version of the class.
    */
    static final long serialVersionUID = -3617482732056931635L;

    
Generates a new copy of this name.
Subsequent changes to the components of this name will not
affect the new copy, and vice versa.
See Also:
Object.clone()
Returns:
 a copy of this name/**
     * Generates a new copy of this name.
     * Subsequent changes to the components of this name will not
     * affect the new copy, and vice versa.
     *
     * @return  a copy of this name
     *
     * @see Object#clone()
     */
    public Object clone();

    
Compares this name with another name for order.
Returns a negative integer, zero, or a positive integer as this
name is less than, equal to, or greater than the given name.
 As with Object.equals(), the notion of ordering for names depends on the class that implements this interface. For example, the ordering may be based on lexicographical ordering of the name components. Specific attributes of the name, such as how it treats case, may affect the ordering. In general, two names of different classes may not be compared. 
Params:
obj – the non-null object to compare against.
Throws:
ClassCastException – if obj is not a Name of a type that may be compared with this name
See Also:
Comparable.compareTo(Object)
Returns:
 a negative integer, zero, or a positive integer as this name
         is less than, equal to, or greater than the given name/**
     * Compares this name with another name for order.
     * Returns a negative integer, zero, or a positive integer as this
     * name is less than, equal to, or greater than the given name.
     *
     * <p> As with {@code Object.equals()}, the notion of ordering for names
     * depends on the class that implements this interface.
     * For example, the ordering may be
     * based on lexicographical ordering of the name components.
     * Specific attributes of the name, such as how it treats case,
     * may affect the ordering.  In general, two names of different
     * classes may not be compared.
     *
     * @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 name
     * @throws  ClassCastException if obj is not a {@code Name} of a
     *          type that may be compared with this name
     *
     * @see Comparable#compareTo(Object)
     */
    public int compareTo(Object obj);

    
Returns the number of components in this name.
Returns:
 the number of components in this name/**
     * Returns the number of components in this name.
     *
     * @return  the number of components in this name
     */
    public int size();

    
Determines whether this name is empty.
An empty name is one with zero components.
Returns:
 true if this name is empty, false otherwise/**
     * Determines whether this name is empty.
     * An empty name is one with zero components.
     *
     * @return  true if this name is empty, false otherwise
     */
    public boolean isEmpty();

    
Retrieves the components of this name as an enumeration
of strings.  The effect on the enumeration of updates to
this name is undefined.  If the name has zero components,
an empty (non-null) enumeration is returned.
Returns:
 an enumeration of the components of this name, each a string/**
     * Retrieves the components of this name as an enumeration
     * of strings.  The effect on the enumeration of updates to
     * this name is undefined.  If the name has zero components,
     * an empty (non-null) enumeration is returned.
     *
     * @return  an enumeration of the components of this name, each a string
     */
    public Enumeration<String> getAll();

    
Retrieves a component of this name.
Params:
posn – 
         the 0-based index of the component to retrieve.
         Must be in the range [0,size()).
Throws:
ArrayIndexOutOfBoundsException – 
         if posn is outside the specified range
Returns:
 the component at index posn/**
     * Retrieves a component of this 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
     * @throws  ArrayIndexOutOfBoundsException
     *          if posn is outside the specified range
     */
    public String get(int posn);

    
Creates a name whose components consist of a prefix of the
components of this name.  Subsequent changes to
this name will not affect the name that is returned and vice versa.
Params:
posn – 
         the 0-based index of the component at which to stop.
         Must be in the range [0,size()].
Throws:
ArrayIndexOutOfBoundsException – 
         if posn is outside the specified range
Returns:
 a name consisting of the components at indexes in
         the range [0,posn)./**
     * Creates a name whose components consist of a prefix of the
     * components of this name.  Subsequent changes to
     * this name will 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 name consisting of the components at indexes in
     *          the range [0,posn).
     * @throws  ArrayIndexOutOfBoundsException
     *          if posn is outside the specified range
     */
    public Name getPrefix(int posn);

    
Creates a name whose components consist of a suffix of the
components in this name.  Subsequent changes to
this name do not affect the name that is returned and vice versa.
Params:
posn – 
         the 0-based index of the component at which to start.
         Must be in the range [0,size()].
Throws:
ArrayIndexOutOfBoundsException – 
         if posn is outside the specified range
Returns:
 a name consisting of the components at indexes in
         the range [posn,size()).  If posn is equal to
         size(), an empty name is returned./**
     * Creates a name whose components consist of a suffix of the
     * components in this name.  Subsequent changes to
     * this name do not affect the name that is returned and vice versa.
     *
     * @param posn
     *          the 0-based index of the component at which to start.
     *          Must be in the range [0,size()].
     * @return  a name consisting of the components at indexes in
     *          the range [posn,size()).  If posn is equal to
     *          size(), an empty name is returned.
     * @throws  ArrayIndexOutOfBoundsException
     *          if posn is outside the specified range
     */
    public Name getSuffix(int posn);

    
Determines whether this name starts with a specified prefix. A name n is a prefix if it is equal to getPrefix(n.size()). 
Params:
n – 
         the name to check
Returns:
 true if n is a prefix of this name, false otherwise/**
     * Determines whether this name starts with a specified prefix.
     * A name {@code n} is a prefix if it is equal to
     * {@code getPrefix(n.size())}.
     *
     * @param n
     *          the name to check
     * @return  true if {@code n} is a prefix of this name, false otherwise
     */
    public boolean startsWith(Name n);

    
Determines whether this name ends with a specified suffix. A name n is a suffix if it is equal to getSuffix(size()-n.size()). 
Params:
n – 
         the name to check
Returns:
 true if n is a suffix of this name, false otherwise/**
     * Determines whether this name ends with a specified suffix.
     * A name {@code n} is a suffix if it is equal to
     * {@code getSuffix(size()-n.size())}.
     *
     * @param n
     *          the name to check
     * @return  true if {@code n} is a suffix of this name, false otherwise
     */
    public boolean endsWith(Name n);

    
Adds the components of a name -- in order -- to the end of this name.
Params:
suffix – 
         the components to add
Throws:
InvalidNameException – if suffix is not a valid name, or if the addition of the components would violate the syntax rules of this name
Returns:
 the updated name (not a new one)/**
     * Adds the components of a name -- in order -- to the end of this name.
     *
     * @param suffix
     *          the components to add
     * @return  the updated name (not a new one)
     *
     * @throws  InvalidNameException if {@code suffix} is not a valid name,
     *          or if the addition of the components would violate the syntax
     *          rules of this name
     */
    public Name addAll(Name suffix) throws InvalidNameException;

    
Adds the components of a name -- in order -- at a specified position
within this name.
Components of this name at or after the index of the first new
component are shifted up (away from 0) to accommodate the new
components.
Params:
n – 
         the components to add
posn – 
         the index in this name at which to add the new
         components.  Must be in the range [0,size()].
Throws:
ArrayIndexOutOfBoundsException – 
         if posn is outside the specified range
InvalidNameException – if n is not a valid name, or if the addition of the components would violate the syntax rules of this name
Returns:
 the updated name (not a new one)/**
     * Adds the components of a name -- in order -- at a specified position
     * within this name.
     * Components of this name at or after the index of the first new
     * component are shifted up (away from 0) to accommodate the new
     * components.
     *
     * @param n
     *          the 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 name (not a new one)
     *
     * @throws  ArrayIndexOutOfBoundsException
     *          if posn is outside the specified range
     * @throws  InvalidNameException if {@code n} is not a valid name,
     *          or if the addition of the components would violate the syntax
     *          rules of this name
     */
    public Name addAll(int posn, Name n) throws InvalidNameException;

    
Adds a single component to the end of this name.
Params:
comp – 
         the component to add
Throws:
InvalidNameException – if adding comp would violate the syntax rules of this name
Returns:
 the updated name (not a new one)/**
     * Adds a single component to the end of this name.
     *
     * @param comp
     *          the component to add
     * @return  the updated name (not a new one)
     *
     * @throws  InvalidNameException if adding {@code comp} would violate
     *          the syntax rules of this name
     */
    public Name add(String comp) throws InvalidNameException;

    
Adds a single component at a specified position within this name.
Components of this name at or after the index of the new component
are shifted up by one (away from index 0) to accommodate the new
component.
Params:
comp – 
         the component to add
posn – 
         the index at which to add the new component.
         Must be in the range [0,size()].
Throws:
ArrayIndexOutOfBoundsException – 
         if posn is outside the specified range
InvalidNameException – if adding comp would violate the syntax rules of this name
Returns:
 the updated name (not a new one)/**
     * Adds a single component at a specified position within this name.
     * Components of this 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 component to add
     * @param posn
     *          the index at which to add the new component.
     *          Must be in the range [0,size()].
     * @return  the updated name (not a new one)
     *
     * @throws  ArrayIndexOutOfBoundsException
     *          if posn is outside the specified range
     * @throws  InvalidNameException if adding {@code comp} would violate
     *          the syntax rules of this name
     */
    public Name add(int posn, String comp) throws InvalidNameException;

    
Removes a component from this name.
The component of this name at the specified position is removed.
Components with indexes greater than this position
are shifted down (toward index 0) by one.
Params:
posn – 
         the index of the component to remove.
         Must be in the range [0,size()).
Throws:
ArrayIndexOutOfBoundsException – 
         if posn is outside the specified range
InvalidNameException – if deleting the component
         would violate the syntax rules of the name
Returns:
 the component removed (a String)/**
     * Removes a component from this name.
     * The component of this name at the specified position is removed.
     * Components with indexes greater than this position
     * are shifted down (toward index 0) by one.
     *
     * @param posn
     *          the index of the component to remove.
     *          Must be in the range [0,size()).
     * @return  the component removed (a String)
     *
     * @throws  ArrayIndexOutOfBoundsException
     *          if posn is outside the specified range
     * @throws  InvalidNameException if deleting the component
     *          would violate the syntax rules of the name
     */
    public Object remove(int posn) throws InvalidNameException;
}