1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 package org.apache.directory.server.core.entry; 20 21 22 import java.util.List; 23 import java.util.Set; 24 25 import javax.naming.NamingException; 26 27 import org.apache.directory.shared.ldap.entry.Entry; 28 import org.apache.directory.shared.ldap.entry.EntryAttribute; 29 import org.apache.directory.shared.ldap.entry.Value; 30 import org.apache.directory.shared.ldap.schema.AttributeType; 31 32 33 /** 34 * A server side entry which is schema aware. 35 * 36 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 37 * @version $Rev$, $Date$ 38 */ 39 public interface ServerEntry extends Entry, Cloneable 40 { 41 /** 42 * <p> 43 * Add an attribute (represented by its AttributeType and some binary values) into an 44 * entry. 45 * </p> 46 * <p> 47 * If we already have an attribute with the same values, the duplicated values 48 * are not added (duplicated values are not allowed) 49 * </p> 50 * <p> 51 * If the value cannot be added, or if the AttributeType is null or invalid, 52 * a NamingException is thrown. 53 * </p> 54 * 55 * @param attributeType The attribute Type. 56 * @param values The list of binary values to inject. It can be empty. 57 * @throws NamingException If the attribute does not exist 58 */ 59 void add( AttributeType attributeType, byte[]... values ) throws NamingException; 60 61 62 /** 63 * <p> 64 * Add an attribute (represented by its AttributeType and some String values) into an 65 * entry. 66 * </p> 67 * <p> 68 * If we already have an attribute with the same values, the duplicated values 69 * are not added (duplicated values are not allowed) 70 * </p> 71 * <p> 72 * If the value cannot be added, or if the AttributeType is null or invalid, 73 * a NamingException is thrown. 74 * </p> 75 * 76 * @param attributeType The attribute Type 77 * @param values The list of binary values to inject. It can be empty 78 * @throws NamingException If the attribute does not exist 79 */ 80 void add( AttributeType attributeType, String... values ) throws NamingException; 81 82 83 /** 84 * <p> 85 * Add an attribute (represented by its AttributeType and some values) into an 86 * entry. 87 * </p> 88 * <p> 89 * If we already have an attribute with the same values, the duplicated values 90 * are not added (duplicated values are not allowed) 91 * </p> 92 * <p> 93 * If the value cannot be added, or if the AttributeType is null or invalid, 94 * a NamingException is thrown. 95 * </p> 96 * 97 * @param attributeType The attribute Type 98 * @param values The list of binary values to inject. It can be empty 99 * @throws NamingException If the attribute does not exist 100 */ 101 void add( AttributeType attributeType, Value<?>... values ) throws NamingException; 102 103 104 /** 105 * <p> 106 * Add an attribute (represented by its AttributeType and some binary values) into an 107 * entry. Set the User Provider ID at the same time 108 * </p> 109 * <p> 110 * If we already have an attribute with the same values, the duplicated values 111 * are not added (duplicated values are not allowed) 112 * </p> 113 * <p> 114 * If the value cannot be added, or if the AttributeType is null or invalid, 115 * a NamingException is thrown. 116 * </p> 117 * 118 * @param upId The user provided ID for the added AttributeType 119 * @param attributeType The attribute Type. 120 * @param values The list of binary values to add. It can be empty. 121 * @throws NamingException If the attribute does not exist 122 */ 123 void add( String upId, AttributeType attributeType, byte[]... values ) throws NamingException; 124 125 126 /** 127 * <p> 128 * Add an attribute (represented by its AttributeType and some String values) into an 129 * entry. Set the User Provider ID at the same time 130 * </p> 131 * <p> 132 * If we already have an attribute with the same values, the duplicated values 133 * are not added (duplicated values are not allowed) 134 * </p> 135 * <p> 136 * If the value cannot be added, or if the AttributeType is null or invalid, 137 * a NamingException is thrown. 138 * </p> 139 * 140 * @param upId The user provided ID for the added AttributeType 141 * @param attributeType The attribute Type. 142 * @param values The list of binary values to add. It can be empty. 143 * @throws NamingException If the attribute does not exist 144 */ 145 void add( String upId, AttributeType attributeType, String... values ) throws NamingException; 146 147 148 /** 149 * <p> 150 * Add an attribute (represented by its AttributeType and some values) into an 151 * entry. Set the User Provider ID at the same time 152 * </p> 153 * <p> 154 * If we already have an attribute with the same values, nothing is done 155 * (duplicated values are not allowed) 156 * </p> 157 * <p> 158 * If the value cannot be added, or if the AttributeType is null or invalid, 159 * a NamingException is thrown. 160 * </p> 161 * 162 * @param upId The user provided ID for the added AttributeType 163 * @param attributeType The attribute Type. 164 * @param values The list of values to add. It can be empty. 165 * @throws NamingException If the attribute does not exist 166 */ 167 void add( String upId, AttributeType attributeType, Value<?>... values ) throws NamingException; 168 169 170 // ----------------------------------------------------------------------- 171 // Container (get/put/remove) Methods 172 // ----------------------------------------------------------------------- 173 /** 174 * Checks if an entry contains an attribute with some given binary values. 175 * 176 * @param attributeType The Attribute we are looking for. 177 * @param values The searched values. 178 * @return <code>true</code> if all the values are found within the attribute, 179 * <code>false</code> otherwise, or if the attributes does not exist. 180 * @throws NamingException If the attribute does not exists 181 */ 182 boolean contains( AttributeType attributeType, byte[]... values ); 183 184 185 /** 186 * Checks if an entry contains an attribute with some given String values. 187 * 188 * @param attributeType The Attribute we are looking for. 189 * @param values The searched values. 190 * @return <code>true</code> if all the values are found within the attribute, 191 * <code>false</code> otherwise, or if the attributes does not exist. 192 * @throws NamingException If the attribute does not exists 193 */ 194 boolean contains( AttributeType attributeType, String... values ); 195 196 197 /** 198 * Checks if an entry contains an attribute with some given binary values. 199 * 200 * @param attributeType The Attribute we are looking for. 201 * @param values The searched values. 202 * @return <code>true</code> if all the values are found within the attribute, 203 * <code>false</code> otherwise, or if the attributes does not exist. 204 * @throws NamingException If the attribute does not exists 205 */ 206 boolean contains( AttributeType attributeType, Value<?>... values ); 207 208 209 /** 210 * Checks if an entry contains a specific AttributeType. 211 * 212 * @param attributeType The AttributeType to look for. 213 * @return <code>true</code> if the attribute is found within the entry. 214 */ 215 boolean containsAttribute( AttributeType attributeType ); 216 217 218 /** 219 * <p> 220 * Returns the attribute with the specified AttributeType. The return value 221 * is <code>null</code> if no match is found. 222 * </p> 223 * 224 * @param attributeType The attributeType we are looking for. 225 * @return the attribute associated with the AttributeType. 226 */ 227 /** 228 * Returns the attribute associated with an AttributeType 229 * 230 * @param the AttributeType we are looking for 231 * @return the associated attribute 232 */ 233 EntryAttribute get( AttributeType attributeType ); 234 235 236 /** 237 * Gets all the attributes type 238 * 239 * @return The combined set of all the attributes. 240 */ 241 Set<AttributeType> getAttributeTypes(); 242 243 244 /** 245 * Tells if an entry has a specific ObjectClass Attribute 246 * 247 * @param objectClass The ObjectClass we want to check 248 * @return <code>true</code> if the ObjectClass value is present 249 * in the ObjectClass attribute 250 */ 251 boolean hasObjectClass( EntryAttribute objectClass ); 252 253 254 /** 255 * Fail fast check performed to determine entry consistency according to schema 256 * characteristics. 257 * 258 * @return true if the entry, it's attributes and their values are consistent 259 * with the schema 260 */ 261 boolean isValid(); 262 263 264 /** 265 * Check performed to determine entry consistency according to the schema 266 * requirements of a particular objectClass. The entry must be of that objectClass 267 * to return true: meaning if the entry's objectClass attribute does not contain 268 * the objectClass argument, then false should be returned. 269 * 270 * @param objectClass the objectClass to use while checking for validity 271 * @return true if the entry, it's attributes and their values are consistent 272 * with the objectClass 273 */ 274 boolean isValid( String objectClass ); 275 276 277 /** 278 * Check performed to determine entry consistency according to the schema 279 * requirements of a particular objectClass. The entry must be of that objectClass 280 * to return true: meaning if the entry's objectClass attribute does not contain 281 * the objectClass argument, then false should be returned. 282 * 283 * @param objectClass the objectClass to use while checking for validity 284 * @return true if the entry, it's attributes and their values are consistent 285 * with the objectClass 286 */ 287 boolean isValid( EntryAttribute objectClass ); 288 289 290 /** 291 * <p> 292 * Places a new attribute with the supplied AttributeType and binary values 293 * into the attribute collection. 294 * </p> 295 * <p> 296 * If there is already an attribute with the same AttributeType, the old 297 * one is removed from the collection and is returned by this method. 298 * </p> 299 * <p> 300 * This method provides a mechanism to put an attribute with a 301 * <code>null</code> value: the value may be <code>null</code>. 302 * 303 * @param attributeType the type of the new attribute to be put 304 * @param values the binary values of the new attribute to be put 305 * @return the old attribute with the same identifier, if exists; otherwise 306 * <code>null</code> 307 * @throws NamingException if there are failures 308 */ 309 EntryAttribute put( AttributeType attributeType, byte[]... values ) throws NamingException; 310 311 312 /** 313 * <p> 314 * Places a new attribute with the supplied AttributeType and String values 315 * into the attribute collection. 316 * </p> 317 * <p> 318 * If there is already an attribute with the same AttributeType, the old 319 * one is removed from the collection and is returned by this method. 320 * </p> 321 * <p> 322 * This method provides a mechanism to put an attribute with a 323 * <code>null</code> value: the value may be <code>null</code>. 324 * 325 * @param attributeType the type of the new attribute to be put 326 * @param values the String values of the new attribute to be put 327 * @return the old attribute with the same identifier, if exists; otherwise 328 * <code>null</code> 329 * @throws NamingException if there are failures 330 */ 331 EntryAttribute put( AttributeType attributeType, String... values ) throws NamingException; 332 333 334 /** 335 * <p> 336 * Places a new attribute with the supplied AttributeType and some values 337 * into the attribute collection. 338 * </p> 339 * <p> 340 * If there is already an attribute with the same AttributeType, the old 341 * one is removed from the collection and is returned by this method. 342 * </p> 343 * <p> 344 * This method provides a mechanism to put an attribute with a 345 * <code>null</code> value: the value may be <code>null</code>. 346 * 347 * @param attributeType the type of the new attribute to be put 348 * @param values the values of the new attribute to be put 349 * @return the old attribute with the same identifier, if exists; otherwise 350 * <code>null</code> 351 * @throws NamingException if there are failures 352 */ 353 EntryAttribute put( AttributeType attributeType, Value<?>... values ) throws NamingException; 354 355 356 /** 357 * <p> 358 * Places a new attribute with the supplied AttributeType and some binary values 359 * into the attribute collection. 360 * </p> 361 * <p> 362 * The given User provided ID will be used for this new AttributeEntry. 363 * </p> 364 * <p> 365 * If there is already an attribute with the same AttributeType, the old 366 * one is removed from the collection and is returned by this method. 367 * </p> 368 * <p> 369 * This method provides a mechanism to put an attribute with a 370 * <code>null</code> value: the value may be <code>null</code>. 371 * 372 * @param upId The User Provided ID to be stored into the AttributeEntry 373 * @param values the binary values of the new attribute to be put 374 * @return the old attribute with the same identifier, if exists; otherwise 375 * <code>null</code> 376 * @throws NamingException if there are failures. 377 */ 378 EntryAttribute put( String upId, AttributeType attributeType, byte[]... values ) throws NamingException; 379 380 381 /** 382 * <p> 383 * Places a new attribute with the supplied AttributeType and some String values 384 * into the attribute collection. 385 * </p> 386 * <p> 387 * The given User provided ID will be used for this new AttributeEntry. 388 * </p> 389 * <p> 390 * If there is already an attribute with the same AttributeType, the old 391 * one is removed from the collection and is returned by this method. 392 * </p> 393 * <p> 394 * This method provides a mechanism to put an attribute with a 395 * <code>null</code> value: the value may be <code>null</code>. 396 * 397 * @param upId The User Provided ID to be stored into the AttributeEntry 398 * @param attributeType the type of the new attribute to be put 399 * @param values the String values of the new attribute to be put 400 * @return the old attribute with the same identifier, if exists; otherwise 401 * <code>null</code> 402 * @throws NamingException if there are failures. 403 */ 404 EntryAttribute put( String upId, AttributeType attributeType, String... values ) throws NamingException; 405 406 407 /** 408 * <p> 409 * Places a new attribute with the supplied AttributeType and some values 410 * into the attribute collection. 411 * </p> 412 * <p> 413 * The given User provided ID will be used for this new AttributeEntry. 414 * </p> 415 * <p> 416 * If there is already an attribute with the same AttributeType, the old 417 * one is removed from the collection and is returned by this method. 418 * </p> 419 * <p> 420 * This method provides a mechanism to put an attribute with a 421 * <code>null</code> value: the value may be <code>null</code>. 422 * 423 * @param upId The User Provided ID to be stored into the AttributeEntry 424 * @param attributeType the type of the new attribute to be put 425 * @param values the values of the new attribute to be put 426 * @return the old attribute with the same identifier, if exists; otherwise 427 * <code>null</code> 428 * @throws NamingException if there are failures. 429 */ 430 EntryAttribute put( String upId, AttributeType attributeType, Value<?>... values ) throws NamingException; 431 432 433 /** 434 * <p> 435 * Removes the specified binary values from an attribute. 436 * </p> 437 * <p> 438 * If at least one value is removed, this method returns <code>true</code>. 439 * </p> 440 * <p> 441 * If there is no more value after having removed the values, the attribute 442 * will be removed too. 443 * </p> 444 * <p> 445 * If the attribute does not exist, nothing is done and the method returns 446 * <code>false</code> 447 * </p> 448 * 449 * @param attributeType The attribute type 450 * @param values the values to be removed 451 * @return <code>true</code> if at least a value is removed, <code>false</code> 452 * if not all the values have been removed or if the attribute does not exist. 453 */ 454 boolean remove( AttributeType attributeType, byte[]... values ) throws NamingException; 455 456 457 /** 458 * <p> 459 * Removes the specified String values from an attribute. 460 * </p> 461 * <p> 462 * If at least one value is removed, this method returns <code>true</code>. 463 * </p> 464 * <p> 465 * If there is no more value after having removed the values, the attribute 466 * will be removed too. 467 * </p> 468 * <p> 469 * If the attribute does not exist, nothing is done and the method returns 470 * <code>false</code> 471 * </p> 472 * 473 * @param attributeType The attribute type 474 * @param values the values to be removed 475 * @return <code>true</code> if at least a value is removed, <code>false</code> 476 * if not all the values have been removed or if the attribute does not exist. 477 */ 478 boolean remove( AttributeType attributeType, String... values ) throws NamingException; 479 480 481 /** 482 * <p> 483 * Removes the specified values from an attribute. 484 * </p> 485 * <p> 486 * If at least one value is removed, this method returns <code>true</code>. 487 * </p> 488 * <p> 489 * If there is no more value after having removed the values, the attribute 490 * will be removed too. 491 * </p> 492 * <p> 493 * If the attribute does not exist, nothing is done and the method returns 494 * <code>false</code> 495 * </p> 496 * 497 * @param attributeType The attribute type 498 * @param values the values to be removed 499 * @return <code>true</code> if at least a value is removed, <code>false</code> 500 * if not all the values have been removed or if the attribute does not exist. 501 */ 502 boolean remove( AttributeType attributeType, Value<?>... values ) throws NamingException; 503 504 505 /** 506 * Removes the specified attributes. The removed attributes are 507 * returned by this method. If there were no attribute the return value 508 * is <code>null</code>. 509 * 510 * @param attributes the attributes to be removed 511 * @return the removed attribute, if exists; otherwise <code>null</code> 512 */ 513 List<EntryAttribute> remove( EntryAttribute... attributes ) throws NamingException; 514 515 516 /** 517 * <p> 518 * Removes the attribute with the specified AttributeTypes. 519 * </p> 520 * <p> 521 * The removed attribute are returned by this method. 522 * </p> 523 * <p> 524 * If there is no attribute with the specified AttributeTypes, 525 * the return value is <code>null</code>. 526 * </p> 527 * 528 * @param attributes the AttributeTypes to be removed 529 * @return the removed attributes, if any, as a list; otherwise <code>null</code> 530 */ 531 List<EntryAttribute> removeAttributes( AttributeType... attributes ); 532 533 534 /** 535 * <p> 536 * Put some new attributes using the attributeTypes. 537 * No value is inserted. 538 * </p> 539 * <p> 540 * If an existing Attribute is found, it will be replaced by an 541 * empty attribute, and returned to the caller. 542 * </p> 543 * 544 * @param attributeTypes The AttributeTypes to add. 545 * @return A list of replaced Attributes, of <code>null</code> if no attribute are removed. 546 */ 547 List<EntryAttribute> set( AttributeType... attributeTypes ); 548 549 550 /** 551 * A clone method to produce a clone of the current object 552 */ 553 Entry clone(); 554 555 556 /** 557 * Convert the ServerEntry to a ClientEntry 558 * 559 * @return An instance of ClientEntry 560 */ 561 Entry toClientEntry() throws NamingException; 562 }