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 */ 20 package org.apache.directory.ldap.client.api; 21 22 23 import java.io.Closeable; 24 import java.io.IOException; 25 import java.util.List; 26 27 import org.apache.directory.api.asn1.util.Oid; 28 import org.apache.directory.api.ldap.codec.api.BinaryAttributeDetector; 29 import org.apache.directory.api.ldap.codec.api.LdapApiService; 30 import org.apache.directory.api.ldap.model.cursor.EntryCursor; 31 import org.apache.directory.api.ldap.model.cursor.SearchCursor; 32 import org.apache.directory.api.ldap.model.entry.Entry; 33 import org.apache.directory.api.ldap.model.entry.Modification; 34 import org.apache.directory.api.ldap.model.entry.ModificationOperation; 35 import org.apache.directory.api.ldap.model.entry.Value; 36 import org.apache.directory.api.ldap.model.exception.LdapException; 37 import org.apache.directory.api.ldap.model.message.AbandonRequest; 38 import org.apache.directory.api.ldap.model.message.AddRequest; 39 import org.apache.directory.api.ldap.model.message.AddResponse; 40 import org.apache.directory.api.ldap.model.message.BindRequest; 41 import org.apache.directory.api.ldap.model.message.BindResponse; 42 import org.apache.directory.api.ldap.model.message.CompareRequest; 43 import org.apache.directory.api.ldap.model.message.CompareResponse; 44 import org.apache.directory.api.ldap.model.message.Control; 45 import org.apache.directory.api.ldap.model.message.DeleteRequest; 46 import org.apache.directory.api.ldap.model.message.DeleteResponse; 47 import org.apache.directory.api.ldap.model.message.ExtendedRequest; 48 import org.apache.directory.api.ldap.model.message.ExtendedResponse; 49 import org.apache.directory.api.ldap.model.message.ModifyDnRequest; 50 import org.apache.directory.api.ldap.model.message.ModifyDnResponse; 51 import org.apache.directory.api.ldap.model.message.ModifyRequest; 52 import org.apache.directory.api.ldap.model.message.ModifyResponse; 53 import org.apache.directory.api.ldap.model.message.SearchRequest; 54 import org.apache.directory.api.ldap.model.message.SearchScope; 55 import org.apache.directory.api.ldap.model.name.Dn; 56 import org.apache.directory.api.ldap.model.name.Rdn; 57 import org.apache.directory.api.ldap.model.schema.SchemaManager; 58 59 60 // TODO: all the SASL bind methods are not declared in this interface, but implemented in LdapNetworkConnection. Is that intended? 61 // TODO: why does connect() return a boolean? What is the difference between false and an Exception? 62 // TODO: describe better which type of LdapException are thrown in which case? 63 // TODO: does method getCodecService() belong into the interface? It returns a LdapApiService, should it be renamed? 64 // TODO: does method doesFutureExistFor() belong into the interface? Move to LdapAsyncConnection? 65 66 /** 67 * The root interface for all the LDAP connection implementations. All operations defined in this interface are blocking (synchronous). 68 * 69 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 70 */ 71 public interface LdapConnection extends Closeable 72 { 73 /** 74 * Check if the connection is established 75 * 76 * @return <code>true</code> if the connection is established 77 */ 78 boolean isConnected(); 79 80 81 /** 82 * Check if the connection is authenticated. 83 * 84 * @return <code>true</code> if the connection is authenticated 85 */ 86 boolean isAuthenticated(); 87 88 89 /** 90 * Connect to the remote LDAP server. 91 * 92 * @return <code>true</code> if the connection is established, false otherwise 93 * @throws LdapException if some error occurred 94 */ 95 boolean connect() throws LdapException; 96 97 98 /** 99 * Disconnect from the remote LDAP server. 100 * 101 * @throws IOException if some I/O error occurs 102 */ 103 @Override 104 void close() throws IOException; 105 106 107 //------------------------ The LDAP operations ------------------------// 108 // Add operations // 109 //---------------------------------------------------------------------// 110 /** 111 * Add an entry to the server. 112 * 113 * @param entry The entry to add 114 * @throws LdapException if some error occurred 115 */ 116 void add( Entry entry ) throws LdapException; 117 118 119 /** 120 * Add an entry present in the {@link AddRequest} to the server. 121 * 122 * @param addRequest the request object containing an entry and controls (if any) 123 * @return the add operation's response 124 * @throws LdapException if some error occurred 125 */ 126 AddResponse add( AddRequest addRequest ) throws LdapException; 127 128 129 /** 130 * Abandons a request submitted to the server for performing a particular operation. 131 * 132 * The abandonRequest is always non-blocking, because no response is expected 133 * 134 * @param messageId the ID of the request message sent to the server 135 */ 136 void abandon( int messageId ); 137 138 139 /** 140 * An abandon request essentially with the request message ID of the operation to be canceled 141 * and/or potentially some controls and timeout (the controls and timeout are not mandatory). 142 * 143 * The abandonRequest is always non-blocking, because no response is expected. 144 * 145 * @param abandonRequest the abandon operation's request 146 */ 147 void abandon( AbandonRequest abandonRequest ); 148 149 150 /** 151 * Bind on a server, using the {@link LdapConnectionConfig} information of this connection. 152 * 153 * @throws LdapException if some error occurred 154 */ 155 void bind() throws LdapException; 156 157 158 /** 159 * Anonymous bind on a server. 160 * 161 * @throws LdapException if some error occurred 162 */ 163 void anonymousBind() throws LdapException; 164 165 166 /** 167 * Unauthenticated authentication bind on a server. 168 * 169 * @param name The name used to authenticate the user. It must be a 170 * valid distinguished name. 171 * @throws LdapException if some error occurred 172 */ 173 void bind( String name ) throws LdapException; 174 175 176 /** 177 * Simple bind on a server. 178 * 179 * @param name The name used to authenticate the user. It must be a 180 * valid distinguished name. 181 * @param credentials The password, it can't be <code>null</code> 182 * @throws LdapException if some error occurred 183 */ 184 void bind( String name, String credentials ) throws LdapException; 185 186 187 /** 188 * SASL PLAIN Bind on a server. 189 * 190 * @param authcid The Authentication identity 191 * @param credentials The password, it can't be null 192 * @return The BindResponse LdapResponse 193 * @throws LdapException if some error occurred 194 */ 195 // Not yet available on the CoreConnection 196 //BindResponse bindSaslPlain( String authcid, String credentials ) throws LdapException; 197 198 /** 199 * SASL PLAIN Bind on a server. 200 * 201 * @param authzid The Authorization identity 202 * @param authcid The Authentication identity 203 * @param credentials The password. It can't be null 204 * @return The BindResponse LdapResponse 205 * @throws LdapException if some error occurred 206 */ 207 // Not yet available on the CoreConnection 208 //BindResponse bindSaslPlain( String authzid, String authcid, String credentials ) throws LdapException; 209 210 /** 211 * Unauthenticated authentication bind on a server. 212 * 213 * @param name The name used to authenticate the user. 214 * @throws LdapException if some error occurred 215 */ 216 void bind( Dn name ) throws LdapException; 217 218 219 /** 220 * Simple bind on a server. 221 * 222 * @param name The name used to authenticate the user. 223 * @param credentials The password, it can't be null 224 * @throws LdapException if some error occurred 225 */ 226 void bind( Dn name, String credentials ) throws LdapException; 227 228 229 /** 230 * Bind to the server using a bind request object. 231 * 232 * @param bindRequest The bind request object containing all the needed parameters 233 * @return A {@link BindResponse} containing the result 234 * @throws LdapException if some error occurred 235 */ 236 BindResponse bind( BindRequest bindRequest ) throws LdapException; 237 238 239 /** 240 * Do a search, on the base object, using the given filter and scope. The 241 * SearchRequest parameters default to 242 * <ul> 243 * <li> DerefAlias : ALWAYS 244 * <li> SizeLimit : none 245 * <li> TimeLimit : none 246 * <li> TypesOnly : false 247 * </ul> 248 * 249 * @param baseDn The base for the search. It must be a valid distinguished name and can't be emtpy 250 * @param filter The filter to use for this search. It can't be empty 251 * @param scope The search scope : OBJECT, ONELEVEL or SUBTREE 252 * @param attributes The attributes to use for this search 253 * @return An {@link EntryCursor} on the result. 254 * @throws LdapException if some error occurred 255 */ 256 EntryCursor search( Dn baseDn, String filter, SearchScope scope, String... attributes ) 257 throws LdapException; 258 259 260 /** 261 * Do a search, on the base object, using the given filter and scope. The 262 * SearchRequest parameters default to 263 * <ul> 264 * <li> DerefAlias : ALWAYS 265 * <li> SizeLimit : none 266 * <li> TimeLimit : none 267 * <li> TypesOnly : false 268 * </ul> 269 * 270 * @param baseDn The base for the search. It must be a valid distinguished name, and can't be emtpy 271 * @param filter The filter to use for this search. It can't be empty 272 * @param scope The search scope : OBJECT, ONELEVEL or SUBTREE 273 * @param attributes The attributes to use for this search 274 * @return An {@link EntryCursor} on the result. 275 * @throws LdapException if some error occurred 276 */ 277 EntryCursor search( String baseDn, String filter, SearchScope scope, String... attributes ) 278 throws LdapException; 279 280 281 /** 282 * Performs search using a search request object. 283 * 284 * @param searchRequest The search request object containing all the needed information 285 * @return a search cursor on the result. 286 * @throws LdapException if some error occurred 287 */ 288 SearchCursor search( SearchRequest searchRequest ) throws LdapException; 289 290 291 //------------------------ The LDAP operations ------------------------// 292 // Unbind operations // 293 //---------------------------------------------------------------------// 294 /** 295 * UnBind from a server. This is a request which expects no response. 296 * 297 * @throws LdapException if some error occurred 298 */ 299 void unBind() throws LdapException; 300 301 302 /** 303 * Set the timeout for the responses. We won't wait longer than this 304 * value. 305 * 306 * @param timeOut The timeout, in milliseconds 307 */ 308 void setTimeOut( long timeOut ); 309 310 311 /** 312 * Applies all the modifications to the entry specified by its distinguished name. 313 * 314 * @param dn The entry's distinguished name 315 * @param modifications The list of modifications to be applied 316 * @throws LdapException in case of modify operation failure or timeout happens 317 */ 318 void modify( Dn dn, Modification... modifications ) throws LdapException; 319 320 321 /** 322 * Applies all the modifications to the entry specified by its distinguished name. 323 * 324 * @param dn The entry's distinguished name, it must be a valid distinguished name. 325 * @param modifications The list of modifications to be applied 326 * @throws LdapException in case of modify operation failure or timeout happens 327 */ 328 void modify( String dn, Modification... modifications ) throws LdapException; 329 330 331 /** 332 * Modifies all the attributes present in the entry by applying the same operation. 333 * 334 * @param entry the entry with the attributes to be modified 335 * @param modOp the operation to be applied on all the attributes of the above entry 336 * @throws LdapException in case of modify operation failure or timeout happens 337 */ 338 void modify( Entry entry, ModificationOperation modOp ) throws LdapException; 339 340 341 /** 342 * Performs an modify operation based on the modifications present in 343 * the modify request. 344 * 345 * @param modRequest the modify request object 346 * @return the modify operation's response 347 * @throws LdapException in case of modify operation failure or timeout happens 348 */ 349 ModifyResponse modify( ModifyRequest modRequest ) throws LdapException; 350 351 352 /** 353 * Renames the given entryDn with new relative distinguished name and deletes the 354 * old relative distinguished name. 355 * 356 * @param entryDn the target distinguished name. 357 * @param newRdn new relative distinguished name for the target distinguished name. 358 * @throws LdapException if some error occurred 359 * @see #rename(String, String, boolean) 360 */ 361 void rename( String entryDn, String newRdn ) throws LdapException; 362 363 364 /** 365 * Renames the given entryDn with new relative distinguished name and deletes the 366 * old relative distinguished name. 367 * 368 * @param entryDn the target distinguished name. 369 * @param newRdn new relative distinguished name for the target distinguished name. 370 * @throws LdapException if some error occurred 371 * @see #rename(Dn, Rdn, boolean) 372 */ 373 void rename( Dn entryDn, Rdn newRdn ) throws LdapException; 374 375 376 /** 377 * Renames the given entryDn with new relative distinguished name and deletes the 378 * old relative distinguished name if deleteOldRdn is set to true. 379 * 380 * @param entryDn the target distinguished name. 381 * @param newRdn new relative distinguished name for the target distinguished name. 382 * @param deleteOldRdn flag to indicate whether to delete the old relative distinguished name 383 * @throws LdapException if some error occurred 384 * @see #rename(Dn, Rdn, boolean) 385 */ 386 void rename( String entryDn, String newRdn, boolean deleteOldRdn ) throws LdapException; 387 388 389 /** 390 * Renames the given entryDn with new relative distinguished name and deletes the 391 * old relative distinguished name if deleteOldRdn is set to true. 392 * 393 * @param entryDn the target distinguished name. 394 * @param newRdn new relative distinguished name for the target distinguished name. 395 * @param deleteOldRdn flag to indicate whether to delete the old relative distinguished name 396 * @throws LdapException if some error occurred 397 */ 398 void rename( Dn entryDn, Rdn newRdn, boolean deleteOldRdn ) throws LdapException; 399 400 401 /** 402 * Moves the given entry distinguished name under the new superior distinguished name. 403 * 404 * @param entryDn the distinguished name of the target entry 405 * @param newSuperiorDn distinguished name of the new parent/superior 406 * @throws LdapException if some error occurred 407 * @see #move(Dn, Dn) 408 */ 409 void move( String entryDn, String newSuperiorDn ) throws LdapException; 410 411 412 /** 413 * Moves the given entry distinguished name under the new superior distinguished name. 414 * 415 * @param entryDn the distinguished name of the target entry 416 * @param newSuperiorDn distinguished name of the new parent/superior 417 * @throws LdapException if some error occurred 418 */ 419 void move( Dn entryDn, Dn newSuperiorDn ) throws LdapException; 420 421 422 /** 423 * Moves and renames the given entryDn. The old relative distinguished name will be deleted. 424 * 425 * @param entryDn The original entry distinguished name. 426 * @param newDn The new entry distinguished name. 427 * @throws LdapException if some error occurred 428 * @see #moveAndRename(Dn, Dn, boolean) 429 */ 430 void moveAndRename( Dn entryDn, Dn newDn ) throws LdapException; 431 432 433 /** 434 * Moves and renames the given entry distinguished name. The old relative 435 * distinguished name will be deleted 436 * 437 * @param entryDn The original entry distinguished name. 438 * @param newDn The new entry distinguished name. 439 * @throws LdapException if some error occurred 440 * @see #moveAndRename(Dn, Dn, boolean) 441 */ 442 void moveAndRename( String entryDn, String newDn ) throws LdapException; 443 444 445 /** 446 * Moves and renames the given entryDn. The old relative distinguished name will be deleted if requested. 447 * 448 * @param entryDn The original entry distinguished name. 449 * @param newDn The new entry distinguished name. 450 * @param deleteOldRdn Tells if the old relative distinguished name must be removed 451 * @throws LdapException if some error occurred 452 */ 453 void moveAndRename( Dn entryDn, Dn newDn, boolean deleteOldRdn ) throws LdapException; 454 455 456 /** 457 * Moves and renames the given entryDn. The old relative distinguished name will be deleted if requested. 458 * 459 * @param entryDn The original entry distinguished name. 460 * @param newDn The new entry distinguished name. 461 * @param deleteOldRdn Tells if the old relative distinguished name must be removed 462 * @throws LdapException if some error occurred 463 */ 464 void moveAndRename( String entryDn, String newDn, boolean deleteOldRdn ) 465 throws LdapException; 466 467 468 /** 469 * Performs the modifyDn operation based on the given request object. 470 * 471 * @param modDnRequest the request object 472 * @return modifyDn operation's response 473 * @throws LdapException if some error occurred 474 */ 475 ModifyDnResponse modifyDn( ModifyDnRequest modDnRequest ) throws LdapException; 476 477 478 /** 479 * Deletes the entry with the given distinguished name. 480 * 481 * @param dn the target entry's distinguished name, it must be a valid distinguished name. 482 * @throws LdapException If the distinguished name is not valid or if the deletion failed 483 */ 484 void delete( String dn ) throws LdapException; 485 486 487 /** 488 * Deletes the entry with the given distinguished name. 489 * 490 * @param dn the target entry's distinguished name 491 * @throws LdapException If the distinguished name is not valid or if the deletion failed 492 */ 493 void delete( Dn dn ) throws LdapException; 494 495 496 /** 497 * Performs a delete operation based on the delete request object. 498 * 499 * @param deleteRequest the delete operation's request 500 * @return delete operation's response 501 * @throws LdapException If the distinguished name is not valid or if the deletion failed 502 */ 503 DeleteResponse delete( DeleteRequest deleteRequest ) throws LdapException; 504 505 506 /** 507 * Compares whether a given attribute's value matches that of the 508 * existing value of the attribute present in the entry with the given distinguished name. 509 * 510 * @param dn the target entry's distinguished name, it must be a valid distinguished name. 511 * @param attributeName the attribute's name 512 * @param value a String value with which the target entry's attribute value to be compared with 513 * @return <code>true</code> if the value matches, <code>false</code> otherwise 514 * @throws LdapException if some error occurred 515 */ 516 boolean compare( String dn, String attributeName, String value ) throws LdapException; 517 518 519 /** 520 * Compares whether a given attribute's value matches that of the 521 * existing value of the attribute present in the entry with the given distinguished name. 522 * 523 * @param dn the target entry's distinguished name, it must be a valid distinguished name. 524 * @param attributeName the attribute's name 525 * @param value a byte[] value with which the target entry's attribute value to be compared with 526 * @return <code>true</code> if the value matches, <code>false</code> otherwise 527 * @throws LdapException if some error occurred 528 */ 529 boolean compare( String dn, String attributeName, byte[] value ) throws LdapException; 530 531 532 /** 533 * Compares whether a given attribute's value matches that of the 534 * existing value of the attribute present in the entry with the given distinguished name. 535 * 536 * @param dn the target entry's distinguished name, it must be a valid distinguished name. 537 * @param attributeName the attribute's name 538 * @param value a Value<?> value with which the target entry's attribute value to be compared with 539 * @return <code>true</code> if the value matches, <code>false</code> otherwise 540 * @throws LdapException if some error occurred 541 */ 542 boolean compare( String dn, String attributeName, Value<?> value ) throws LdapException; 543 544 545 /** 546 * Compares whether a given attribute's value matches that of the 547 * existing value of the attribute present in the entry with the given distinguished name. 548 * 549 * @param dn the target entry's distinguished name 550 * @param attributeName the attribute's name 551 * @param value a String value with which the target entry's attribute value to be compared with 552 * @return <code>true</code> if the value matches, <code>false</code> otherwise 553 * @throws LdapException if some error occurred 554 */ 555 boolean compare( Dn dn, String attributeName, String value ) throws LdapException; 556 557 558 /** 559 * Compares whether a given attribute's value matches that of the 560 * existing value of the attribute present in the entry with the given distinguished name. 561 * 562 * @param dn the target entry's distinguished name 563 * @param attributeName the attribute's name 564 * @param value a byte[] value with which the target entry's attribute value to be compared with 565 * @return <code>true</code> if the value matches, <code>false</code> otherwise 566 * @throws LdapException if some error occurred 567 */ 568 boolean compare( Dn dn, String attributeName, byte[] value ) throws LdapException; 569 570 571 /** 572 * Compares whether a given attribute's value matches that of the 573 * existing value of the attribute present in the entry with the given distinguished name. 574 * 575 * @param dn the target entry's distinguished name 576 * @param attributeName the attribute's name 577 * @param value a Value<?> value with which the target entry's attribute value to be compared with 578 * @return <code>true</code> if the value matches, <code>false</code> otherwise 579 * @throws LdapException if some error occurred 580 */ 581 boolean compare( Dn dn, String attributeName, Value<?> value ) throws LdapException; 582 583 584 /** 585 * Compares an entry's attribute's value with that of the given value. 586 * 587 * @param compareRequest the compare request which contains the target distinguished name, 588 * attribute name and value 589 * @return compare operation's response 590 * @throws LdapException if some error occurred 591 */ 592 CompareResponse compare( CompareRequest compareRequest ) throws LdapException; 593 594 595 /** 596 * Sends a extended operation request to the server with the given OID and no value. 597 * 598 * @param oid the object identifier of the extended operation 599 * @return extended operation's response 600 * @throws LdapException if some error occurred 601 * @see #extended(org.apache.directory.api.asn1.util.Oid, byte[]) 602 */ 603 ExtendedResponse extended( String oid ) throws LdapException; 604 605 606 /** 607 * Sends a extended operation request to the server with the given OID and value. 608 * 609 * @param oid the object identifier of the extended operation 610 * @param value value to be used by the extended operation, can be a null value 611 * @return extended operation's response 612 * @throws LdapException if some error occurred 613 * @see #extended(org.apache.directory.api.asn1.util.Oid, byte[]) 614 */ 615 ExtendedResponse extended( String oid, byte[] value ) throws LdapException; 616 617 618 /** 619 * Sends a extended operation request to the server with the given OID and no value. 620 * 621 * @param oid the object identifier of the extended operation 622 * @return extended operation's response 623 * @throws LdapException if some error occurred 624 * @see #extended(org.apache.directory.api.asn1.util.Oid, byte[]) 625 */ 626 ExtendedResponse extended( Oid oid ) throws LdapException; 627 628 629 /** 630 * Sends a extended operation request to the server with the given OID and value. 631 * 632 * @param oid the object identifier of the extended operation 633 * @param value value to be used by the extended operation, can be a null value 634 * @return extended operation's response 635 * @throws LdapException if some error occurred 636 */ 637 ExtendedResponse extended( Oid oid, byte[] value ) throws LdapException; 638 639 640 /** 641 * Performs an extended operation based on the extended request object. 642 * 643 * @param extendedRequest the extended operation's request 644 * @return Extended operation's response 645 * @throws LdapException if the extended operation failed 646 */ 647 ExtendedResponse extended( ExtendedRequest extendedRequest ) throws LdapException; 648 649 650 /** 651 * Tells if an entry exists in the server. 652 * 653 * @param dn The distinguished name of the entry to check for existence, must be a valid distinguished name. 654 * @return <code>true</code> if the entry exists, <code>false</code> otherwise. 655 * Note that if the entry exists but if the user does not have the permission to 656 * read it, <code>false</code> will also be returned 657 * @throws LdapException if some error occurred 658 */ 659 boolean exists( String dn ) throws LdapException; 660 661 662 /** 663 * Tells if an Entry exists in the server. 664 * 665 * @param dn The distinguished name of the entry to check for existence 666 * @return <code>true</code> if the entry exists, <code>false</code> otherwise. 667 * Note that if the entry exists but if the user does not have the permission to 668 * read it, <code>false</code> will also be returned 669 * @throws LdapException if some error occurred 670 */ 671 boolean exists( Dn dn ) throws LdapException; 672 673 674 /** 675 * Get back the RooDSE from the connected server. Only the user attributes are returned. 676 * 677 * @return The Entry containing all the information about the rootDSE 678 * @throws LdapException If the rootDSE can't be read 679 */ 680 Entry getRootDse() throws LdapException; 681 682 683 /** 684 * Get back the RooDSE from the connected server. The user can provide the 685 * list of attributes he wants to get back. Sending "*" will return all the 686 * user attributes, sending "+" will return all the operational attributes. 687 * 688 * @param attributes The list of attributes to return 689 * @return The Entry containing all the information about the rootDSE 690 * @throws LdapException If the rootDSE can't be read 691 */ 692 Entry getRootDse( String... attributes ) throws LdapException; 693 694 695 /** 696 * Searches for an entry having the given distinguished name. 697 * 698 * @param dn the distinguished name of the entry to be fetched 699 * @return the Entry with the given distinguished name or null if no entry exists with that distinguished name. 700 * @throws LdapException in case of any problems while searching for the distinguished name or if the returned 701 * response contains a referral 702 * @see #lookup(Dn, String...) 703 */ 704 Entry lookup( Dn dn ) throws LdapException; 705 706 707 /** 708 * Searches for an entry having the given distinguished name. 709 * 710 * @param dn the distinguished name of the entry to be fetched 711 * @return the Entry with the given distinguished name or null if no entry exists with that distinguished name. 712 * @throws LdapException in case of any problems while searching for the distinguished name or if the returned 713 * response contains a referral 714 * @see #lookup(String, String...) 715 */ 716 Entry lookup( String dn ) throws LdapException; 717 718 719 /** 720 * Searches for an entry having the given distinguished name. 721 * 722 * @param dn the distinguished name of the entry to be fetched 723 * @param attributes the attributes to be returned along with entry 724 * @return the Entry with the given distinguished name or null if no entry exists with 725 * that distinguished name. 726 * @throws LdapException in case of any problems while searching for the distinguished name 727 * or if the returned response contains a referral 728 */ 729 Entry lookup( Dn dn, String... attributes ) throws LdapException; 730 731 732 /** 733 * Searches for an entry having the given distinguished name. 734 * 735 * @param dn the distinguished name of the entry to be fetched 736 * @param controls the controls to use 737 * @param attributes the attributes to be returned along with entry 738 * @return the Entry with the given distinguished name or null if no entry exists with 739 * that distinguished name. 740 * @throws LdapException in case of any problems while searching for the distinguished name 741 * or if the returned response contains a referral 742 */ 743 Entry lookup( Dn dn, Control[] controls, String... attributes ) throws LdapException; 744 745 746 /** 747 * Searches for an entry having the given distinguished name. 748 * 749 * @param dn the distinguished name of the entry to be fetched 750 * @param attributes the attributes to be returned along with entry 751 * @return the Entry with the given distinguished name or null if no entry exists with 752 * that distinguished name. 753 * @throws LdapException in case of any problems while searching for the distinguished name 754 * or if the returned response contains a referral 755 * @see #lookup(Dn, String...) 756 */ 757 Entry lookup( String dn, String... attributes ) throws LdapException; 758 759 760 /** 761 * Searches for an entry having the given distinguished name. 762 * 763 * @param dn the distinguished name of the entry to be fetched 764 * @param controls the controls to use 765 * @param attributes the attributes to be returned along with entry 766 * @return the Entry with the given distinguished name or null if no entry exists with 767 * that distinguished name. 768 * @throws LdapException in case of any problems while searching for the distinguished name 769 * or if the returned response contains a referral 770 * @see #lookup(Dn, String...) 771 */ 772 Entry lookup( String dn, Control[] controls, String... attributes ) throws LdapException; 773 774 775 /** 776 * Checks if a control with the given OID is supported. 777 * 778 * @param controlOID the OID of the control 779 * @return true if the control is supported, false otherwise 780 * @throws LdapException if some error occurred 781 */ 782 boolean isControlSupported( String controlOID ) throws LdapException; 783 784 785 /** 786 * Get the Controls supported by server. 787 * 788 * @return a list of control OIDs supported by server 789 * @throws LdapException if some error occurred 790 */ 791 List<String> getSupportedControls() throws LdapException; 792 793 794 /** 795 * Loads all the default schemas that are bundled with the API.<br><br> 796 * <b>Note:</b> This method enables <b>all</b> schemas prior to loading. 797 * 798 * @throws LdapException in case of problems while loading the schema 799 */ 800 void loadSchema() throws LdapException; 801 802 803 /** 804 * Loads all the default schemas that are bundled with the API, in a relaxed mode.<br><br> 805 * <b>Note:</b> This method enables <b>all</b> schemas prior to loading.<br> 806 * The relaxed mode will allow inconsistencies in the schema. 807 * 808 * @throws LdapException in case of problems while loading the schema 809 */ 810 void loadSchemaRelaxed() throws LdapException; 811 812 813 /** 814 * @return The SchemaManager associated with this LdapConection if any 815 */ 816 SchemaManager getSchemaManager(); 817 818 819 /** 820 * Gets the LDAP CODEC service responsible for encoding and decoding 821 * messages. 822 * 823 * @return The LDAP CODEC service. 824 */ 825 LdapApiService getCodecService(); 826 827 828 /** 829 * Checks if a request has been completed, or not. 830 * 831 * @param messageId ID of the request 832 * @return true if the request has been completed, false is still being processed 833 */ 834 boolean isRequestCompleted( int messageId ); 835 836 837 /** 838 * Checks if there is a ResponseFuture associated with the given message ID. 839 * 840 * @param messageId ID of the request 841 * @return true if there is a non-null future exists, false otherwise 842 * @deprecated Use {@link #isRequestCompleted(int)} 843 */ 844 @Deprecated 845 boolean doesFutureExistFor( int messageId ); 846 847 848 /** 849 * @return the object responsible for the detection of binary attributes 850 */ 851 BinaryAttributeDetector getBinaryAttributeDetector(); 852 853 854 /** 855 * Sets the object responsible for the detection of binary attributes. 856 * 857 * @param binaryAttributeDetecter The Binary Attribute Detector to use 858 */ 859 void setBinaryAttributeDetector( BinaryAttributeDetector binaryAttributeDetecter ); 860 861 862 /** 863 * sets a SchemaManager to be used by this connection 864 * @param schemaManager The SchemaManager to set 865 */ 866 void setSchemaManager( SchemaManager schemaManager ); 867 }