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