1. /*
  2. * @(#)Name.java 1.7 03/01/23
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.naming;
  8. import java.util.Enumeration;
  9. /**
  10. * The <tt>Name</tt> interface represents a generic name -- an ordered
  11. * sequence of components. It can be a composite name (names that
  12. * span multiple namespaces), or a compound name (names that are
  13. * used within individual hierarchical naming systems).
  14. *
  15. * <p> There can be different implementations of <tt>Name</tt> for example,
  16. * composite names, URLs, or namespace-specific compound names.
  17. *
  18. * <p> The components of a name are numbered. The indexes of a name
  19. * with N components range from 0 up to, but not including, N. This
  20. * range may be written as [0,N).
  21. * The most significant component is at index 0.
  22. * An empty name has no components.
  23. *
  24. * <p> None of the methods in this interface accept null as a valid
  25. * value for a parameter that is a name or a name component.
  26. * Likewise, methods that return a name or name component never return null.
  27. *
  28. * <p> An instance of a <tt>Name</tt> may not be synchronized against
  29. * concurrent multithreaded access if that access is not read-only.
  30. *
  31. * @author Rosanna Lee
  32. * @author Scott Seligman
  33. * @author R. Vasudevan
  34. * @version 1.7 03/01/23
  35. * @since 1.3
  36. */
  37. public interface Name extends Cloneable, java.io.Serializable {
  38. /**
  39. * Generates a new copy of this name.
  40. * Subsequent changes to the components of this name will not
  41. * affect the new copy, and vice versa.
  42. *
  43. * @return a copy of this name
  44. *
  45. * @see Object#clone()
  46. */
  47. public Object clone();
  48. /**
  49. * Compares this name with another name for order.
  50. * Returns a negative integer, zero, or a positive integer as this
  51. * name is less than, equal to, or greater than the given name.
  52. *
  53. * <p> As with <tt>Object.equals()</tt>, the notion of ordering for names
  54. * depends on the class that implements this interface.
  55. * For example, the ordering may be
  56. * based on lexicographical ordering of the name components.
  57. * Specific attributes of the name, such as how it treats case,
  58. * may affect the ordering. In general, two names of different
  59. * classes may not be compared.
  60. *
  61. * @param obj the non-null object to compare against.
  62. * @return a negative integer, zero, or a positive integer as this name
  63. * is less than, equal to, or greater than the given name
  64. * @throws ClassCastException if obj is not a <tt>Name</tt> of a
  65. * type that may be compared with this name
  66. *
  67. * @see Comparable#compareTo(Object)
  68. */
  69. public int compareTo(Object obj);
  70. /**
  71. * Returns the number of components in this name.
  72. *
  73. * @return the number of components in this name
  74. */
  75. public int size();
  76. /**
  77. * Determines whether this name is empty.
  78. * An empty name is one with zero components.
  79. *
  80. * @return true if this name is empty, false otherwise
  81. */
  82. public boolean isEmpty();
  83. /**
  84. * Retrieves the components of this name as an enumeration
  85. * of strings. The effect on the enumeration of updates to
  86. * this name is undefined. If the name has zero components,
  87. * an empty (non-null) enumeration is returned.
  88. *
  89. * @return an enumeration of the components of this name, each a string
  90. */
  91. public Enumeration getAll();
  92. /**
  93. * Retrieves a component of this name.
  94. *
  95. * @param posn
  96. * the 0-based index of the component to retrieve.
  97. * Must be in the range [0,size()).
  98. * @return the component at index posn
  99. * @throws ArrayIndexOutOfBoundsException
  100. * if posn is outside the specified range
  101. */
  102. public String get(int posn);
  103. /**
  104. * Creates a name whose components consist of a prefix of the
  105. * components of this name. Subsequent changes to
  106. * this name will not affect the name that is returned and vice versa.
  107. *
  108. * @param posn
  109. * the 0-based index of the component at which to stop.
  110. * Must be in the range [0,size()].
  111. * @return a name consisting of the components at indexes in
  112. * the range [0,posn).
  113. * @throws ArrayIndexOutOfBoundsException
  114. * if posn is outside the specified range
  115. */
  116. public Name getPrefix(int posn);
  117. /**
  118. * Creates a name whose components consist of a suffix of the
  119. * components in this name. Subsequent changes to
  120. * this name do not affect the name that is returned and vice versa.
  121. *
  122. * @param posn
  123. * the 0-based index of the component at which to start.
  124. * Must be in the range [0,size()].
  125. * @return a name consisting of the components at indexes in
  126. * the range [posn,size()). If posn is equal to
  127. * size(), an empty name is returned.
  128. * @throws ArrayIndexOutOfBoundsException
  129. * if posn is outside the specified range
  130. */
  131. public Name getSuffix(int posn);
  132. /**
  133. * Determines whether this name starts with a specified prefix.
  134. * A name <tt>n</tt> is a prefix if it is equal to
  135. * <tt>getPrefix(n.size())</tt>.
  136. *
  137. * @param n
  138. * the name to check
  139. * @return true if <tt>n</tt> is a prefix of this name, false otherwise
  140. */
  141. public boolean startsWith(Name n);
  142. /**
  143. * Determines whether this name ends with a specified suffix.
  144. * A name <tt>n</tt> is a suffix if it is equal to
  145. * <tt>getSuffix(size()-n.size())</tt>.
  146. *
  147. * @param n
  148. * the name to check
  149. * @return true if <tt>n</tt> is a suffix of this name, false otherwise
  150. */
  151. public boolean endsWith(Name n);
  152. /**
  153. * Adds the components of a name -- in order -- to the end of this name.
  154. *
  155. * @param suffix
  156. * the components to add
  157. * @return the updated name (not a new one)
  158. *
  159. * @throws InvalidNameException if <tt>suffix</tt> is not a valid name,
  160. * or if the addition of the components would violate the syntax
  161. * rules of this name
  162. */
  163. public Name addAll(Name suffix) throws InvalidNameException;
  164. /**
  165. * Adds the components of a name -- in order -- at a specified position
  166. * within this name.
  167. * Components of this name at or after the index of the first new
  168. * component are shifted up (away from 0) to accommodate the new
  169. * components.
  170. *
  171. * @param n
  172. * the components to add
  173. * @param posn
  174. * the index in this name at which to add the new
  175. * components. Must be in the range [0,size()].
  176. * @return the updated name (not a new one)
  177. *
  178. * @throws ArrayIndexOutOfBoundsException
  179. * if posn is outside the specified range
  180. * @throws InvalidNameException if <tt>n</tt> is not a valid name,
  181. * or if the addition of the components would violate the syntax
  182. * rules of this name
  183. */
  184. public Name addAll(int posn, Name n) throws InvalidNameException;
  185. /**
  186. * Adds a single component to the end of this name.
  187. *
  188. * @param comp
  189. * the component to add
  190. * @return the updated name (not a new one)
  191. *
  192. * @throws InvalidNameException if adding <tt>comp</tt> would violate
  193. * the syntax rules of this name
  194. */
  195. public Name add(String comp) throws InvalidNameException;
  196. /**
  197. * Adds a single component at a specified position within this name.
  198. * Components of this name at or after the index of the new component
  199. * are shifted up by one (away from index 0) to accommodate the new
  200. * component.
  201. *
  202. * @param comp
  203. * the component to add
  204. * @param posn
  205. * the index at which to add the new component.
  206. * Must be in the range [0,size()].
  207. * @return the updated name (not a new one)
  208. *
  209. * @throws ArrayIndexOutOfBoundsException
  210. * if posn is outside the specified range
  211. * @throws InvalidNameException if adding <tt>comp</tt> would violate
  212. * the syntax rules of this name
  213. */
  214. public Name add(int posn, String comp) throws InvalidNameException;
  215. /**
  216. * Removes a component from this name.
  217. * The component of this name at the specified position is removed.
  218. * Components with indexes greater than this position
  219. * are shifted down (toward index 0) by one.
  220. *
  221. * @param posn
  222. * the index of the component to remove.
  223. * Must be in the range [0,size()).
  224. * @return the component removed (a String)
  225. *
  226. * @throws ArrayIndexOutOfBoundsException
  227. * if posn is outside the specified range
  228. * @throws InvalidNameException if deleting the component
  229. * would violate the syntax rules of the name
  230. */
  231. public Object remove(int posn) throws InvalidNameException;
  232. }