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.util.List; 023 import java.util.Set; 024 025 import org.apache.directory.shared.ldap.exception.LdapException; 026 import org.apache.directory.shared.ldap.schema.AttributeType; 027 028 029 /** 030 * A server side entry which is schema aware. 031 * 032 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 033 * @version $Rev$, $Date$ 034 */ 035 public interface ServerEntry extends Entry, Cloneable 036 { 037 /** 038 * <p> 039 * Add an attribute (represented by its AttributeType and some binary values) into an 040 * entry. 041 * </p> 042 * <p> 043 * If we already have an attribute with the same values, the duplicated values 044 * are not added (duplicated values are not allowed) 045 * </p> 046 * <p> 047 * If the value cannot be added, or if the AttributeType is null or invalid, 048 * a LdapException is thrown. 049 * </p> 050 * 051 * @param attributeType The attribute Type. 052 * @param values The list of binary values to inject. It can be empty. 053 * @throws LdapException If the attribute does not exist 054 */ 055 void add( AttributeType attributeType, byte[]... values ) throws LdapException; 056 057 058 /** 059 * <p> 060 * Add an attribute (represented by its AttributeType and some String values) into an 061 * entry. 062 * </p> 063 * <p> 064 * If we already have an attribute with the same values, the duplicated values 065 * are not added (duplicated values are not allowed) 066 * </p> 067 * <p> 068 * If the value cannot be added, or if the AttributeType is null or invalid, 069 * a LdapException is thrown. 070 * </p> 071 * 072 * @param attributeType The attribute Type 073 * @param values The list of binary values to inject. It can be empty 074 * @throws LdapException If the attribute does not exist 075 */ 076 void add( AttributeType attributeType, String... values ) throws LdapException; 077 078 079 /** 080 * <p> 081 * Add an attribute (represented by its AttributeType and some values) into an 082 * entry. 083 * </p> 084 * <p> 085 * If we already have an attribute with the same values, the duplicated values 086 * are not added (duplicated values are not allowed) 087 * </p> 088 * <p> 089 * If the value cannot be added, or if the AttributeType is null or invalid, 090 * a LdapException is thrown. 091 * </p> 092 * 093 * @param attributeType The attribute Type 094 * @param values The list of binary values to inject. It can be empty 095 * @throws LdapException If the attribute does not exist 096 */ 097 void add( AttributeType attributeType, Value<?>... values ) throws LdapException; 098 099 100 /** 101 * <p> 102 * Add an attribute (represented by its AttributeType and some binary values) into an 103 * entry. Set the User Provider ID at the same time 104 * </p> 105 * <p> 106 * If we already have an attribute with the same values, the duplicated values 107 * are not added (duplicated values are not allowed) 108 * </p> 109 * <p> 110 * If the value cannot be added, or if the AttributeType is null or invalid, 111 * a LdapException is thrown. 112 * </p> 113 * 114 * @param upId The user provided ID for the added AttributeType 115 * @param attributeType The attribute Type. 116 * @param values The list of binary values to add. It can be empty. 117 * @throws LdapException If the attribute does not exist 118 */ 119 void add( String upId, AttributeType attributeType, byte[]... values ) throws LdapException; 120 121 122 /** 123 * <p> 124 * Add an attribute (represented by its AttributeType and some String values) into an 125 * entry. Set the User Provider ID at the same time 126 * </p> 127 * <p> 128 * If we already have an attribute with the same values, the duplicated values 129 * are not added (duplicated values are not allowed) 130 * </p> 131 * <p> 132 * If the value cannot be added, or if the AttributeType is null or invalid, 133 * a LdapException is thrown. 134 * </p> 135 * 136 * @param upId The user provided ID for the added AttributeType 137 * @param attributeType The attribute Type. 138 * @param values The list of binary values to add. It can be empty. 139 * @throws LdapException If the attribute does not exist 140 */ 141 void add( String upId, AttributeType attributeType, String... values ) throws LdapException; 142 143 144 /** 145 * <p> 146 * Add an attribute (represented by its AttributeType and some values) into an 147 * entry. Set the User Provider ID at the same time 148 * </p> 149 * <p> 150 * If we already have an attribute with the same values, nothing is done 151 * (duplicated values are not allowed) 152 * </p> 153 * <p> 154 * If the value cannot be added, or if the AttributeType is null or invalid, 155 * a LdapException is thrown. 156 * </p> 157 * 158 * @param upId The user provided ID for the added AttributeType 159 * @param attributeType The attribute Type. 160 * @param values The list of values to add. It can be empty. 161 * @throws LdapException If the attribute does not exist 162 */ 163 void add( String upId, AttributeType attributeType, Value<?>... values ) throws LdapException; 164 165 166 // ----------------------------------------------------------------------- 167 // Container (get/put/remove) Methods 168 // ----------------------------------------------------------------------- 169 /** 170 * Checks if an entry contains an attribute with some given binary values. 171 * 172 * @param attributeType The Attribute we are looking for. 173 * @param values The searched values. 174 * @return <code>true</code> if all the values are found within the attribute, 175 * <code>false</code> otherwise, or if the attributes does not exist. 176 * @throws LdapException If the attribute does not exists 177 */ 178 boolean contains( AttributeType attributeType, byte[]... values ); 179 180 181 /** 182 * Checks if an entry contains an attribute with some given String values. 183 * 184 * @param attributeType The Attribute we are looking for. 185 * @param values The searched values. 186 * @return <code>true</code> if all the values are found within the attribute, 187 * <code>false</code> otherwise, or if the attributes does not exist. 188 * @throws LdapException If the attribute does not exists 189 */ 190 boolean contains( AttributeType attributeType, String... values ); 191 192 193 /** 194 * Checks if an entry contains an attribute with some given binary values. 195 * 196 * @param attributeType The Attribute we are looking for. 197 * @param values The searched values. 198 * @return <code>true</code> if all the values are found within the attribute, 199 * <code>false</code> otherwise, or if the attributes does not exist. 200 * @throws LdapException If the attribute does not exists 201 */ 202 boolean contains( AttributeType attributeType, Value<?>... values ); 203 204 205 /** 206 * Checks if an entry contains a specific AttributeType. 207 * 208 * @param attributeType The AttributeType to look for. 209 * @return <code>true</code> if the attribute is found within the entry. 210 */ 211 boolean containsAttribute( AttributeType attributeType ); 212 213 214 /** 215 * <p> 216 * Returns the attribute with the specified AttributeType. The return value 217 * is <code>null</code> if no match is found. 218 * </p> 219 * 220 * @param attributeType The attributeType we are looking for. 221 * @return the attribute associated with the AttributeType. 222 */ 223 /** 224 * Returns the attribute associated with an AttributeType 225 * 226 * @param the AttributeType we are looking for 227 * @return the associated attribute 228 */ 229 EntryAttribute get( AttributeType attributeType ); 230 231 232 /** 233 * Gets all the attributes type 234 * 235 * @return The combined set of all the attributes. 236 */ 237 Set<AttributeType> getAttributeTypes(); 238 239 240 /** 241 * Tells if an entry has a specific ObjectClass Attribute 242 * 243 * @param objectClass The ObjectClass we want to check 244 * @return <code>true</code> if the ObjectClass value is present 245 * in the ObjectClass attribute 246 */ 247 boolean hasObjectClass( EntryAttribute objectClass ); 248 249 250 /** 251 * Fail fast check performed to determine entry consistency according to schema 252 * characteristics. 253 * 254 * @return true if the entry, it's attributes and their values are consistent 255 * with the schema 256 */ 257 boolean isValid(); 258 259 260 /** 261 * Check performed to determine entry consistency according to the schema 262 * requirements of a particular objectClass. The entry must be of that objectClass 263 * to return true: meaning if the entry's objectClass attribute does not contain 264 * the objectClass argument, then false should be returned. 265 * 266 * @param objectClass the objectClass to use while checking for validity 267 * @return true if the entry, it's attributes and their values are consistent 268 * with the objectClass 269 */ 270 boolean isValid( String objectClass ); 271 272 273 /** 274 * Check performed to determine entry consistency according to the schema 275 * requirements of a particular objectClass. The entry must be of that objectClass 276 * to return true: meaning if the entry's objectClass attribute does not contain 277 * the objectClass argument, then false should be returned. 278 * 279 * @param objectClass the objectClass to use while checking for validity 280 * @return true if the entry, it's attributes and their values are consistent 281 * with the objectClass 282 */ 283 boolean isValid( EntryAttribute objectClass ); 284 285 286 /** 287 * <p> 288 * Places a new attribute with the supplied AttributeType and binary values 289 * into the attribute collection. 290 * </p> 291 * <p> 292 * If there is already an attribute with the same AttributeType, the old 293 * one is removed from the collection and is returned by this method. 294 * </p> 295 * <p> 296 * This method provides a mechanism to put an attribute with a 297 * <code>null</code> value: the value may be <code>null</code>. 298 * 299 * @param attributeType the type of the new attribute to be put 300 * @param values the binary values of the new attribute to be put 301 * @return the old attribute with the same identifier, if exists; otherwise 302 * <code>null</code> 303 * @throws LdapException if there are failures 304 */ 305 EntryAttribute put( AttributeType attributeType, byte[]... values ) throws LdapException; 306 307 308 /** 309 * <p> 310 * Places a new attribute with the supplied AttributeType and String values 311 * into the attribute collection. 312 * </p> 313 * <p> 314 * If there is already an attribute with the same AttributeType, the old 315 * one is removed from the collection and is returned by this method. 316 * </p> 317 * <p> 318 * This method provides a mechanism to put an attribute with a 319 * <code>null</code> value: the value may be <code>null</code>. 320 * 321 * @param attributeType the type of the new attribute to be put 322 * @param values the String values of the new attribute to be put 323 * @return the old attribute with the same identifier, if exists; otherwise 324 * <code>null</code> 325 * @throws LdapException if there are failures 326 */ 327 EntryAttribute put( AttributeType attributeType, String... values ) throws LdapException; 328 329 330 /** 331 * <p> 332 * Places a new attribute with the supplied AttributeType and some values 333 * into the attribute collection. 334 * </p> 335 * <p> 336 * If there is already an attribute with the same AttributeType, the old 337 * one is removed from the collection and is returned by this method. 338 * </p> 339 * <p> 340 * This method provides a mechanism to put an attribute with a 341 * <code>null</code> value: the value may be <code>null</code>. 342 * 343 * @param attributeType the type of the new attribute to be put 344 * @param values the values of the new attribute to be put 345 * @return the old attribute with the same identifier, if exists; otherwise 346 * <code>null</code> 347 * @throws LdapException if there are failures 348 */ 349 EntryAttribute put( AttributeType attributeType, Value<?>... values ) throws LdapException; 350 351 352 /** 353 * <p> 354 * Places a new attribute with the supplied AttributeType and some binary values 355 * into the attribute collection. 356 * </p> 357 * <p> 358 * The given User provided ID will be used for this new AttributeEntry. 359 * </p> 360 * <p> 361 * If there is already an attribute with the same AttributeType, the old 362 * one is removed from the collection and is returned by this method. 363 * </p> 364 * <p> 365 * This method provides a mechanism to put an attribute with a 366 * <code>null</code> value: the value may be <code>null</code>. 367 * 368 * @param upId The User Provided ID to be stored into the AttributeEntry 369 * @param values the binary values of the new attribute to be put 370 * @return the old attribute with the same identifier, if exists; otherwise 371 * <code>null</code> 372 * @throws LdapException if there are failures. 373 */ 374 EntryAttribute put( String upId, AttributeType attributeType, byte[]... values ) throws LdapException; 375 376 377 /** 378 * <p> 379 * Places a new attribute with the supplied AttributeType and some String values 380 * into the attribute collection. 381 * </p> 382 * <p> 383 * The given User provided ID will be used for this new AttributeEntry. 384 * </p> 385 * <p> 386 * If there is already an attribute with the same AttributeType, the old 387 * one is removed from the collection and is returned by this method. 388 * </p> 389 * <p> 390 * This method provides a mechanism to put an attribute with a 391 * <code>null</code> value: the value may be <code>null</code>. 392 * 393 * @param upId The User Provided ID to be stored into the AttributeEntry 394 * @param attributeType the type of the new attribute to be put 395 * @param values the String values of the new attribute to be put 396 * @return the old attribute with the same identifier, if exists; otherwise 397 * <code>null</code> 398 * @throws LdapException if there are failures. 399 */ 400 EntryAttribute put( String upId, AttributeType attributeType, String... values ) throws LdapException; 401 402 403 /** 404 * <p> 405 * Places a new attribute with the supplied AttributeType and some values 406 * into the attribute collection. 407 * </p> 408 * <p> 409 * The given User provided ID will be used for this new AttributeEntry. 410 * </p> 411 * <p> 412 * If there is already an attribute with the same AttributeType, the old 413 * one is removed from the collection and is returned by this method. 414 * </p> 415 * <p> 416 * This method provides a mechanism to put an attribute with a 417 * <code>null</code> value: the value may be <code>null</code>. 418 * 419 * @param upId The User Provided ID to be stored into the AttributeEntry 420 * @param attributeType the type of the new attribute to be put 421 * @param values the values of the new attribute to be put 422 * @return the old attribute with the same identifier, if exists; otherwise 423 * <code>null</code> 424 * @throws LdapException if there are failures. 425 */ 426 EntryAttribute put( String upId, AttributeType attributeType, Value<?>... values ) throws LdapException; 427 428 429 /** 430 * <p> 431 * Removes the specified binary values from an attribute. 432 * </p> 433 * <p> 434 * If at least one value is removed, this method returns <code>true</code>. 435 * </p> 436 * <p> 437 * If there is no more value after having removed the values, the attribute 438 * will be removed too. 439 * </p> 440 * <p> 441 * If the attribute does not exist, nothing is done and the method returns 442 * <code>false</code> 443 * </p> 444 * 445 * @param attributeType The attribute type 446 * @param values the values to be removed 447 * @return <code>true</code> if at least a value is removed, <code>false</code> 448 * if not all the values have been removed or if the attribute does not exist. 449 */ 450 boolean remove( AttributeType attributeType, byte[]... values ) throws LdapException; 451 452 453 /** 454 * <p> 455 * Removes the specified String values from an attribute. 456 * </p> 457 * <p> 458 * If at least one value is removed, this method returns <code>true</code>. 459 * </p> 460 * <p> 461 * If there is no more value after having removed the values, the attribute 462 * will be removed too. 463 * </p> 464 * <p> 465 * If the attribute does not exist, nothing is done and the method returns 466 * <code>false</code> 467 * </p> 468 * 469 * @param attributeType The attribute type 470 * @param values the values to be removed 471 * @return <code>true</code> if at least a value is removed, <code>false</code> 472 * if not all the values have been removed or if the attribute does not exist. 473 */ 474 boolean remove( AttributeType attributeType, String... values ) throws LdapException; 475 476 477 /** 478 * <p> 479 * Removes the specified values from an attribute. 480 * </p> 481 * <p> 482 * If at least one value is removed, this method returns <code>true</code>. 483 * </p> 484 * <p> 485 * If there is no more value after having removed the values, the attribute 486 * will be removed too. 487 * </p> 488 * <p> 489 * If the attribute does not exist, nothing is done and the method returns 490 * <code>false</code> 491 * </p> 492 * 493 * @param attributeType The attribute type 494 * @param values the values to be removed 495 * @return <code>true</code> if at least a value is removed, <code>false</code> 496 * if not all the values have been removed or if the attribute does not exist. 497 */ 498 boolean remove( AttributeType attributeType, Value<?>... values ) throws LdapException; 499 500 501 /** 502 * Removes the specified attributes. The removed attributes are 503 * returned by this method. If there were no attribute the return value 504 * is <code>null</code>. 505 * 506 * @param attributes the attributes to be removed 507 * @return the removed attribute, if exists; otherwise <code>null</code> 508 */ 509 List<EntryAttribute> remove( EntryAttribute... attributes ) throws LdapException; 510 511 512 /** 513 * <p> 514 * Removes the attribute with the specified AttributeTypes. 515 * </p> 516 * <p> 517 * The removed attribute are returned by this method. 518 * </p> 519 * <p> 520 * If there is no attribute with the specified AttributeTypes, 521 * the return value is <code>null</code>. 522 * </p> 523 * 524 * @param attributes the AttributeTypes to be removed 525 * @return the removed attributes, if any, as a list; otherwise <code>null</code> 526 */ 527 List<EntryAttribute> removeAttributes( AttributeType... attributes ); 528 529 530 /** 531 * <p> 532 * Put some new attributes using the attributeTypes. 533 * No value is inserted. 534 * </p> 535 * <p> 536 * If an existing Attribute is found, it will be replaced by an 537 * empty attribute, and returned to the caller. 538 * </p> 539 * 540 * @param attributeTypes The AttributeTypes to add. 541 * @return A list of replaced Attributes, of <code>null</code> if no attribute are removed. 542 */ 543 List<EntryAttribute> set( AttributeType... attributeTypes ); 544 545 546 /** 547 * A clone method to produce a clone of the current object 548 */ 549 Entry clone(); 550 551 552 /** 553 * Convert the ServerEntry to a ClientEntry 554 * 555 * @return An instance of ClientEntry 556 */ 557 Entry toClientEntry() throws LdapException; 558 }