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
26package javax.naming;
27
28import 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
58public 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}
278