001 /*
002 * Copyright 1999-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.naming;
027
028 import java.util.Enumeration;
029
030 /**
031 * The <tt>Name</tt> interface represents a generic name -- an ordered
032 * sequence of components. It can be a composite name (names that
033 * span multiple namespaces), or a compound name (names that are
034 * used within individual hierarchical naming systems).
035 *
036 * <p> There can be different implementations of <tt>Name</tt>; for example,
037 * composite names, URLs, or namespace-specific compound names.
038 *
039 * <p> The components of a name are numbered. The indexes of a name
040 * with N components range from 0 up to, but not including, N. This
041 * range may be written as [0,N).
042 * The most significant component is at index 0.
043 * An empty name has no components.
044 *
045 * <p> None of the methods in this interface accept null as a valid
046 * value for a parameter that is a name or a name component.
047 * Likewise, methods that return a name or name component never return null.
048 *
049 * <p> An instance of a <tt>Name</tt> may not be synchronized against
050 * concurrent multithreaded access if that access is not read-only.
051 *
052 * @author Rosanna Lee
053 * @author Scott Seligman
054 * @author R. Vasudevan
055 * @version 1.18 07/05/05
056 * @since 1.3
057 */
058
059 public interface Name extends Cloneable, java.io.Serializable,
060 Comparable<Object> {
061
062 /**
063 * The class fingerprint that is set to indicate
064 * serialization compatibility with a previous
065 * version of the class.
066 */
067 static final long serialVersionUID = -3617482732056931635L;
068
069 /**
070 * Generates a new copy of this name.
071 * Subsequent changes to the components of this name will not
072 * affect the new copy, and vice versa.
073 *
074 * @return a copy of this name
075 *
076 * @see Object#clone()
077 */
078 public Object clone();
079
080 /**
081 * Compares this name with another name for order.
082 * Returns a negative integer, zero, or a positive integer as this
083 * name is less than, equal to, or greater than the given name.
084 *
085 * <p> As with <tt>Object.equals()</tt>, the notion of ordering for names
086 * depends on the class that implements this interface.
087 * For example, the ordering may be
088 * based on lexicographical ordering of the name components.
089 * Specific attributes of the name, such as how it treats case,
090 * may affect the ordering. In general, two names of different
091 * classes may not be compared.
092 *
093 * @param obj the non-null object to compare against.
094 * @return a negative integer, zero, or a positive integer as this name
095 * is less than, equal to, or greater than the given name
096 * @throws ClassCastException if obj is not a <tt>Name</tt> of a
097 * type that may be compared with this name
098 *
099 * @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 }
|