KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > naming > Name


1 /*
2  * @(#)Name.java 1.11 04/05/05
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package javax.naming;
9
10 import java.util.Enumeration JavaDoc;
11
12 /**
13  * The <tt>Name</tt> interface represents a generic name -- an ordered
14  * sequence of components. It can be a composite name (names that
15  * span multiple namespaces), or a compound name (names that are
16  * used within individual hierarchical naming systems).
17  *
18  * <p> There can be different implementations of <tt>Name</tt>; for example,
19  * composite names, URLs, or namespace-specific compound names.
20  *
21  * <p> The components of a name are numbered. The indexes of a name
22  * with N components range from 0 up to, but not including, N. This
23  * range may be written as [0,N).
24  * The most significant component is at index 0.
25  * An empty name has no components.
26  *
27  * <p> None of the methods in this interface accept null as a valid
28  * value for a parameter that is a name or a name component.
29  * Likewise, methods that return a name or name component never return null.
30  *
31  * <p> An instance of a <tt>Name</tt> may not be synchronized against
32  * concurrent multithreaded access if that access is not read-only.
33  *
34  * @author Rosanna Lee
35  * @author Scott Seligman
36  * @author R. Vasudevan
37  * @version 1.11 04/05/05
38  * @since 1.3
39  */

40
41 public interface Name
42     extends Cloneable JavaDoc, java.io.Serializable JavaDoc, Comparable JavaDoc<Object JavaDoc>
43 {
44
45    /**
46     * The class fingerprint that is set to indicate
47     * serialization compatibility with a previous
48     * version of the class.
49     */

50     static final long serialVersionUID = -3617482732056931635L;
51
52     /**
53      * Generates a new copy of this name.
54      * Subsequent changes to the components of this name will not
55      * affect the new copy, and vice versa.
56      *
57      * @return a copy of this name
58      *
59      * @see Object#clone()
60      */

61     public Object JavaDoc clone();
62
63     /**
64      * Compares this name with another name for order.
65      * Returns a negative integer, zero, or a positive integer as this
66      * name is less than, equal to, or greater than the given name.
67      *
68      * <p> As with <tt>Object.equals()</tt>, the notion of ordering for names
69      * depends on the class that implements this interface.
70      * For example, the ordering may be
71      * based on lexicographical ordering of the name components.
72      * Specific attributes of the name, such as how it treats case,
73      * may affect the ordering. In general, two names of different
74      * classes may not be compared.
75      *
76      * @param obj the non-null object to compare against.
77      * @return a negative integer, zero, or a positive integer as this name
78      * is less than, equal to, or greater than the given name
79      * @throws ClassCastException if obj is not a <tt>Name</tt> of a
80      * type that may be compared with this name
81      *
82      * @see Comparable#compareTo(Object)
83      */

84     public int compareTo(Object JavaDoc obj);
85
86     /**
87      * Returns the number of components in this name.
88      *
89      * @return the number of components in this name
90      */

91     public int size();
92
93     /**
94      * Determines whether this name is empty.
95      * An empty name is one with zero components.
96      *
97      * @return true if this name is empty, false otherwise
98      */

99     public boolean isEmpty();
100
101     /**
102      * Retrieves the components of this name as an enumeration
103      * of strings. The effect on the enumeration of updates to
104      * this name is undefined. If the name has zero components,
105      * an empty (non-null) enumeration is returned.
106      *
107      * @return an enumeration of the components of this name, each a string
108      */

109     public Enumeration JavaDoc<String JavaDoc> getAll();
110
111     /**
112      * Retrieves a component of this name.
113      *
114      * @param posn
115      * the 0-based index of the component to retrieve.
116      * Must be in the range [0,size()).
117      * @return the component at index posn
118      * @throws ArrayIndexOutOfBoundsException
119      * if posn is outside the specified range
120      */

121     public String JavaDoc get(int posn);
122
123     /**
124      * Creates a name whose components consist of a prefix of the
125      * components of this name. Subsequent changes to
126      * this name will not affect the name that is returned and vice versa.
127      *
128      * @param posn
129      * the 0-based index of the component at which to stop.
130      * Must be in the range [0,size()].
131      * @return a name consisting of the components at indexes in
132      * the range [0,posn).
133      * @throws ArrayIndexOutOfBoundsException
134      * if posn is outside the specified range
135      */

136     public Name JavaDoc getPrefix(int posn);
137
138     /**
139      * Creates a name whose components consist of a suffix of the
140      * components in this name. Subsequent changes to
141      * this name do not affect the name that is returned and vice versa.
142      *
143      * @param posn
144      * the 0-based index of the component at which to start.
145      * Must be in the range [0,size()].
146      * @return a name consisting of the components at indexes in
147      * the range [posn,size()). If posn is equal to
148      * size(), an empty name is returned.
149      * @throws ArrayIndexOutOfBoundsException
150      * if posn is outside the specified range
151      */

152     public Name JavaDoc getSuffix(int posn);
153
154     /**
155      * Determines whether this name starts with a specified prefix.
156      * A name <tt>n</tt> is a prefix if it is equal to
157      * <tt>getPrefix(n.size())</tt>.
158      *
159      * @param n
160      * the name to check
161      * @return true if <tt>n</tt> is a prefix of this name, false otherwise
162      */

163     public boolean startsWith(Name JavaDoc n);
164
165     /**
166      * Determines whether this name ends with a specified suffix.
167      * A name <tt>n</tt> is a suffix if it is equal to
168      * <tt>getSuffix(size()-n.size())</tt>.
169      *
170      * @param n
171      * the name to check
172      * @return true if <tt>n</tt> is a suffix of this name, false otherwise
173      */

174     public boolean endsWith(Name JavaDoc n);
175
176     /**
177      * Adds the components of a name -- in order -- to the end of this name.
178      *
179      * @param suffix
180      * the components to add
181      * @return the updated name (not a new one)
182      *
183      * @throws InvalidNameException if <tt>suffix</tt> is not a valid name,
184      * or if the addition of the components would violate the syntax
185      * rules of this name
186      */

187     public Name JavaDoc addAll(Name JavaDoc suffix) throws InvalidNameException JavaDoc;
188
189     /**
190      * Adds the components of a name -- in order -- at a specified position
191      * within this name.
192      * Components of this name at or after the index of the first new
193      * component are shifted up (away from 0) to accommodate the new
194      * components.
195      *
196      * @param n
197      * the components to add
198      * @param posn
199      * the index in this name at which to add the new
200      * components. Must be in the range [0,size()].
201      * @return the updated name (not a new one)
202      *
203      * @throws ArrayIndexOutOfBoundsException
204      * if posn is outside the specified range
205      * @throws InvalidNameException if <tt>n</tt> is not a valid name,
206      * or if the addition of the components would violate the syntax
207      * rules of this name
208      */

209     public Name JavaDoc addAll(int posn, Name JavaDoc n) throws InvalidNameException JavaDoc;
210
211     /**
212      * Adds a single component to the end of this name.
213      *
214      * @param comp
215      * the component to add
216      * @return the updated name (not a new one)
217      *
218      * @throws InvalidNameException if adding <tt>comp</tt> would violate
219      * the syntax rules of this name
220      */

221     public Name JavaDoc add(String JavaDoc comp) throws InvalidNameException JavaDoc;
222
223     /**
224      * Adds a single component at a specified position within this name.
225      * Components of this name at or after the index of the new component
226      * are shifted up by one (away from index 0) to accommodate the new
227      * component.
228      *
229      * @param comp
230      * the component to add
231      * @param posn
232      * the index at which to add the new component.
233      * Must be in the range [0,size()].
234      * @return the updated name (not a new one)
235      *
236      * @throws ArrayIndexOutOfBoundsException
237      * if posn is outside the specified range
238      * @throws InvalidNameException if adding <tt>comp</tt> would violate
239      * the syntax rules of this name
240      */

241     public Name JavaDoc add(int posn, String JavaDoc comp) throws InvalidNameException JavaDoc;
242
243     /**
244      * Removes a component from this name.
245      * The component of this name at the specified position is removed.
246      * Components with indexes greater than this position
247      * are shifted down (toward index 0) by one.
248      *
249      * @param posn
250      * the index of the component to remove.
251      * Must be in the range [0,size()).
252      * @return the component removed (a String)
253      *
254      * @throws ArrayIndexOutOfBoundsException
255      * if posn is outside the specified range
256      * @throws InvalidNameException if deleting the component
257      * would violate the syntax rules of the name
258      */

259     public Object JavaDoc remove(int posn) throws InvalidNameException JavaDoc;
260 }
261
Popular Tags