1 /*

     2  * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package javax.naming;

    27 

    28 import java.util.Enumeration;

    29 

    30 /**

    31  * The {@code Name} interface represents a generic name -- an ordered

    32  * sequence of components.  It can be a composite name (names that

    33  * span multiple namespaces), or a compound name (names that are

    34  * used within individual hierarchical naming systems).

    35  *

    36  * <p> There can be different implementations of {@code Name}; for example,

    37  * composite names, URLs, or namespace-specific compound names.

    38  *

    39  * <p> The components of a name are numbered.  The indexes of a name

    40  * with N components range from 0 up to, but not including, N.  This

    41  * range may be written as [0,N).

    42  * The most significant component is at index 0.

    43  * An empty name has no components.

    44  *

    45  * <p> None of the methods in this interface accept null as a valid

    46  * value for a parameter that is a name or a name component.

    47  * Likewise, methods that return a name or name component never return null.

    48  *

    49  * <p> An instance of a {@code Name} may not be synchronized against

    50  * concurrent multithreaded access if that access is not read-only.

    51  *

    52  * @author Rosanna Lee

    53  * @author Scott Seligman

    54  * @author R. Vasudevan

    55  * @since 1.3

    56  */

    57 

    58 public interface Name

    59     extends Cloneable, java.io.Serializable, Comparable<Object>

    60 {

    61 

    62    /**

    63     * The class fingerprint that is set to indicate

    64     * serialization compatibility with a previous

    65     * version of the class.

    66     */

    67     static final long serialVersionUID = -3617482732056931635L;

    68 

    69     /**

    70      * Generates a new copy of this name.

    71      * Subsequent changes to the components of this name will not

    72      * affect the new copy, and vice versa.

    73      *

    74      * @return  a copy of this name

    75      *

    76      * @see Object#clone()

    77      */

    78     public Object clone();

    79 

    80     /**

    81      * Compares this name with another name for order.

    82      * Returns a negative integer, zero, or a positive integer as this

    83      * name is less than, equal to, or greater than the given name.

    84      *

    85      * <p> As with {@code Object.equals()}, the notion of ordering for names

    86      * depends on the class that implements this interface.

    87      * For example, the ordering may be

    88      * based on lexicographical ordering of the name components.

    89      * Specific attributes of the name, such as how it treats case,

    90      * may affect the ordering.  In general, two names of different

    91      * classes may not be compared.

    92      *

    93      * @param   obj the non-null object to compare against.

    94      * @return  a negative integer, zero, or a positive integer as this name

    95      *          is less than, equal to, or greater than the given name

    96      * @throws  ClassCastException if obj is not a {@code Name} of a

    97      *          type that may be compared with this name

    98      *

    99      * @see Comparable#compareTo(Object)

   100      */

   101     public int compareTo(Object obj);

   102 

   103     /**

   104      * Returns the number of components in this name.

   105      *

   106      * @return  the number of components in this name

   107      */

   108     public int size();

   109 

   110     /**

   111      * Determines whether this name is empty.

   112      * An empty name is one with zero components.

   113      *

   114      * @return  true if this name is empty, false otherwise

   115      */

   116     public boolean isEmpty();

   117 

   118     /**

   119      * Retrieves the components of this name as an enumeration

   120      * of strings.  The effect on the enumeration of updates to

   121      * this name is undefined.  If the name has zero components,

   122      * an empty (non-null) enumeration is returned.

   123      *

   124      * @return  an enumeration of the components of this name, each a string

   125      */

   126     public Enumeration<String> getAll();

   127 

   128     /**

   129      * Retrieves a component of this name.

   130      *

   131      * @param posn

   132      *          the 0-based index of the component to retrieve.

   133      *          Must be in the range [0,size()).

   134      * @return  the component at index posn

   135      * @throws  ArrayIndexOutOfBoundsException

   136      *          if posn is outside the specified range

   137      */

   138     public String get(int posn);

   139 

   140     /**

   141      * Creates a name whose components consist of a prefix of the

   142      * components of this name.  Subsequent changes to

   143      * this name will not affect the name that is returned and vice versa.

   144      *

   145      * @param posn

   146      *          the 0-based index of the component at which to stop.

   147      *          Must be in the range [0,size()].

   148      * @return  a name consisting of the components at indexes in

   149      *          the range [0,posn).

   150      * @throws  ArrayIndexOutOfBoundsException

   151      *          if posn is outside the specified range

   152      */

   153     public Name getPrefix(int posn);

   154 

   155     /**

   156      * Creates a name whose components consist of a suffix of the

   157      * components in this name.  Subsequent changes to

   158      * this name do not affect the name that is returned and vice versa.

   159      *

   160      * @param posn

   161      *          the 0-based index of the component at which to start.

   162      *          Must be in the range [0,size()].

   163      * @return  a name consisting of the components at indexes in

   164      *          the range [posn,size()).  If posn is equal to

   165      *          size(), an empty name is returned.

   166      * @throws  ArrayIndexOutOfBoundsException

   167      *          if posn is outside the specified range

   168      */

   169     public Name getSuffix(int posn);

   170 

   171     /**

   172      * Determines whether this name starts with a specified prefix.

   173      * A name {@code n} is a prefix if it is equal to

   174      * {@code getPrefix(n.size())}.

   175      *

   176      * @param n

   177      *          the name to check

   178      * @return  true if {@code n} is a prefix of this name, false otherwise

   179      */

   180     public boolean startsWith(Name n);

   181 

   182     /**

   183      * Determines whether this name ends with a specified suffix.

   184      * A name {@code n} is a suffix if it is equal to

   185      * {@code getSuffix(size()-n.size())}.

   186      *

   187      * @param n

   188      *          the name to check

   189      * @return  true if {@code n} is a suffix of this name, false otherwise

   190      */

   191     public boolean endsWith(Name n);

   192 

   193     /**

   194      * Adds the components of a name -- in order -- to the end of this name.

   195      *

   196      * @param suffix

   197      *          the components to add

   198      * @return  the updated name (not a new one)

   199      *

   200      * @throws  InvalidNameException if {@code suffix} is not a valid name,

   201      *          or if the addition of the components would violate the syntax

   202      *          rules of this name

   203      */

   204     public Name addAll(Name suffix) throws InvalidNameException;

   205 

   206     /**

   207      * Adds the components of a name -- in order -- at a specified position

   208      * within this name.

   209      * Components of this name at or after the index of the first new

   210      * component are shifted up (away from 0) to accommodate the new

   211      * components.

   212      *

   213      * @param n

   214      *          the components to add

   215      * @param posn

   216      *          the index in this name at which to add the new

   217      *          components.  Must be in the range [0,size()].

   218      * @return  the updated name (not a new one)

   219      *

   220      * @throws  ArrayIndexOutOfBoundsException

   221      *          if posn is outside the specified range

   222      * @throws  InvalidNameException if {@code n} is not a valid name,

   223      *          or if the addition of the components would violate the syntax

   224      *          rules of this name

   225      */

   226     public Name addAll(int posn, Name n) throws InvalidNameException;

   227 

   228     /**

   229      * Adds a single component to the end of this name.

   230      *

   231      * @param comp

   232      *          the component to add

   233      * @return  the updated name (not a new one)

   234      *

   235      * @throws  InvalidNameException if adding {@code comp} would violate

   236      *          the syntax rules of this name

   237      */

   238     public Name add(String comp) throws InvalidNameException;

   239 

   240     /**

   241      * Adds a single component at a specified position within this name.

   242      * Components of this name at or after the index of the new component

   243      * are shifted up by one (away from index 0) to accommodate the new

   244      * component.

   245      *

   246      * @param comp

   247      *          the component to add

   248      * @param posn

   249      *          the index at which to add the new component.

   250      *          Must be in the range [0,size()].

   251      * @return  the updated name (not a new one)

   252      *

   253      * @throws  ArrayIndexOutOfBoundsException

   254      *          if posn is outside the specified range

   255      * @throws  InvalidNameException if adding {@code comp} would violate

   256      *          the syntax rules of this name

   257      */

   258     public Name add(int posn, String comp) throws InvalidNameException;

   259 

   260     /**

   261      * Removes a component from this name.

   262      * The component of this name at the specified position is removed.

   263      * Components with indexes greater than this position

   264      * are shifted down (toward index 0) by one.

   265      *

   266      * @param posn

   267      *          the index of the component to remove.

   268      *          Must be in the range [0,size()).

   269      * @return  the component removed (a String)

   270      *

   271      * @throws  ArrayIndexOutOfBoundsException

   272      *          if posn is outside the specified range

   273      * @throws  InvalidNameException if deleting the component

   274      *          would violate the syntax rules of the name

   275      */

   276     public Object remove(int posn) throws InvalidNameException;

   277 }