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  ;
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  , java.io.Serializable  , Comparable  <Object  >
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   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   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  <String  > 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   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   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   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   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   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   addAll(Name   suffix) throws InvalidNameException  ;
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   addAll(int posn, Name   n) throws InvalidNameException  ;
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   add(String   comp) throws InvalidNameException  ;
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   add(int posn, String   comp) throws InvalidNameException  ;
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   remove(int posn) throws InvalidNameException  ;
260 }
261
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags