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 */ isCaseIgnored()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 */ size()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 */ get(String attrID)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 */ getAll()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 */ getIDs()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 */ put(String attrID, Object val)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 */ put(Attribute attr)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 */ remove(String attrID)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 */ clone()177 Object clone(); 178 179 /** 180 * Use serialVersionUID from JNDI 1.1.1 for interoperability 181 */ 182 // static final long serialVersionUID = -7247874645443605347L; 183 } 184