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