*
* All operations are performed synchronously and return an appropriate * {@link Result} representing the final status of the operation. * Operation failures, for whatever reason, are signalled using an * {@link ErrorResultException}. *
*
* 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. *
*
*
* This method is equivalent to the following code: * *
* 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, UnsupportedOperationException, IllegalStateException, NullPointerException; /** * Adds an entry to the Directory Server using the provided lines of * LDIF. *
* This method is equivalent to the following code: * *
* 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, UnsupportedOperationException, LocalizedIllegalArgumentException, IllegalStateException, NullPointerException; /** * Registers the provided connection event listener so that it will be * notified when this connection is closed by the application, * receives an unsolicited notification, or experiences a fatal error. * * @param listener * The listener which wants to be notified when events occur * on this connection. * @throws IllegalStateException * If this connection has already been closed, i.e. if * {@code isClosed() == true}. * @throws NullPointerException * If the {@code listener} was {@code null}. */ void addConnectionEventListener(ConnectionEventListener listener) throws IllegalStateException, NullPointerException; /** * Authenticates to the Directory Server using the provided bind * request. * * @param request * The bind 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 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}. */ BindResult bind(BindRequest request) throws ErrorResultException, InterruptedException, UnsupportedOperationException, IllegalStateException, NullPointerException; /** * Authenticates to the Directory Server using simple authentication * and the provided user name and password. *
* This method is equivalent to the following code: * *
* 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, String password) throws ErrorResultException, InterruptedException, LocalizedIllegalArgumentException, UnsupportedOperationException, IllegalStateException, NullPointerException; /** * Releases any resources associated with this connection. For * physical connections to a Directory Server this will mean that an * unbind request is sent and the underlying socket is closed. *
* 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: * *
* 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. *
* 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) throws NullPointerException; /** * 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, UnsupportedOperationException, IllegalStateException, NullPointerException; /** * Compares the named entry in the Directory Server against the * provided attribute value assertion. *
* This method is equivalent to the following code: * *
* 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, LocalizedIllegalArgumentException, UnsupportedOperationException, IllegalStateException, NullPointerException; /** * Deletes an entry from the Directory Server using the provided * delete request. * * @param request * The delete 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 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}. */ Result delete(DeleteRequest request) throws ErrorResultException, InterruptedException, UnsupportedOperationException, IllegalStateException, NullPointerException; /** * Deletes the named entry from the Directory Server. *
* This method is equivalent to the following code: * *
* 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, LocalizedIllegalArgumentException, UnsupportedOperationException, IllegalStateException, NullPointerException; /** * Requests that the Directory Server performs the provided extended * request. * * @param
* This method is equivalent to the following code: * *
* 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, UnsupportedOperationException, IllegalStateException, NullPointerException; // // // // /** // * Indicates whether or not this connection is valid. A connection // is // * not valid if the method {@code close} has been called on it or if // * certain fatal errors have occurred. This method is guaranteed to // * return {@code false} only when it is called after the method // * {@code close} has been called. // *
// * Implementations may choose to send a no-op request to the // * underlying Directory Server in order to determine if the // underlying // * connection is still valid. // * // * @return {@code true} if this connection is valid, or {@code // false} // * otherwise. // * @throws InterruptedException // * If the current thread was interrupted while waiting. // */ // boolean isValid() throws InterruptedException; // // // // /** // * Indicates whether or not this connection is valid. A connection // is // * not valid if the method {@code close} has been called on it or if // * certain fatal errors have occurred. This method is guaranteed to // * return {@code false} only when it is called after the method // * {@code close} has been called. // *
// * Implementations may choose to send a no-op request to the // * underlying Directory Server in order to determine if the // underlying // * connection is still valid. // * // * @param timeout // * The maximum time to wait. // * @param unit // * The time unit of the timeout argument. // * @return {@code true} if this connection is valid, or {@code // false} // * otherwise. // * @throws InterruptedException // * If the current thread was interrupted while waiting. // * @throws TimeoutException // * If the wait timed out. // */ // boolean isValid(long timeout, TimeUnit unit) // throws InterruptedException, TimeoutException; /** * Indicates whether or not this connection has been explicitly closed * by calling {@code close}. This method will not return {@code true} * if a fatal error has occurred on the connection unless {@code * close} has been called. * * @return {@code true} if this connection has been explicitly closed * by calling {@code close}, or {@code false} otherwise. */ boolean isClosed(); /** * Modifies an entry in the Directory Server using the provided modify * request. * * @param request * The modify 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 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}. */ Result modify(ModifyRequest request) throws ErrorResultException, InterruptedException, UnsupportedOperationException, IllegalStateException, NullPointerException; /** * Modifies an entry in the Directory Server using the provided lines * of LDIF. *
* This method is equivalent to the following code: * *
* 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, UnsupportedOperationException, LocalizedIllegalArgumentException, IllegalStateException, NullPointerException; /** * Renames an entry in the Directory Server using the provided modify * DN request. * * @param request * The modify DN 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 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}. */ Result modifyDN(ModifyDNRequest request) throws ErrorResultException, InterruptedException, UnsupportedOperationException, IllegalStateException, NullPointerException; /** * Renames the named entry in the Directory Server using the provided * new RDN. *
* This method is equivalent to the following code: * *
* 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, LocalizedIllegalArgumentException, InterruptedException, UnsupportedOperationException, IllegalStateException, NullPointerException; /** * Reads the named entry from the Directory Server. *
* 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: * *
* 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, UnsupportedOperationException, IllegalStateException, NullPointerException; /** * Reads the named entry from the Directory Server. *
* 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: * *
* 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, LocalizedIllegalArgumentException, UnsupportedOperationException, IllegalStateException, NullPointerException; /** * Reads the Root DSE from the Directory Server. *
* If the Root DSE 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}. * * @return The Directory Server's Root DSE. * @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}. */ RootDSE readRootDSE() throws ErrorResultException, InterruptedException, UnsupportedOperationException, IllegalStateException; /** * Reads the schema from the Directory Server contained in the named * subschema sub-entry. *
* If the requested schema 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}. *
* Implementations may choose to perform optimizations such as * caching. * * @param name * The distinguished name of the subschema sub-entry. * @return The schema from the Directory Server. * @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}. */ Schema readSchema(DN name) throws ErrorResultException, InterruptedException, UnsupportedOperationException, IllegalStateException; /** * Reads the schema from the Directory Server contained in the named * subschema sub-entry. *
* If the requested schema 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}. *
* Implementations may choose to perform optimizations such as * caching. * * @param name * The distinguished name of the subschema sub-entry. * @return The schema from the Directory Server. * @throws ErrorResultException * If the result code indicates that the request failed for * some reason. * @throws LocalizedIllegalArgumentException * If {@code name} could not be decoded using the default * schema. * @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}. */ Schema readSchema(String name) throws ErrorResultException, InterruptedException, LocalizedIllegalArgumentException, UnsupportedOperationException, IllegalStateException; /** * Reads the schema from the Directory Server which applies to the * named entry. *
* If the requested entry or its associated schema are not returned by * the Directory Server then the request will fail with an * {@link EntryNotFoundException}. More specifically, this method will * never return {@code null}. *
* A typical implementation will first read the {@code * subschemaSubentry} attribute of the entry in order to locate the * schema. However, implementations may choose to perform other * optimizations, such as caching. * * @param name * The distinguished name of the entry whose schema is to be * located. * @return The schema from the Directory Server which applies to the * named entry. * @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}. */ Schema readSchemaForEntry(DN name) throws ErrorResultException, InterruptedException, UnsupportedOperationException, IllegalStateException; /** * Reads the schema from the Directory Server which applies to the * named entry. *
* If the requested entry or its associated schema are not returned by * the Directory Server then the request will fail with an * {@link EntryNotFoundException}. More specifically, this method will * never return {@code null}. *
* A typical implementation will first read the {@code * subschemaSubentry} attribute of the entry in order to locate the * schema. However, implementations may choose to perform other * optimizations, such as caching. * * @param name * The distinguished name of the entry whose schema is to be * located. * @return The schema from the Directory Server which applies to the * named entry. * @throws ErrorResultException * If the result code indicates that the request failed for * some reason. * @throws LocalizedIllegalArgumentException * If {@code name} could not be decoded using the default * schema. * @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}. */ Schema readSchemaForEntry(String name) throws ErrorResultException, InterruptedException, LocalizedIllegalArgumentException, UnsupportedOperationException, IllegalStateException; /** * Reads the schema from the Directory Server which applies to the * Root DSE. *
* If the requested schema 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}. *
* A typical implementation will first read the {@code * subschemaSubentry} attribute of the Root DSE in order to locate the * schema. However, implementations may choose to perform other * optimizations, such as caching. *
* This method is equivalent to the following code: * *
* connection.readSchemaForEntry(DN.rootDN()); ** * @return The schema from the Directory Server which applies to the * named entry. * @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}. */ Schema readSchemaForRootDSE() throws ErrorResultException, InterruptedException, UnsupportedOperationException, IllegalStateException; /** * Removes the provided connection event listener from this connection * so that it will no longer be notified when this connection is * closed by the application, receives an unsolicited notification, or * experiences a fatal error. * * @param listener * The listener which no longer wants to be notified when * events occur on this connection. * @throws NullPointerException * If the {@code listener} was {@code null}. */ void removeConnectionEventListener(ConnectionEventListener listener) throws NullPointerException; /** * 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. *
* 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: * *
* 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, UnsupportedOperationException, IllegalStateException, NullPointerException; /** * 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}. *
* 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, UnsupportedOperationException, IllegalStateException, NullPointerException; /** * 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, UnsupportedOperationException, IllegalStateException, NullPointerException; /** * Searches the Directory Server using the provided search parameters. * Any matching entries returned by the search will be added to a * {@code List} which is returned if the search succeeds. Search * result references will be discarded. *
* 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: * *
* SearchRequest request = new SearchRequest(baseDN, scope, filter, * attributeDescriptions); * connection.search(request, new LinkedList<SearchResultEntry>()); ** * @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 A list containing any matching entries returned by 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}. */ List
* 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, UnsupportedOperationException, IllegalStateException, NullPointerException; /** * 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: * *
* 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, LocalizedIllegalArgumentException, UnsupportedOperationException, IllegalStateException, NullPointerException; }