001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 */ 019 package org.apache.directory.shared.ldap.entry; 020 021 022 import java.io.Externalizable; 023 import java.util.Iterator; 024 import java.util.List; 025 026 import org.apache.directory.shared.ldap.exception.LdapException; 027 028 import org.apache.directory.shared.ldap.name.DN; 029 030 031 /** 032 * <p> 033 * This interface represent a LDAP entry. An LDAP entry contains : 034 * <li> A distinguished name (DN)</li> 035 * <li> A list of attributes</li> 036 * </p> 037 * <p> 038 * The available methods on this object are described in this interface. 039 * </p> 040 * <p> 041 * This interface is used by the serverEntry and clientEntry interfaces. 042 *</p> 043 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 044 * @version $Rev$, $Date$ 045 */ 046 public interface Entry extends Cloneable, Iterable<EntryAttribute>, Externalizable 047 { 048 /** 049 * Remove all the attributes for this entry. The DN is not reset 050 */ 051 void clear(); 052 053 054 /** 055 * Clone the current entry 056 */ 057 Entry clone(); 058 059 060 /** 061 * Get this entry's DN. 062 * 063 * @return The entry's DN 064 */ 065 DN getDn(); 066 067 068 /** 069 * Tells if an entry as a specific ObjectClass value 070 * 071 * @param objectClass The ObjectClassw we want to check 072 * @return <code>true</code> if the ObjectClass value is present 073 * in the ObjectClass attribute 074 */ 075 boolean hasObjectClass( String objectClass ); 076 077 078 /** 079 * <p> 080 * Returns the attribute with the specified alias. The return value 081 * is <code>null</code> if no match is found. 082 * </p> 083 * <p>An Attribute with an id different from the supplied alias may 084 * be returned: for example a call with 'cn' may in some implementations 085 * return an Attribute whose getId() field returns 'commonName'. 086 * </p> 087 * 088 * @param alias an aliased name of the attribute identifier 089 * @return the attribute associated with the alias 090 */ 091 EntryAttribute get( String alias ); 092 093 094 /** 095 * <p> 096 * Put some new ClientAttribute using the User Provided ID. 097 * No value is inserted. 098 * </p> 099 * <p> 100 * If an existing Attribute is found, it will be replaced by an 101 * empty attribute, and returned to the caller. 102 * </p> 103 * 104 * @param upIds The user provided IDs of the AttributeTypes to add. 105 * @return A list of replaced Attributes. 106 */ 107 List<EntryAttribute> set( String... upIds ); 108 109 110 /** 111 * Set this entry's DN. 112 * 113 * @param dn The DN associated with this entry 114 */ 115 void setDn( DN dn ); 116 117 118 /** 119 * Returns an enumeration containing the zero or more attributes in the 120 * collection. The behavior of the enumeration is not specified if the 121 * attribute collection is changed. 122 * 123 * @return an enumeration of all contained attributes 124 */ 125 Iterator<EntryAttribute> iterator(); 126 127 128 /** 129 * Add some Attributes to the current Entry. 130 * 131 * @param attributes The attributes to add 132 * @throws LdapException If we can't add any of the attributes 133 */ 134 void add( EntryAttribute... attributes ) throws LdapException; 135 136 137 /** 138 * Add some String values to the current Entry. 139 * 140 * @param upId The user provided ID of the attribute we want to add 141 * some values to 142 * @param values The list of String values to add 143 * @throws LdapException If we can't add any of the values 144 */ 145 void add( String upId, String... values ) throws LdapException; 146 147 148 /** 149 * Add some binary values to the current Entry. 150 * 151 * @param upId The user provided ID of the attribute we want to add 152 * some values to 153 * @param values The list of binary values to add 154 * @throws LdapException If we can't add any of the values 155 */ 156 void add( String upId, byte[]... values ) throws LdapException; 157 158 159 /** 160 * Add some Values to the current Entry. 161 * 162 * @param upId The user provided ID of the attribute we want to add 163 * some values to 164 * @param values The list of Values to add 165 * @throws LdapException If we can't add any of the values 166 */ 167 void add( String upId, Value<?>... values ) throws LdapException; 168 169 170 /** 171 * <p> 172 * Places attributes in the attribute collection. 173 * </p> 174 * <p>If there is already an attribute with the same ID as any of the 175 * new attributes, the old ones are removed from the collection and 176 * are returned by this method. If there was no attribute with the 177 * same ID the return value is <code>null</code>. 178 *</p> 179 * 180 * @param attributes the attributes to be put 181 * @return the old attributes with the same OID, if exist; otherwise 182 * <code>null</code> 183 * @exception LdapException if the operation fails 184 */ 185 List<EntryAttribute> put( EntryAttribute... attributes ) throws LdapException; 186 187 188 /** 189 * <p> 190 * Put an attribute (represented by its ID and some binary values) into an entry. 191 * </p> 192 * <p> 193 * If the attribute already exists, the previous attribute will be 194 * replaced and returned. 195 * </p> 196 * 197 * @param upId The attribute ID 198 * @param values The list of binary values to put. It can be empty. 199 * @return The replaced attribute 200 */ 201 EntryAttribute put( String upId, byte[]... values ); 202 203 204 /** 205 * <p> 206 * Put an attribute (represented by its ID and some String values) into an entry. 207 * </p> 208 * <p> 209 * If the attribute already exists, the previous attribute will be 210 * replaced and returned. 211 * </p> 212 * 213 * @param upId The attribute ID 214 * @param values The list of String values to put. It can be empty. 215 * @return The replaced attribute 216 */ 217 EntryAttribute put( String upId, String... values ); 218 219 220 /** 221 * <p> 222 * Put an attribute (represented by its ID and some values) into an entry. 223 * </p> 224 * <p> 225 * If the attribute already exists, the previous attribute will be 226 * replaced and returned. 227 * </p> 228 * 229 * @param upId The attribute ID 230 * @param values The list of values to put. It can be empty. 231 * @return The replaced attribute 232 */ 233 EntryAttribute put( String upId, Value<?>... values ); 234 235 236 /** 237 * Removes the specified attributes. The removed attributes are 238 * returned by this method. If there were no attribute the return value 239 * is <code>null</code>. 240 * 241 * @param attributes the attributes to be removed 242 * @return the removed attribute, if exists; otherwise <code>null</code> 243 */ 244 List<EntryAttribute> remove( EntryAttribute... attributes ) throws LdapException; 245 246 247 /** 248 * <p> 249 * Removes the specified binary values from an attribute. 250 * </p> 251 * <p> 252 * If at least one value is removed, this method returns <code>true</code>. 253 * </p> 254 * <p> 255 * If there is no more value after having removed the values, the attribute 256 * will be removed too. 257 * </p> 258 * <p> 259 * If the attribute does not exist, nothing is done and the method returns 260 * <code>false</code> 261 * </p> 262 * 263 * @param upId The attribute ID 264 * @param attributes the attributes to be removed 265 * @return <code>true</code> if at least a value is removed, <code>false</code> 266 * if not all the values have been removed or if the attribute does not exist. 267 */ 268 boolean remove( String upId, byte[]... values ) throws LdapException; 269 270 271 /** 272 * <p> 273 * Removes the specified String values from an attribute. 274 * </p> 275 * <p> 276 * If at least one value is removed, this method returns <code>true</code>. 277 * </p> 278 * <p> 279 * If there is no more value after havong removed the values, the attribute 280 * will be removed too. 281 * </p> 282 * <p> 283 * If the attribute does not exist, nothing is done and the method returns 284 * <code>false</code> 285 * </p> 286 * 287 * @param upId The attribute ID 288 * @param attributes the attributes to be removed 289 * @return <code>true</code> if at least a value is removed, <code>false</code> 290 * if no values have been removed or if the attribute does not exist. 291 */ 292 boolean remove( String upId, String... values ) throws LdapException; 293 294 295 /** 296 * <p> 297 * Removes the specified values from an attribute. 298 * </p> 299 * <p> 300 * If at least one value is removed, this method returns <code>true</code>. 301 * </p> 302 * <p> 303 * If there is no more value after having removed the values, the attribute 304 * will be removed too. 305 * </p> 306 * <p> 307 * If the attribute does not exist, nothing is done and the method returns 308 * <code>false</code> 309 * </p> 310 * 311 * @param upId The attribute ID 312 * @param attributes the attributes to be removed 313 * @return <code>true</code> if at least a value is removed, <code>false</code> 314 * if not all the values have been removed or if the attribute does not exist. 315 */ 316 boolean remove( String upId, Value<?>... values ) throws LdapException; 317 318 319 /** 320 * <p> 321 * Removes the attribute with the specified alias. 322 * </p> 323 * <p> 324 * The removed attribute are returned by this method. 325 * </p> 326 * <p> 327 * If there is no attribute with the specified alias, 328 * the return value is <code>null</code>. 329 * </p> 330 * 331 * @param attributes an aliased name of the attribute to be removed 332 * @return the removed attributes, if any, as a list; otherwise <code>null</code> 333 */ 334 List<EntryAttribute> removeAttributes( String... attributes ); 335 336 337 /** 338 * <p> 339 * Checks if an entry contains a list of attributes. 340 * </p> 341 * <p> 342 * If the list is null or empty, this method will return <code>true</code> 343 * if the entry has no attribute, <code>false</code> otherwise. 344 * </p> 345 * 346 * @param attributes The Attributes to look for 347 * @return <code>true</code> if all the attributes are found within 348 * the entry, <code>false</code> if at least one of them is not present. 349 * @throws LdapException If the attribute does not exist 350 */ 351 boolean contains( EntryAttribute... attributes ) throws LdapException; 352 353 354 /** 355 * Checks if an entry contains an attribute with some binary values. 356 * 357 * @param id The Attribute we are looking for. 358 * @param values The searched values. 359 * @return <code>true</code> if all the values are found within the attribute, 360 * false if at least one value is not present or if the ID is not valid. 361 */ 362 boolean contains( String upId, byte[]... values ); 363 364 365 /** 366 * Checks if an entry contains an attribute with some String values. 367 * 368 * @param id The Attribute we are looking for. 369 * @param values The searched values. 370 * @return <code>true</code> if all the values are found within the attribute, 371 * false if at least one value is not present or if the ID is not valid. 372 */ 373 boolean contains( String upId, String... values ); 374 375 376 /** 377 * Checks if an entry contains an attribute with some values. 378 * 379 * @param id The Attribute we are looking for. 380 * @param values The searched values. 381 * @return <code>true</code> if all the values are found within the attribute, 382 * false if at least one value is not present or if the ID is not valid. 383 */ 384 boolean contains( String upId, Value<?>... values ); 385 386 387 /** 388 * Checks if an entry contains some specific attributes. 389 * 390 * @param attributes The Attributes to look for. 391 * @return <code>true</code> if the attributes are all found within the entry. 392 */ 393 boolean containsAttribute( String... attributes ); 394 395 396 /** 397 * Returns the number of attributes. 398 * 399 * @return the number of attributes 400 */ 401 int size(); 402 }