1. /*
  2. * @(#)Attribute.java 1.9 01/02/09
  3. *
  4. * Copyright 1999-2001 Sun Microsystems, Inc. All Rights Reserved.
  5. *
  6. * This software is the proprietary information of Sun Microsystems, Inc.
  7. * Use is subject to license terms.
  8. *
  9. */
  10. package javax.naming.directory;
  11. import java.util.Vector;
  12. import java.util.Enumeration;
  13. import java.util.NoSuchElementException;
  14. import javax.naming.NamingException;
  15. import javax.naming.NamingEnumeration;
  16. import javax.naming.OperationNotSupportedException;
  17. /**
  18. * This interface represents an attribute associated with a named object.
  19. *<p>
  20. * In a directory, named objects can have associated with them
  21. * attributes. The <tt>Attribute</tt> interface represents an attribute associated
  22. * with a named object. An attribute contains 0 or more, possibly null, values.
  23. * The attribute values can be ordered or unordered (see <tt>isOrdered()</tt>).
  24. * If the values are unordered, no duplicates are allowed.
  25. * If the values are ordered, duplicates are allowed.
  26. *<p>
  27. * The content and representation of an attribute and its values is defined by
  28. * the attribute's <em>schema</em>. The schema contains information
  29. * about the attribute's syntax and other properties about the attribute.
  30. * See <tt>getAttributeDefinition()</tt> and
  31. * <tt>getAttributeSyntaxDefinition()</tt>
  32. * for details regarding how to get schema information about an attribute
  33. * if the underlying directory service supports schemas.
  34. *<p>
  35. * Equality of two attributes is determined by the implementation class.
  36. * A simple implementation can use <tt>Object.equals()</tt> to determine equality
  37. * of attribute values, while a more sophisticated implementation might
  38. * make use of schema information to determine equality.
  39. * Similarly, one implementation might provide a static storage
  40. * structure which simply returns the values passed to its
  41. * constructor, while another implementation might define <tt>get()</tt> and
  42. * <tt>getAll()</tt>.
  43. * to get the values dynamically from the directory.
  44. *<p>
  45. * Note that updates to <tt>Attribute</tt> (such as adding or removing a
  46. * value) do not affect the corresponding representation of the attribute
  47. * in the directory. Updates to the directory can only be effected
  48. * using operations in the <tt>DirContext</tt> interface.
  49. *
  50. * @author Rosanna Lee
  51. * @author Scott Seligman
  52. * @version 1.9 01/02/09
  53. *
  54. * @see BasicAttribute
  55. * @since 1.3
  56. */
  57. public interface Attribute extends Cloneable, java.io.Serializable {
  58. /**
  59. * Retrieves an enumeration of the attribute's values.
  60. * The behaviour of this enumeration is unspecified
  61. * if the attribute's values are added, changed,
  62. * or removed while the enumeration is in progress.
  63. * If the attribute values are ordered, the enumeration's items
  64. * will be ordered.
  65. *
  66. * @return A non-null enumeration of the attribute's values.
  67. * Each element of the enumeration is a possibly null Object. The object's
  68. * class is the class of the attribute value. The element is null
  69. * if the attribute's value is null.
  70. * If the attribute has zero values, an empty enumeration
  71. * is returned.
  72. * @exception NamingException
  73. * If a naming exception was encountered while retrieving
  74. * the values.
  75. * @see #isOrdered
  76. */
  77. NamingEnumeration getAll() throws NamingException;
  78. /**
  79. * Retrieves one of this attribute's values.
  80. * If the attribute has more than one value and is unordered, any one of
  81. * the values is returned.
  82. * If the attribute has more than one value and is ordered, the
  83. * first value is returned.
  84. *
  85. * @return A possibly null object representing one of
  86. * the attribute's value. It is null if the attribute's value
  87. * is null.
  88. * @exception NamingException
  89. * If a naming exception was encountered while retrieving
  90. * the value.
  91. * @exception java.util.NoSuchElementException
  92. * If this attribute has no values.
  93. */
  94. Object get() throws NamingException;
  95. /**
  96. * Retrieves the number of values in this attribute.
  97. *
  98. * @return The nonnegative number of values in this attribute.
  99. */
  100. int size();
  101. /**
  102. * Retrieves the id of this attribute.
  103. *
  104. * @return The id of this attribute. It cannot be null.
  105. */
  106. String getID();
  107. /**
  108. * Determines whether a value is in the attribute.
  109. * Equality is determined by the implementation, which may use
  110. * <tt>Object.equals()</tt> or schema information to determine equality.
  111. *
  112. * @param attrVal The possibly null value to check. If null, check
  113. * whether the attribute has an attribute value whose value is null.
  114. * @return true if attrVal is one of this attribute's values; false otherwise.
  115. * @see java.lang.Object#equals
  116. * @see BasicAttribute#equals
  117. */
  118. boolean contains(Object attrVal);
  119. /**
  120. * Adds a new value to the attribute.
  121. * If the attribute values are unordered and
  122. * <tt>attrVal</tt> is already in the attribute, this method does nothing.
  123. * If the attribute values are ordered, <tt>attrVal</tt> is added to the end of
  124. * the list of attribute values.
  125. *<p>
  126. * Equality is determined by the implementation, which may use
  127. * <tt>Object.equals()</tt> or schema information to determine equality.
  128. *
  129. * @param attrVal The new possibly null value to add. If null, null
  130. * is added as an attribute value.
  131. * @return true if a value was added; false otherwise.
  132. */
  133. boolean add(Object attrVal);
  134. /**
  135. * Removes a specified value from the attribute.
  136. * If <tt>attrval</tt> is not in the attribute, this method does nothing.
  137. * If the attribute values are ordered, the first occurrence of
  138. * <tt>attrVal</tt> is removed and attribute values at indices greater
  139. * than the removed
  140. * value are shifted up towards the head of the list (and their indices
  141. * decremented by one).
  142. *<p>
  143. * Equality is determined by the implementation, which may use
  144. * <tt>Object.equals()</tt> or schema information to determine equality.
  145. *
  146. * @param attrval The possibly null value to remove from this attribute.
  147. * If null, remove the attribute value that is null.
  148. * @return true if the value was removed; false otherwise.
  149. */
  150. boolean remove(Object attrval);
  151. /**
  152. * Removes all values from this attribute.
  153. */
  154. void clear();
  155. /**
  156. * Retrieves the syntax definition associated with the attribute.
  157. * An attribute's syntax definition specifies the format
  158. * of the attribute's value(s). Note that this is different from
  159. * the attribute value's representation as a Java object. Syntax
  160. * definition refers to the directory's notion of <em>syntax</em>.
  161. *<p>
  162. * For example, even though a value might be
  163. * a Java String object, its directory syntax might be "Printable String"
  164. * or "Telephone Number". Or a value might be a byte array, and its
  165. * directory syntax is "JPEG" or "Certificate".
  166. * For example, if this attribute's syntax is "JPEG",
  167. * this method would return the syntax definition for "JPEG".
  168. * <p>
  169. * The information that you can retrieve from a syntax definition
  170. * is directory-dependent.
  171. *<p>
  172. * If an implementation does not support schemas, it should throw
  173. * OperationNotSupportedException. If an implementation does support
  174. * schemas, it should define this method to return the appropriate
  175. * information.
  176. * @return The attribute's syntax definition. Null if the implementation
  177. * supports schemas but this particular attribute does not have
  178. * any schema information.
  179. * @exception OperationNotSupportedException If getting the schema
  180. * is not supported.
  181. * @exception NamingException If a naming exception occurs while getting
  182. * the schema.
  183. */
  184. DirContext getAttributeSyntaxDefinition() throws NamingException;
  185. /**
  186. * Retrieves the attribute's schema definition.
  187. * An attribute's schema definition contains information
  188. * such as whether the attribute is multivalued or single-valued,
  189. * the matching rules to use when comparing the attribute's values.
  190. *
  191. * The information that you can retrieve from an attribute definition
  192. * is directory-dependent.
  193. *
  194. *<p>
  195. * If an implementation does not support schemas, it should throw
  196. * OperationNotSupportedException. If an implementation does support
  197. * schemas, it should define this method to return the appropriate
  198. * information.
  199. * @return This attribute's schema definition. Null if the implementation
  200. * supports schemas but this particular attribute does not have
  201. * any schema information.
  202. * @exception OperationNotSupportedException If getting the schema
  203. * is not supported.
  204. * @exception NamingException If a naming exception occurs while getting
  205. * the schema.
  206. */
  207. DirContext getAttributeDefinition() throws NamingException;
  208. /**
  209. * Makes a copy of the attribute.
  210. * The copy contains the same attribute values as the original attribute:
  211. * the attribute values are not themselves cloned.
  212. * Changes to the copy will not affect the original and vice versa.
  213. *
  214. * @return A non-null copy of the attribute.
  215. */
  216. Object clone();
  217. //----------- Methods to support ordered multivalued attributes
  218. /**
  219. * Determines whether this attribute's values are ordered.
  220. * If an attribute's values are ordered, duplicate values are allowed.
  221. * If an attribute's values are unordered, they are presented
  222. * in any order and there are no duplicate values.
  223. * @return true if this attribute's values are ordered; false otherwise.
  224. * @see #get(int)
  225. * @see #remove(int)
  226. * @see #add(int, java.lang.Object)
  227. * @see #set(int, java.lang.Object)
  228. */
  229. boolean isOrdered();
  230. /**
  231. * Retrieves the attribute value from the ordered list of attribute values.
  232. * This method returns the value at the <tt>ix</tt> index of the list of
  233. * attribute values.
  234. * If the attribute values are unordered,
  235. * this method returns the value that happens to be at that index.
  236. * @param ix The index of the value in the ordered list of attribute values.
  237. * 0 <= <tt>ix</tt> < <tt>size()</tt>.
  238. * @return The possibly null attribute value at index <tt>ix</tt>
  239. * null if the attribute value is null.
  240. * @exception NamingException If a naming exception was encountered while
  241. * retrieving the value.
  242. * @exception IndexOutOfBoundsException If <tt>ix</tt> is outside the specified range.
  243. */
  244. Object get(int ix) throws NamingException;
  245. /**
  246. * Removes an attribute value from the ordered list of attribute values.
  247. * This method removes the value at the <tt>ix</tt> index of the list of
  248. * attribute values.
  249. * If the attribute values are unordered,
  250. * this method removes the value that happens to be at that index.
  251. * Values located at indices greater than <tt>ix</tt> are shifted up towards
  252. * the front of the list (and their indices decremented by one).
  253. *
  254. * @param ix The index of the value to remove.
  255. * 0 <= <tt>ix</tt> < <tt>size()</tt>.
  256. * @return The possibly null attribute value at index <tt>ix</tt> that was removed;
  257. * null if the attribute value is null.
  258. * @exception IndexOutOfBoundsException If <tt>ix</tt> is outside the specified range.
  259. */
  260. Object remove(int ix);
  261. /**
  262. * Adds an attribute value to the ordered list of attribute values.
  263. * This method adds <tt>attrVal</tt> to the list of attribute values at
  264. * index <tt>ix</tt>.
  265. * Values located at indices at or greater than <tt>ix</tt> are
  266. * shifted down towards the end of the list (and their indices incremented
  267. * by one).
  268. * If the attribute values are unordered and already have <tt>attrVal</tt>,
  269. * <tt>IllegalStateException</tt> is thrown.
  270. *
  271. * @param ix The index in the ordered list of attribute values to add the new value.
  272. * 0 <= <tt>ix</tt> <= <tt>size()</tt>.
  273. * @param attrVal The possibly null attribute value to add; if null, null is
  274. * the value added.
  275. * @exception IndexOutOfBoundsException If <tt>ix</tt> is outside the specified range.
  276. * @exception IllegalStateException If the attribute values are unordered and
  277. * <tt>attrVal</tt> is one of those values.
  278. */
  279. void add(int ix, Object attrVal);
  280. /**
  281. * Sets an attribute value in the ordered list of attribute values.
  282. * This method sets the value at the <tt>ix</tt> index of the list of
  283. * attribute values to be <tt>attrVal</tt>. The old value is removed.
  284. * If the attribute values are unordered,
  285. * this method sets the value that happens to be at that index
  286. * to <tt>attrVal</tt>, unless <tt>attrVal</tt> is already one of the values.
  287. * In that case, <tt>IllegalStateException</tt> is thrown.
  288. *
  289. * @param ix The index of the value in the ordered list of attribute values.
  290. * 0 <= <tt>ix</tt> < <tt>size()</tt>.
  291. * @param attrVal The possibly null attribute value to use.
  292. * If null, 'null' replaces the old value.
  293. * @return The possibly null attribute value at index ix that was replaced.
  294. * Null if the attribute value was null.
  295. * @exception IndexOutOfBoundsException If <tt>ix</tt> is outside the specified range.
  296. * @exception IllegalStateException If <tt>attrVal</tt> already exists and the
  297. * attribute values are unordered.
  298. */
  299. Object set(int ix, Object attrVal);
  300. /**
  301. * Use serialVersionUID from JNDI 1.1.1 for interoperability.
  302. */
  303. static final long serialVersionUID = 8707690322213556804L;
  304. }