KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > naming > directory > Attributes


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
8
9 package javax.naming.directory;
10
11 import java.util.Hashtable JavaDoc;
12 import java.util.Enumeration JavaDoc;
13
14 import javax.naming.NamingException JavaDoc;
15 import javax.naming.NamingEnumeration JavaDoc;
16
17 /**
18   * This interface represents a collection of attributes.
19   *<p>
20   * In a directory, named objects can have associated with them
21   * attributes. The Attributes interface represents a collection of attributes.
22   * For example, you can request from the directory the attributes
23   * associated with an object. Those attributes are returned in
24   * an object that implements the Attributes interface.
25   *<p>
26   * Attributes in an object that implements the Attributes interface are
27   * unordered. The object can have zero or more attributes.
28   * Attributes is either case-sensitive or case-insensitive (case-ignore).
29   * This property is determined at the time the Attributes object is
30   * created. (see BasicAttributes constructor for example).
31   * In a case-insensitive Attributes, the case of its attribute identifiers
32   * is ignored when searching for an attribute, or adding attributes.
33   * In a case-sensitive Attributes, the case is significant.
34   *<p>
35   * Note that updates to Attributes (such as adding or removing an attribute)
36   * do not affect the corresponding representation in the directory.
37   * Updates to the directory can only be effected
38   * using operations in the DirContext interface.
39   *
40   * @author Rosanna Lee
41   * @author Scott Seligman
42   * @version 1.10 04/05/05
43   *
44   * @see DirContext#getAttributes
45   * @see DirContext#modifyAttributes
46   * @see DirContext#bind
47   * @see DirContext#rebind
48   * @see DirContext#createSubcontext
49   * @see DirContext#search
50   * @see BasicAttributes
51   * @since 1.3
52   */

53
54 public interface Attributes extends Cloneable JavaDoc, java.io.Serializable JavaDoc {
55     /**
56       * Determines whether the attribute set ignores the case of
57       * attribute identifiers when retrieving or adding attributes.
58       * @return true if case is ignored; false otherwise.
59       */

60     boolean isCaseIgnored();
61
62     /**
63       * Retrieves the number of attributes in the attribute set.
64       *
65       * @return The nonnegative number of attributes in this attribute set.
66       */

67     int size();
68
69     /**
70       * Retrieves the attribute with the given attribute id from the
71       * attribute set.
72       *
73       * @param attrID The non-null id of the attribute to retrieve.
74       * If this attribute set ignores the character
75       * case of its attribute ids, the case of attrID
76       * is ignored.
77       * @return The attribute identified by attrID; null if not found.
78       * @see #put
79       * @see #remove
80       */

81     Attribute JavaDoc get(String JavaDoc attrID);
82
83     /**
84       * Retrieves an enumeration of the attributes in the attribute set.
85       * The effects of updates to this attribute set on this enumeration
86       * are undefined.
87       *
88       * @return A non-null enumeration of the attributes in this attribute set.
89       * Each element of the enumeration is of class <tt>Attribute</tt>.
90       * If attribute set has zero attributes, an empty enumeration
91       * is returned.
92       */

93     NamingEnumeration JavaDoc<? extends Attribute JavaDoc> getAll();
94
95     /**
96       * Retrieves an enumeration of the ids of the attributes in the
97       * attribute set.
98       * The effects of updates to this attribute set on this enumeration
99       * are undefined.
100       *
101       * @return A non-null enumeration of the attributes' ids in
102       * this attribute set. Each element of the enumeration is
103       * of class String.
104       * If attribute set has zero attributes, an empty enumeration
105       * is returned.
106       */

107     NamingEnumeration JavaDoc<String JavaDoc> getIDs();
108
109     /**
110       * Adds a new attribute to the attribute set.
111       *
112       * @param attrID non-null The id of the attribute to add.
113       * If the attribute set ignores the character
114       * case of its attribute ids, the case of attrID
115       * is ignored.
116       * @param val The possibly null value of the attribute to add.
117       * If null, the attribute does not have any values.
118       * @return The Attribute with attrID that was previous in this attribute set;
119       * null if no such attribute existed.
120       * @see #remove
121       */

122     Attribute JavaDoc put(String JavaDoc attrID, Object JavaDoc val);
123
124     /**
125       * Adds a new attribute to the attribute set.
126       *
127       * @param attr The non-null attribute to add.
128       * If the attribute set ignores the character
129       * case of its attribute ids, the case of
130       * attr's identifier is ignored.
131       * @return The Attribute with the same ID as attr that was previous
132       * in this attribute set;
133       * null if no such attribute existed.
134       * @see #remove
135       */

136     Attribute JavaDoc put(Attribute JavaDoc attr);
137
138     /**
139       * Removes the attribute with the attribute id 'attrID' from
140       * the attribute set. If the attribute does not exist, ignore.
141       *
142       * @param attrID The non-null id of the attribute to remove.
143       * If the attribute set ignores the character
144       * case of its attribute ids, the case of
145       * attrID is ignored.
146       * @return The Attribute with the same ID as attrID that was previous
147       * in the attribute set;
148       * null if no such attribute existed.
149       */

150     Attribute JavaDoc remove(String JavaDoc attrID);
151
152     /**
153       * Makes a copy of the attribute set.
154       * The new set contains the same attributes as the original set:
155       * the attributes are not themselves cloned.
156       * Changes to the copy will not affect the original and vice versa.
157       *
158       * @return A non-null copy of this attribute set.
159       */

160     Object JavaDoc clone();
161
162     /**
163      * Use serialVersionUID from JNDI 1.1.1 for interoperability
164      */

165     // static final long serialVersionUID = -7247874645443605347L;
166
}
167
Popular Tags