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