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  ;
12  import java.util.Enumeration  ;
13  
14  import javax.naming.NamingException  ;
15  import javax.naming.NamingEnumeration  ;
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  , java.io.Serializable   {
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   get(String   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  <? extends Attribute  > 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  <String  > 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   put(String   attrID, Object   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   put(Attribute   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   remove(String   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   clone();
161 
162     /**
163      * Use serialVersionUID from JNDI 1.1.1 for interoperability
164      */
165     // static final long serialVersionUID = -7247874645443605347L;
166 }
167
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags