001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package javax.naming;
019:
020: import java.io.Serializable;
021: import java.util.Enumeration;
022:
023: /**
024: * A <code>Name</code> interface represents a name in a naming service.
025: * <p>
026: * A name which implements this interface has a sequence of zero or more
027: * elements delimited by separators. Each element can be accessed using its
028: * position. The first element is at position 0.
029: * </p>
030: * <p>
031: * This interface is implemented by 2 classes - <code>CompoundName</code> and
032: * <code>CompositeName</code>.
033: * </p>
034: * <p>
035: * Examples of names are:
036: *
037: * <pre>
038: * File system name - for example /home/jenningm/.profile
039: * DNS hostname - for example www.apache.org
040: * Internet URL - for example http://www.eclipse.org/org/index.html
041: * </pre>
042: *
043: * </p>
044: *
045: * @see CompositeName
046: * @see CompoundName
047: */
048: public interface Name extends Cloneable, Serializable,
049: Comparable<Object> {
050:
051: public static final long serialVersionUID = -3617482732056931635L;
052:
053: /**
054: * Get all the elements of this <code>Name</code>. If the
055: * <code>Name</code> is empty then return an empty
056: * <code>Enumeration</code>.
057: *
058: * @return an enumeration of <code>Name</code> elements - cannot be null
059: */
060: public Enumeration<String> getAll();
061:
062: /**
063: * Get an element of this <code>Name</code>.
064: *
065: * @param i
066: * the index of the required element - must be greater than or
067: * equal to 0 and less than size().
068: * @return the element at the specified position
069: * @throws ArrayIndexOutOfBoundsException
070: * when the position is invalid. If the <code>Name</code> is
071: * empty this always returns
072: * <code>ArrayIndexOutOfBoundsException</code>
073: */
074: public String get(int i);
075:
076: /**
077: * Create a new <code>Name</code> which comprises the first several
078: * elements of this <code>Name</code>.
079: *
080: * @param i
081: * the index of the first element not to be included - must be
082: * greater than or equal to 0 and less than or equal to size. If
083: * 0 then an empty name is returned.
084: * @return a new <code>Name</code> which comprises the first several
085: * elements of this <code>Name</code>
086: * @throws ArrayIndexOutOfBoundsException
087: * when the position is invalid.
088: */
089: public Name getPrefix(int i);
090:
091: /**
092: * Create a new <code>Name</code> which comprises the last (<code>size() - i</code>)
093: * elements of this <code>Name</code>.
094: *
095: * @param i
096: * the index of the first element to be included - must be
097: * greater than or equal to 0 and less than size.
098: * @return a new <code>Name</code> which comprises the last (<code>size() - i</code>)
099: * elements of this <code>Name</code>
100: * @throws ArrayIndexOutOfBoundsException
101: * when the position is invalid.
102: */
103: public Name getSuffix(int i);
104:
105: /**
106: * Append a name to this <code>Name</code>. The name itself may have a
107: * number of elements.
108: *
109: * @param name
110: * the name to append onto this <code>Name</code>.
111: * @return this <code>Name</code>
112: * @throws InvalidNameException
113: * if name is invalid or the addition of the name results in
114: * this <code>Name</code> becoming invalid.
115: */
116: public Name addAll(Name name) throws InvalidNameException;
117:
118: /**
119: * Insert a name within this <code>Name</code> at the specified position.
120: * The name itself may have a number of elements.
121: *
122: * @param i
123: * the index of the element where to start inserting the name -
124: * must be greater than or equal to 0 and less than or equal to
125: * size.
126: * @param name
127: * the name to insert into this <code>Name</code>.
128: * @return this <code>Name</code>
129: * @throws InvalidNameException
130: * if name is invalid or the addition of the name results in
131: * this <code>Name</code> becoming invalid.
132: */
133: public Name addAll(int i, Name name) throws InvalidNameException;
134:
135: /**
136: * Append an element to this <code>Name</code>.
137: *
138: * @param s
139: * the string to append
140: * @return this <code>Name</code>
141: * @throws InvalidNameException
142: * if the addition of the element results in this
143: * <code>Name</code> becoming invalid.
144: */
145: public Name add(String s) throws InvalidNameException;
146:
147: /**
148: * Insert an element within this <code>Name</code> at the specified
149: * position.
150: *
151: * @param i
152: * the index of the element where to insert the element - must be
153: * greater than or equal to 0 and less than or equal to size.
154: * @param s
155: * the String to insert
156: * @return this <code>Name</code>.
157: * @throws InvalidNameException
158: * if the insertion of the element results in this Name becoming
159: * invalid.
160: */
161: public Name add(int i, String s) throws InvalidNameException;
162:
163: /**
164: * Delete an element from this <code>Name</code>.
165: *
166: * @param i
167: * the index of the element to delete - must be greater than or
168: * equal to 0 and less than size.
169: * @return the deleted element
170: * @throws InvalidNameException
171: * if the deletion of the element results in this
172: * <code>Name</code> becoming invalid.
173: */
174: public Object remove(int i) throws InvalidNameException;
175:
176: /**
177: * Create a copy of this <code>Name</code>.
178: *
179: * @return a complete (deep) copy of the object.
180: */
181: public Object clone();
182:
183: /**
184: * Compare this <code>Name</code> with the one supplied as a parameter.
185: * Each class which implements this interface will have a specification of
186: * how to do the comparison.
187: *
188: * @param o
189: * the object to compare - cannot be null.
190: * @return a negative number means this is less than the supplied object. a
191: * positive number means this is greater than the supplied object.
192: * Zero means the two objects are equal.
193: */
194: public int compareTo(Object o);
195:
196: /**
197: * Get the size of this <code>Name</code>. The size of a
198: * <code>Name</code> is its number of elements.
199: *
200: * @return the size of this name - cannot be null - can be zero
201: */
202: public int size();
203:
204: /**
205: * Check if this <code>Name</code> is empty. A <code>Name</code> is
206: * empty when it has no elements.
207: *
208: * @return true if empty, else returns false
209: */
210: public boolean isEmpty();
211:
212: /**
213: * Check if this <code>Name</code> starts with the elements in the
214: * supplied name. The supplied name itself may have a number of elements.
215: *
216: * @param name
217: * the name to check against this name
218: * @return true when the supplied name matches else returns false
219: */
220: public boolean startsWith(Name name);
221:
222: /**
223: * Check if this <code>Name</code> ends with the elements in the supplied
224: * name. The supplied name itself may have a number of elements.
225: *
226: * @param name
227: * the name to check against this name.
228: * @return true when the supplied name matches else returns false.
229: */
230: public boolean endsWith(Name name);
231:
232: }
|