View Javadoc
1   /*
2    * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  
27  package javax.naming.directory;
28  
29  import java.util.Hashtable;
30  import java.util.Enumeration;
31  
32  import javax.naming.NamingException;
33  import javax.naming.NamingEnumeration;
34  
35  /**
36    * This interface represents a collection of attributes.
37    *<p>
38    * In a directory, named objects can have associated with them
39    * attributes.  The Attributes interface represents a collection of attributes.
40    * For example, you can request from the directory the attributes
41    * associated with an object.  Those attributes are returned in
42    * an object that implements the Attributes interface.
43    *<p>
44    * Attributes in an object that implements the  Attributes interface are
45    * unordered. The object can have zero or more attributes.
46    * Attributes is either case-sensitive or case-insensitive (case-ignore).
47    * This property is determined at the time the Attributes object is
48    * created. (see BasicAttributes constructor for example).
49    * In a case-insensitive Attributes, the case of its attribute identifiers
50    * is ignored when searching for an attribute, or adding attributes.
51    * In a case-sensitive Attributes, the case is significant.
52    *<p>
53    * Note that updates to Attributes (such as adding or removing an attribute)
54    * do not affect the corresponding representation in the directory.
55    * Updates to the directory can only be effected
56    * using operations in the DirContext interface.
57    *
58    * @author Rosanna Lee
59    * @author Scott Seligman
60    *
61    * @see DirContext#getAttributes
62    * @see DirContext#modifyAttributes
63    * @see DirContext#bind
64    * @see DirContext#rebind
65    * @see DirContext#createSubcontext
66    * @see DirContext#search
67    * @see BasicAttributes
68    * @since 1.3
69    */
70  
71  public interface Attributes extends Cloneable, java.io.Serializable {
72      /**
73        * Determines whether the attribute set ignores the case of
74        * attribute identifiers when retrieving or adding attributes.
75        * @return true if case is ignored; false otherwise.
76        */
77      boolean isCaseIgnored();
78  
79      /**
80        * Retrieves the number of attributes in the attribute set.
81        *
82        * @return The nonnegative number of attributes in this attribute set.
83        */
84      int size();
85  
86      /**
87        * Retrieves the attribute with the given attribute id from the
88        * attribute set.
89        *
90        * @param attrID The non-null id of the attribute to retrieve.
91        *           If this attribute set ignores the character
92        *           case of its attribute ids, the case of attrID
93        *           is ignored.
94        * @return The attribute identified by attrID; null if not found.
95        * @see #put
96        * @see #remove
97        */
98      Attribute get(String attrID);
99  
100     /**
101       * Retrieves an enumeration of the attributes in the attribute set.
102       * The effects of updates to this attribute set on this enumeration
103       * are undefined.
104       *
105       * @return A non-null enumeration of the attributes in this attribute set.
106       *         Each element of the enumeration is of class <tt>Attribute</tt>.
107       *         If attribute set has zero attributes, an empty enumeration
108       *         is returned.
109       */
110     NamingEnumeration<? extends Attribute> getAll();
111 
112     /**
113       * Retrieves an enumeration of the ids of the attributes in the
114       * attribute set.
115       * The effects of updates to this attribute set on this enumeration
116       * are undefined.
117       *
118       * @return A non-null enumeration of the attributes' ids in
119       *         this attribute set. Each element of the enumeration is
120       *         of class String.
121       *         If attribute set has zero attributes, an empty enumeration
122       *         is returned.
123       */
124     NamingEnumeration<String> getIDs();
125 
126     /**
127       * Adds a new attribute to the attribute set.
128       *
129       * @param attrID   non-null The id of the attribute to add.
130       *           If the attribute set ignores the character
131       *           case of its attribute ids, the case of attrID
132       *           is ignored.
133       * @param val      The possibly null value of the attribute to add.
134       *                 If null, the attribute does not have any values.
135       * @return The Attribute with attrID that was previous in this attribute set;
136       *         null if no such attribute existed.
137       * @see #remove
138       */
139     Attribute put(String attrID, Object val);
140 
141     /**
142       * Adds a new attribute to the attribute set.
143       *
144       * @param attr     The non-null attribute to add.
145       *                 If the attribute set ignores the character
146       *                 case of its attribute ids, the case of
147       *                 attr's identifier is ignored.
148       * @return The Attribute with the same ID as attr that was previous
149       *         in this attribute set;
150       *         null if no such attribute existed.
151       * @see #remove
152       */
153     Attribute put(Attribute attr);
154 
155     /**
156       * Removes the attribute with the attribute id 'attrID' from
157       * the attribute set. If the attribute does not exist, ignore.
158       *
159       * @param attrID   The non-null id of the attribute to remove.
160       *                 If the attribute set ignores the character
161       *                 case of its attribute ids, the case of
162       *                 attrID is ignored.
163       * @return The Attribute with the same ID as attrID that was previous
164       *         in the attribute set;
165       *         null if no such attribute existed.
166       */
167     Attribute remove(String attrID);
168 
169     /**
170       * Makes a copy of the attribute set.
171       * The new set contains the same attributes as the original set:
172       * the attributes are not themselves cloned.
173       * Changes to the copy will not affect the original and vice versa.
174       *
175       * @return A non-null copy of this attribute set.
176       */
177     Object clone();
178 
179     /**
180      * Use serialVersionUID from JNDI 1.1.1 for interoperability
181      */
182     // static final long serialVersionUID = -7247874645443605347L;
183 }