1. /*
  2. * @(#)Attributes.java 1.10 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. package javax.naming.directory;
  8. import java.util.Hashtable;
  9. import java.util.Enumeration;
  10. import javax.naming.NamingException;
  11. import javax.naming.NamingEnumeration;
  12. /**
  13. * This interface represents a collection of attributes.
  14. *<p>
  15. * In a directory, named objects can have associated with them
  16. * attributes. The Attributes interface represents a collection of attributes.
  17. * For example, you can request from the directory the attributes
  18. * associated with an object. Those attributes are returned in
  19. * an object that implements the Attributes interface.
  20. *<p>
  21. * Attributes in an object that implements the Attributes interface are
  22. * unordered. The object can have zero or more attributes.
  23. * Attributes is either case-sensitive or case-insensitive (case-ignore).
  24. * This property is determined at the time the Attributes object is
  25. * created. (see BasicAttributes constructor for example).
  26. * In a case-insensitive Attributes, the case of its attribute identifiers
  27. * is ignored when searching for an attribute, or adding attributes.
  28. * In a case-sensitive Attributes, the case is significant.
  29. *<p>
  30. * Note that updates to Attributes (such as adding or removing an attribute)
  31. * do not affect the corresponding representation in the directory.
  32. * Updates to the directory can only be effected
  33. * using operations in the DirContext interface.
  34. *
  35. * @author Rosanna Lee
  36. * @author Scott Seligman
  37. * @version 1.10 04/05/05
  38. *
  39. * @see DirContext#getAttributes
  40. * @see DirContext#modifyAttributes
  41. * @see DirContext#bind
  42. * @see DirContext#rebind
  43. * @see DirContext#createSubcontext
  44. * @see DirContext#search
  45. * @see BasicAttributes
  46. * @since 1.3
  47. */
  48. public interface Attributes extends Cloneable, java.io.Serializable {
  49. /**
  50. * Determines whether the attribute set ignores the case of
  51. * attribute identifiers when retrieving or adding attributes.
  52. * @return true if case is ignored; false otherwise.
  53. */
  54. boolean isCaseIgnored();
  55. /**
  56. * Retrieves the number of attributes in the attribute set.
  57. *
  58. * @return The nonnegative number of attributes in this attribute set.
  59. */
  60. int size();
  61. /**
  62. * Retrieves the attribute with the given attribute id from the
  63. * attribute set.
  64. *
  65. * @param attrID The non-null id of the attribute to retrieve.
  66. * If this attribute set ignores the character
  67. * case of its attribute ids, the case of attrID
  68. * is ignored.
  69. * @return The attribute identified by attrID; null if not found.
  70. * @see #put
  71. * @see #remove
  72. */
  73. Attribute get(String attrID);
  74. /**
  75. * Retrieves an enumeration of the attributes in the attribute set.
  76. * The effects of updates to this attribute set on this enumeration
  77. * are undefined.
  78. *
  79. * @return A non-null enumeration of the attributes in this attribute set.
  80. * Each element of the enumeration is of class <tt>Attribute</tt>.
  81. * If attribute set has zero attributes, an empty enumeration
  82. * is returned.
  83. */
  84. NamingEnumeration<? extends Attribute> getAll();
  85. /**
  86. * Retrieves an enumeration of the ids of the attributes in the
  87. * attribute set.
  88. * The effects of updates to this attribute set on this enumeration
  89. * are undefined.
  90. *
  91. * @return A non-null enumeration of the attributes' ids in
  92. * this attribute set. Each element of the enumeration is
  93. * of class String.
  94. * If attribute set has zero attributes, an empty enumeration
  95. * is returned.
  96. */
  97. NamingEnumeration<String> getIDs();
  98. /**
  99. * Adds a new attribute to the attribute set.
  100. *
  101. * @param attrID non-null The id of the attribute to add.
  102. * If the attribute set ignores the character
  103. * case of its attribute ids, the case of attrID
  104. * is ignored.
  105. * @param val The possibly null value of the attribute to add.
  106. * If null, the attribute does not have any values.
  107. * @return The Attribute with attrID that was previous in this attribute set;
  108. * null if no such attribute existed.
  109. * @see #remove
  110. */
  111. Attribute put(String attrID, Object val);
  112. /**
  113. * Adds a new attribute to the attribute set.
  114. *
  115. * @param attr The non-null attribute to add.
  116. * If the attribute set ignores the character
  117. * case of its attribute ids, the case of
  118. * attr's identifier is ignored.
  119. * @return The Attribute with the same ID as attr that was previous
  120. * in this attribute set;
  121. * null if no such attribute existed.
  122. * @see #remove
  123. */
  124. Attribute put(Attribute attr);
  125. /**
  126. * Removes the attribute with the attribute id 'attrID' from
  127. * the attribute set. If the attribute does not exist, ignore.
  128. *
  129. * @param attrID The non-null id of the attribute to remove.
  130. * If the attribute set ignores the character
  131. * case of its attribute ids, the case of
  132. * attrID is ignored.
  133. * @return The Attribute with the same ID as attrID that was previous
  134. * in the attribute set;
  135. * null if no such attribute existed.
  136. */
  137. Attribute remove(String attrID);
  138. /**
  139. * Makes a copy of the attribute set.
  140. * The new set contains the same attributes as the original set:
  141. * the attributes are not themselves cloned.
  142. * Changes to the copy will not affect the original and vice versa.
  143. *
  144. * @return A non-null copy of this attribute set.
  145. */
  146. Object clone();
  147. /**
  148. * Use serialVersionUID from JNDI 1.1.1 for interoperability
  149. */
  150. // static final long serialVersionUID = -7247874645443605347L;
  151. }