*
* Operations may be performed synchronously or asynchronously depending on the * method chosen. Asynchronous methods can be identified by their {@code Async} * suffix. *
*
* Synchronous methods block until a response is received from the Directory * Server, at which point an appropriate {@link Result} object is returned if * the operation succeeded, or thrown as an {@link ErrorResultException} if the * operation failed. *
* Since synchronous operations block the calling thread, the only way to * abandon a long running operation is to interrupt the calling thread from * another thread. This will cause the calling thread unblock and throw an * {@link InterruptedException}. *
*
* Asynchronous methods, identified by their {code Async} suffix, are * non-blocking, returning a {@link FutureResult} or sub-type thereof which can * be used for retrieving the result using the {@link FutureResult#get} method. * Operation failures, for whatever reason, are signalled by the * {@link FutureResult#get()} method throwing an {@link ErrorResultException}. *
* In addition to returning a {@code FutureResult}, all asynchronous methods * accept a {@link ResultHandler} which will be notified upon completion of the * operation. *
* Synchronous operations are easily simulated by immediately getting the * result: * *
* Connection connection = ...; * AddRequest request = ...; * // Will block until operation completes, and * // throws exception on failure. * connection.add(request).get(); ** * Operations can be performed in parallel while taking advantage of the * simplicity of a synchronous application design: * *
* Connection connection1 = ...; * Connection connection2 = ...; * AddRequest request = ...; * // Add the entry to the first server (don't block). * FutureResult future1 = connection1.add(request); * // Add the entry to the second server (in parallel). * FutureResult future2 = connection2.add(request); * // Total time = is O(1) instead of O(n). * future1.get(); * future2.get(); ** * More complex client applications can take advantage of a fully asynchronous * event driven design using {@link ResultHandler}s: * *
* Connection connection = ...; * SearchRequest request = ...; * // Process results in the search result handler * // in a separate thread. * SearchResponseHandler handle = ...; * connection.search(request, handler); **
*
* Applications must ensure that a connection is closed by calling * {@link #close()} even if a fatal error occurs on the connection. Once a * connection has been closed by the client application, any attempts to * continue to use the connection will result in an * {@link IllegalStateException} being thrown. Note that, if a fatal error is * encountered on the connection, then the application can continue to use the * connection. In this case all requests subsequent to the failure will fail * with an appropriate {@link ErrorResultException} when their result is * retrieved. *
*
* Applications can choose to be notified when a connection is closed by the * application, receives an unsolicited notification, or experiences a fatal * error by registering a {@link ConnectionEventListener} with the connection * using the {@link #addConnectionEventListener} method. * * @see RFC 4511 - Lightweight * Directory Access Protocol (LDAP): The Protocol */ public interface Connection extends Closeable { /** * Abandons the unfinished operation identified in the provided abandon * request. *
* Abandon requests do not have a response, so invoking the method get() on * the returned future will not block, nor return anything (it is Void), but * may throw an exception if a problem occurred while sending the abandon * request. In addition the returned future may be used in order to determine * the message ID of the abandon request. *
* Note: a more convenient approach to abandoning unfinished
* asynchronous operations is provided via the
* {@link FutureResult#cancel(boolean)} method.
*
* @param request
* The request identifying the operation to be abandoned.
* @return A future whose result is Void.
* @throws UnsupportedOperationException
* If this connection does not support abandon operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
FutureResult
* This method is equivalent to the following code:
*
*
* This method is equivalent to the following code:
*
*
* This method is equivalent to the following code:
*
*
* Other connection implementations may behave differently, and may choose not
* to send an unbind request if its use is inappropriate (for example a pooled
* connection will be released and returned to its connection pool without
* ever issuing an unbind request).
*
* This method is equivalent to the following code:
*
*
* Other connection implementations may behave differently, and may choose to
* ignore the provided unbind request if its use is inappropriate (for example
* a pooled connection will be released and returned to its connection pool
* without ever issuing an unbind request).
*
* Calling {@code close} on a connection that is already closed has no effect.
*
* @param request
* The unbind request to use in the case where a physical connection
* is closed.
* @param reason
* A reason describing why the connection was closed.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
void close(UnbindRequest request, String reason);
/**
* Compares an entry in the Directory Server using the provided compare
* request.
*
* @param request
* The compare request.
* @return The result of the operation.
* @throws ErrorResultException
* If the result code indicates that the request failed for some
* reason.
* @throws InterruptedException
* If the current thread was interrupted while waiting.
* @throws UnsupportedOperationException
* If this connection does not support compare operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
CompareResult compare(CompareRequest request) throws ErrorResultException,
InterruptedException;
/**
* Compares the named entry in the Directory Server against the provided
* attribute value assertion.
*
* This method is equivalent to the following code:
*
*
* This method is equivalent to the following code:
*
*
* This method is equivalent to the following code:
*
*
* This method is equivalent to the following code:
*
*
* This method is equivalent to the following code:
*
*
* If the requested entry is not returned by the Directory Server then the
* request will fail with an {@link EntryNotFoundException}. More
* specifically, this method will never return {@code null}.
*
* This method is equivalent to the following code:
*
*
* If the requested entry is not returned by the Directory Server then the
* request will fail with an {@link EntryNotFoundException}. More
* specifically, this method will never return {@code null}.
*
* This method is equivalent to the following code:
*
*
* If the requested entry is not returned by the Directory Server then the
* request will fail with an {@link EntryNotFoundException}. More
* specifically, the returned future will never return {@code null}.
*
* This method is equivalent to the following code:
*
*
* Unless otherwise specified, calling this method is equivalent to:
*
* Warning: Usage of this method is discouraged if the search request
* is expected to yield a large number of search results since the entire set
* of results will be stored in memory, potentially causing an
* {@code OutOfMemoryError}.
*
* This method is equivalent to the following code:
*
*
* Warning: Usage of this method is discouraged if the search request
* is expected to yield a large number of search results since the entire set
* of results will be stored in memory, potentially causing an
* {@code OutOfMemoryError}.
*
* @param request
* The search request.
* @param entries
* The collection to which matching entries should be added.
* @param references
* The collection to which search result references should be added,
* or {@code null} if references are to be discarded.
* @return The result of the operation.
* @throws ErrorResultException
* If the result code indicates that the request failed for some
* reason.
* @throws InterruptedException
* If the current thread was interrupted while waiting.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code request} or {@code entries} was {@code null}.
*/
Result search(SearchRequest request,
Collection entries,
Collection references)
throws ErrorResultException, InterruptedException;
/**
* Searches the Directory Server using the provided search request. Any
* matching entries returned by the search as well as any search result
* references will be passed to the provided search result handler.
*
* @param request
* The search request.
* @param handler
* A search result handler which can be used to process the search
* result entries and references as they are received, may be
* {@code null}.
* @return The result of the operation.
* @throws ErrorResultException
* If the result code indicates that the request failed for some
* reason.
* @throws InterruptedException
* If the current thread was interrupted while waiting.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
Result search(SearchRequest request, SearchResultHandler handler)
throws ErrorResultException, InterruptedException;
/**
* Searches the Directory Server using the provided search parameters. Any
* matching entries returned by the search will be exposed through the
* {@code EntryReader} interface.
*
* Warning: When using a queue with an optional capacity bound, the
* connection will stop reading responses and wait if necessary for space to
* become available.
*
* This method is equivalent to the following code:
*
*
* If the requested entry is not returned by the Directory Server then the
* request will fail with an {@link EntryNotFoundException}. More
* specifically, this method will never return {@code null}. If multiple
* matching entries are returned by the Directory Server then the request will
* fail with an {@link MultipleEntriesFoundException}.
*
* @param request
* The search request.
* @return The single search result entry returned from the search.
* @throws ErrorResultException
* If the result code indicates that the request failed for some
* reason.
* @throws InterruptedException
* If the current thread was interrupted while waiting.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If the {@code request} was {@code null}.
*/
SearchResultEntry searchSingleEntry(SearchRequest request)
throws ErrorResultException, InterruptedException;
/**
* Searches the Directory Server for a single entry using the provided search
* parameters.
*
* If the requested entry is not returned by the Directory Server then the
* request will fail with an {@link EntryNotFoundException}. More
* specifically, this method will never return {@code null}. If multiple
* matching entries are returned by the Directory Server then the request will
* fail with an {@link MultipleEntriesFoundException}.
*
* This method is equivalent to the following code:
*
*
* If the requested entry is not returned by the Directory Server then the
* request will fail with an {@link EntryNotFoundException}. More
* specifically, the returned future will never return {@code null}. If
* multiple matching entries are returned by the Directory Server then the
* request will fail with an {@link MultipleEntriesFoundException}.
*
* @param request
* The search request.
* @param handler
* A result handler which can be used to asynchronously process the
* operation result when it is received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If the {@code request} was {@code null}.
*/
FutureResult
* AddRequest request = new AddRequest(entry);
* connection.add(request);
*
*
* @param entry
* The entry to be added.
* @return The result of the operation.
* @throws ErrorResultException
* If the result code indicates that the request failed for some
* reason.
* @throws InterruptedException
* If the current thread was interrupted while waiting.
* @throws UnsupportedOperationException
* If this connection does not support add operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code entry} was {@code null} .
*/
Result add(Entry entry) throws ErrorResultException, InterruptedException;
/**
* Adds an entry to the Directory Server using the provided lines of LDIF.
*
* AddRequest request = new AddRequest(ldifLines);
* connection.add(request);
*
*
* @param ldifLines
* Lines of LDIF containing the an LDIF add change record or an LDIF
* entry record.
* @return The result of the operation.
* @throws ErrorResultException
* If the result code indicates that the request failed for some
* reason.
* @throws InterruptedException
* If the current thread was interrupted while waiting.
* @throws UnsupportedOperationException
* If this connection does not support add operations.
* @throws LocalizedIllegalArgumentException
* If {@code ldifLines} was empty, or contained invalid LDIF, or
* could not be decoded using the default schema.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code ldifLines} was {@code null} .
*/
Result add(String... ldifLines) throws ErrorResultException,
InterruptedException;
/**
* Asynchronously adds an entry to the Directory Server using the provided add
* request.
*
* @param request
* The add request.
* @param intermediateResponseHandler
* An intermediate response handler which can be used to process any
* intermediate responses as they are received, may be {@code null}.
* @param resultHandler
* A result handler which can be used to asynchronously process the
* operation result when it is received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support add operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
FutureResult
* BindRequest request = new SimpleBindRequest(name, password);
* connection.bind(request);
*
*
* @param name
* The distinguished name of the Directory object that the client
* wishes to bind as, which may be empty.
* @param password
* The password of the Directory object that the client wishes to
* bind as, which may be empty.
* @return The result of the operation.
* @throws ErrorResultException
* If the result code indicates that the request failed for some
* reason.
* @throws InterruptedException
* If the current thread was interrupted while waiting.
* @throws LocalizedIllegalArgumentException
* If {@code name} could not be decoded using the default schema.
* @throws UnsupportedOperationException
* If this connection does not support bind operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code name} or {@code password} was {@code null}.
*/
BindResult bind(String name, char[] password) throws ErrorResultException,
InterruptedException;
/**
* Asynchronously authenticates to the Directory Server using the provided
* bind request.
*
* @param request
* The bind request.
* @param intermediateResponseHandler
* An intermediate response handler which can be used to process any
* intermediate responses as they are received, may be {@code null}.
* @param resultHandler
* A result handler which can be used to asynchronously process the
* operation result when it is received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support bind operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
FutureResult
* UnbindRequest request = new UnbindRequest();
* connection.close(request);
*
*
* Calling {@code close} on a connection that is already closed has no effect.
*/
void close();
/**
* Releases any resources associated with this connection. For physical
* connections to a Directory Server this will mean that the provided unbind
* request is sent and the underlying socket is closed.
*
* CompareRequest request = new CompareRequest(name, attributeDescription,
* assertionValue);
* connection.compare(request);
*
*
* @param name
* The distinguished name of the entry to be compared.
* @param attributeDescription
* The name of the attribute to be compared.
* @param assertionValue
* The assertion value to be compared.
* @return The result of the operation.
* @throws ErrorResultException
* If the result code indicates that the request failed for some
* reason.
* @throws InterruptedException
* If the current thread was interrupted while waiting.
* @throws LocalizedIllegalArgumentException
* If {@code name} or {@code AttributeDescription} could not be
* decoded using the default schema.
* @throws UnsupportedOperationException
* If this connection does not support compare operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code name}, {@code attributeDescription}, or
* {@code assertionValue} was {@code null}.
*/
CompareResult compare(String name, String attributeDescription,
String assertionValue) throws ErrorResultException, InterruptedException;
/**
* Asynchronously compares an entry in the Directory Server using the provided
* compare request.
*
* @param request
* The compare request.
* @param intermediateResponseHandler
* An intermediate response handler which can be used to process any
* intermediate responses as they are received, may be {@code null}.
* @param resultHandler
* A result handler which can be used to asynchronously process the
* operation result when it is received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support compare operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
FutureResult
* DeleteRequest request = new DeleteRequest(name);
* connection.delete(request);
*
*
* @param name
* The distinguished name of the entry to be deleted.
* @return The result of the operation.
* @throws ErrorResultException
* If the result code indicates that the request failed for some
* reason.
* @throws InterruptedException
* If the current thread was interrupted while waiting.
* @throws LocalizedIllegalArgumentException
* If {@code name} could not be decoded using the default schema.
* @throws UnsupportedOperationException
* If this connection does not support delete operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code name} was {@code null}.
*/
Result delete(String name) throws ErrorResultException, InterruptedException;
/**
* Asynchronously deletes an entry from the Directory Server using the
* provided delete request.
*
* @param request
* The delete request.
* @param intermediateResponseHandler
* An intermediate response handler which can be used to process any
* intermediate responses as they are received, may be {@code null}.
* @param resultHandler
* A result handler which can be used to asynchronously process the
* operation result when it is received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support delete operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
FutureResult
* GenericExtendedRequest request = new GenericExtendedRequest(requestName,
* requestValue);
* connection.extendedRequest(request);
*
*
* @param requestName
* The dotted-decimal representation of the unique OID corresponding
* to the extended request.
* @param requestValue
* The content of the extended request in a form defined by the
* extended operation, or {@code null} if there is no content.
* @return The result of the operation.
* @throws ErrorResultException
* If the result code indicates that the request failed for some
* reason.
* @throws InterruptedException
* If the current thread was interrupted while waiting.
* @throws UnsupportedOperationException
* If this connection does not support extended operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code requestName} was {@code null}.
*/
GenericExtendedResult extendedRequest(String requestName,
ByteString requestValue) throws ErrorResultException,
InterruptedException;
/**
* Asynchronously performs the provided extended request in the Directory
* Server.
*
* @param
* ModifyRequest request = new ModifyRequest(name, ldifChanges);
* connection.modify(request);
*
*
* @param ldifLines
* Lines of LDIF containing the a single LDIF modify change record.
* @return The result of the operation.
* @throws ErrorResultException
* If the result code indicates that the request failed for some
* reason.
* @throws InterruptedException
* If the current thread was interrupted while waiting.
* @throws UnsupportedOperationException
* If this connection does not support modify operations.
* @throws LocalizedIllegalArgumentException
* If {@code ldifLines} was empty, or contained invalid LDIF, or
* could not be decoded using the default schema.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code ldifLines} was {@code null} .
*/
Result modify(String... ldifLines) throws ErrorResultException,
InterruptedException;
/**
* Asynchronously modifies an entry in the Directory Server using the provided
* modify request.
*
* @param request
* The modify request.
* @param intermediateResponseHandler
* An intermediate response handler which can be used to process any
* intermediate responses as they are received, may be {@code null}.
* @param resultHandler
* A result handler which can be used to asynchronously process the
* operation result when it is received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support modify operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
FutureResult
* ModifyDNRequest request = new ModifyDNRequest(name, newRDN);
* connection.modifyDN(request);
*
*
* @param name
* The distinguished name of the entry to be renamed.
* @param newRDN
* The new RDN of the entry.
* @return The result of the operation.
* @throws ErrorResultException
* If the result code indicates that the request failed for some
* reason.
* @throws InterruptedException
* If the current thread was interrupted while waiting.
* @throws LocalizedIllegalArgumentException
* If {@code name} or {@code newRDN} could not be decoded using the
* default schema.
* @throws UnsupportedOperationException
* If this connection does not support modify DN operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code name} or {@code newRDN} was {@code null}.
*/
Result modifyDN(String name, String newRDN) throws ErrorResultException,
InterruptedException;
/**
* Asynchronously renames an entry in the Directory Server using the provided
* modify DN request.
*
* @param request
* The modify DN request.
* @param intermediateResponseHandler
* An intermediate response handler which can be used to process any
* intermediate responses as they are received, may be {@code null}.
* @param resultHandler
* A result handler which can be used to asynchronously process the
* operation result when it is received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support modify DN operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
FutureResult
* SearchRequest request = new SearchRequest(name, SearchScope.BASE_OBJECT,
* "(objectClass=*)", attributeDescriptions);
* connection.searchSingleEntry(request);
*
*
* @param name
* The distinguished name of the entry to be read.
* @param attributeDescriptions
* The names of the attributes to be included with the entry, which
* may be {@code null} or empty indicating that all user attributes
* should be returned.
* @return The single search result entry returned from the search.
* @throws ErrorResultException
* If the result code indicates that the request failed for some
* reason.
* @throws InterruptedException
* If the current thread was interrupted while waiting.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If the {@code name} was {@code null}.
*/
SearchResultEntry readEntry(DN name, String... attributeDescriptions)
throws ErrorResultException, InterruptedException;
/**
* Reads the named entry from the Directory Server.
*
* SearchRequest request = new SearchRequest(name, SearchScope.BASE_OBJECT,
* "(objectClass=*)", attributeDescriptions);
* connection.searchSingleEntry(request);
*
*
* @param name
* The distinguished name of the entry to be read.
* @param attributeDescriptions
* The names of the attributes to be included with the entry.
* @return The single search result entry returned from the search.
* @throws ErrorResultException
* If the result code indicates that the request failed for some
* reason.
* @throws InterruptedException
* If the current thread was interrupted while waiting.
* @throws LocalizedIllegalArgumentException
* If {@code baseObject} could not be decoded using the default
* schema.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If the {@code name} was {@code null}.
*/
SearchResultEntry readEntry(String name, String... attributeDescriptions)
throws ErrorResultException, InterruptedException;
/**
* Asynchronously reads the named entry from the Directory Server.
*
* SearchRequest request = new SearchRequest(name, SearchScope.BASE_OBJECT,
* "(objectClass=*)", attributeDescriptions);
* connection.searchSingleEntryAsync(request, resultHandler, p);
*
*
* @param name
* The distinguished name of the entry to be read.
* @param attributeDescriptions
* The names of the attributes to be included with the entry, which
* may be {@code null} or empty indicating that all user attributes
* should be returned.
* @param handler
* A result handler which can be used to asynchronously process the
* operation result when it is received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If the {@code name} was {@code null}.
*/
FutureResult
* ConnectionEntryReader reader = new ConnectionEntryReader(this, request);
*
*
* @param request
* The search request.
* @return The result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code request} or {@code entries} was {@code null}.
*/
ConnectionEntryReader search(SearchRequest request);
/**
* Searches the Directory Server using the provided search request. Any
* matching entries returned by the search will be added to {@code entries},
* even if the final search result indicates that the search failed. Search
* result references will be discarded.
*
* connection.search(request, entries, null);
*
*
* @param request
* The search request.
* @param entries
* The collection to which matching entries should be added.
* @return The result of the operation.
* @throws ErrorResultException
* If the result code indicates that the request failed for some
* reason.
* @throws InterruptedException
* If the current thread was interrupted while waiting.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code request} or {@code entries} was {@code null}.
*/
Result search(SearchRequest request,
Collection entries)
throws ErrorResultException, InterruptedException;
/**
* Searches the Directory Server using the provided search request. Any
* matching entries returned by the search will be added to {@code entries},
* even if the final search result indicates that the search failed.
* Similarly, search result references returned by the search will be added to
* {@code references}.
*
* SearchRequest request = new SearchRequest(baseDN, scope, filter,
* attributeDescriptions);
* connection.search(request, new LinkedBlockingQueue<Response>());
*
*
* @param baseObject
* The distinguished name of the base entry relative to which the
* search is to be performed.
* @param scope
* The scope of the search.
* @param filter
* The filter that defines the conditions that must be fulfilled in
* order for an entry to be returned.
* @param attributeDescriptions
* The names of the attributes to be included with each entry.
* @return An entry reader exposing the returned entries.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If the {@code baseObject}, {@code scope}, or {@code filter} were
* {@code null}.
*/
ConnectionEntryReader search(String baseObject, SearchScope scope,
String filter, String... attributeDescriptions);
/**
* Asynchronously searches the Directory Server using the provided search
* request.
*
* @param request
* The search request.
* @param intermediateResponseHandler
* An intermediate response handler which can be used to process any
* intermediate responses as they are received, may be {@code null}.
* @param resultHandler
* A search result handler which can be used to asynchronously
* process the search result entries and references as they are
* received, may be {@code null}.
* @return A future representing the result of the operation.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If {@code request} was {@code null}.
*/
FutureResult
* SearchRequest request = new SearchRequest(baseObject, scope, filter,
* attributeDescriptions);
* connection.searchSingleEntry(request);
*
*
* @param baseObject
* The distinguished name of the base entry relative to which the
* search is to be performed.
* @param scope
* The scope of the search.
* @param filter
* The filter that defines the conditions that must be fulfilled in
* order for an entry to be returned.
* @param attributeDescriptions
* The names of the attributes to be included with each entry.
* @return The single search result entry returned from the search.
* @throws ErrorResultException
* If the result code indicates that the request failed for some
* reason.
* @throws InterruptedException
* If the current thread was interrupted while waiting.
* @throws LocalizedIllegalArgumentException
* If {@code baseObject} could not be decoded using the default
* schema or if {@code filter} is not a valid LDAP string
* representation of a filter.
* @throws UnsupportedOperationException
* If this connection does not support search operations.
* @throws IllegalStateException
* If this connection has already been closed, i.e. if
* {@code isClosed() == true}.
* @throws NullPointerException
* If the {@code baseObject}, {@code scope}, or {@code filter} were
* {@code null}.
*/
SearchResultEntry searchSingleEntry(String baseObject, SearchScope scope,
String filter, String... attributeDescriptions)
throws ErrorResultException, InterruptedException;
/**
* Asynchronously searches the Directory Server for a single entry using the
* provided search request.
*