001 /*
002 * Copyright 1999-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.naming.directory;
027
028 import java.util.Hashtable;
029 import java.util.Enumeration;
030
031 import javax.naming.NamingException;
032 import javax.naming.NamingEnumeration;
033
034 /**
035 * This interface represents a collection of attributes.
036 *<p>
037 * In a directory, named objects can have associated with them
038 * attributes. The Attributes interface represents a collection of attributes.
039 * For example, you can request from the directory the attributes
040 * associated with an object. Those attributes are returned in
041 * an object that implements the Attributes interface.
042 *<p>
043 * Attributes in an object that implements the Attributes interface are
044 * unordered. The object can have zero or more attributes.
045 * Attributes is either case-sensitive or case-insensitive (case-ignore).
046 * This property is determined at the time the Attributes object is
047 * created. (see BasicAttributes constructor for example).
048 * In a case-insensitive Attributes, the case of its attribute identifiers
049 * is ignored when searching for an attribute, or adding attributes.
050 * In a case-sensitive Attributes, the case is significant.
051 *<p>
052 * Note that updates to Attributes (such as adding or removing an attribute)
053 * do not affect the corresponding representation in the directory.
054 * Updates to the directory can only be effected
055 * using operations in the DirContext interface.
056 *
057 * @author Rosanna Lee
058 * @author Scott Seligman
059 * @version 1.17 07/05/05
060 *
061 * @see DirContext#getAttributes
062 * @see DirContext#modifyAttributes
063 * @see DirContext#bind
064 * @see DirContext#rebind
065 * @see DirContext#createSubcontext
066 * @see DirContext#search
067 * @see BasicAttributes
068 * @since 1.3
069 */
070
071 public interface Attributes extends Cloneable, java.io.Serializable {
072 /**
073 * Determines whether the attribute set ignores the case of
074 * attribute identifiers when retrieving or adding attributes.
075 * @return true if case is ignored; false otherwise.
076 */
077 boolean isCaseIgnored();
078
079 /**
080 * Retrieves the number of attributes in the attribute set.
081 *
082 * @return The nonnegative number of attributes in this attribute set.
083 */
084 int size();
085
086 /**
087 * Retrieves the attribute with the given attribute id from the
088 * attribute set.
089 *
090 * @param attrID The non-null id of the attribute to retrieve.
091 * If this attribute set ignores the character
092 * case of its attribute ids, the case of attrID
093 * is ignored.
094 * @return The attribute identified by attrID; null if not found.
095 * @see #put
096 * @see #remove
097 */
098 Attribute get(String attrID);
099
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 }
|