View Javadoc
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 <tt>Name</tt> 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 <tt>Name</tt>; 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 <tt>Name</tt> 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 <tt>Object.equals()</tt>, 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 <tt>Name</tt> 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 <tt>n</tt> is a prefix if it is equal to
174      * <tt>getPrefix(n.size())</tt>.
175      *
176      * @param n
177      *          the name to check
178      * @return  true if <tt>n</tt> 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 <tt>n</tt> is a suffix if it is equal to
185      * <tt>getSuffix(size()-n.size())</tt>.
186      *
187      * @param n
188      *          the name to check
189      * @return  true if <tt>n</tt> 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 <tt>suffix</tt> 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 <tt>n</tt> 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 <tt>comp</tt> 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 <tt>comp</tt> 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 }