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