org.forgerock.opendj.ldap

Interface Connection

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

AbstractAsynchronousConnection, AbstractConnection, AbstractConnectionWrapper, AbstractSynchronousConnection, SdkConnectionAdapter

public interface Connection
extends Closeable

A connection with a Directory Server over which read and update operations may be performed. See RFC 4511 for the LDAPv3 protocol specification and more information about the types of operations defined in LDAP.

Operation processing

Operations may be performed synchronously or asynchronously depending on the method chosen. Asynchronous methods can be identified by their Async suffix.

Performing operations synchronously

Synchronous methods block until a response is received from the Directory Server, at which point an appropriate Result object is returned if the operation succeeded, or thrown as an LdapException 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 a CancelledResultException whose cause is the underlying InterruptedException.

Performing operations asynchronously

Asynchronous methods, identified by their Async suffix, are non-blocking, returning a LdapPromise or sub-type thereof which can be used for retrieving the result using the Promise.get() method. Operation failures, for whatever reason, are signaled by the Promise.get() method throwing an LdapException.

In addition to returning a LdapPromise, all asynchronous methods accept a LdapResultHandler 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).
 LdapPromise promise1 = connection1.add(request);
 // Add the entry to the second server (in parallel).
 LdapPromise promise2 = connection2.add(request);
 // Total time = is O(1) instead of O(n).
 promise1.get();
 promise2.get();
 

More complex client applications can take advantage of a fully asynchronous event driven design using LdapResultHandlers:

 Connection connection = ...;
 SearchRequest request = ...;
 // Process results in the search result handler
 // in a separate thread.
 SearchResponseHandler handle = ...;
 connection.search(request, handler);
 

Closing connections

Applications must ensure that a connection is closed by calling 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 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 LdapException when their result is retrieved.

Event notification

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 ConnectionEventListener with the connection using the addConnectionEventListener(org.forgerock.opendj.ldap.ConnectionEventListener) method.

See Also:

RFC 4511 - Lightweight Directory Access Protocol (LDAP): The Protocol

Method Summary

Modifier and Type	Method and Description
LdapPromise<Void>	abandonAsync(AbandonRequest request) Abandons the unfinished operation identified in the provided abandon request.
Result	add(AddRequest request) Adds an entry to the Directory Server using the provided add request.
Result	add(Entry entry) Adds the provided entry to the Directory Server.
Result	add(String... ldifLines) Adds an entry to the Directory Server using the provided lines of LDIF.
LdapPromise<Result>	addAsync(AddRequest request) Asynchronously adds an entry to the Directory Server using the provided add request.
LdapPromise<Result>	addAsync(AddRequest request, IntermediateResponseHandler intermediateResponseHandler) Asynchronously adds an entry to the Directory Server using the provided add request.
void	addConnectionEventListener(ConnectionEventListener listener) 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.
Result	applyChange(ChangeRecord request) Applies the provided change request to the Directory Server.
LdapPromise<Result>	applyChangeAsync(ChangeRecord request) Asynchronously applies the provided change request to the Directory Server.
LdapPromise<Result>	applyChangeAsync(ChangeRecord request, IntermediateResponseHandler intermediateResponseHandler) Asynchronously applies the provided change request to the Directory Server.
BindResult	bind(BindRequest request) Authenticates to the Directory Server using the provided bind request.
BindResult	bind(String name, char[] password) Authenticates to the Directory Server using simple authentication and the provided user name and password.
LdapPromise<BindResult>	bindAsync(BindRequest request) Asynchronously authenticates to the Directory Server using the provided bind request.
LdapPromise<BindResult>	bindAsync(BindRequest request, IntermediateResponseHandler intermediateResponseHandler) Asynchronously authenticates to the Directory Server using the provided bind request.
void	close() Releases any resources associated with this connection.
void	close(UnbindRequest request, String reason) Releases any resources associated with this connection.
CompareResult	compare(CompareRequest request) Compares an entry in the Directory Server using the provided compare request.
CompareResult	compare(String name, String attributeDescription, String assertionValue) Compares the named entry in the Directory Server against the provided attribute value assertion.
LdapPromise<CompareResult>	compareAsync(CompareRequest request) Asynchronously compares an entry in the Directory Server using the provided compare request.
LdapPromise<CompareResult>	compareAsync(CompareRequest request, IntermediateResponseHandler intermediateResponseHandler) Asynchronously compares an entry in the Directory Server using the provided compare request.
Result	delete(DeleteRequest request) Deletes an entry from the Directory Server using the provided delete request.
default Result	delete(Dn name) Deletes the named entry from the Directory Server.
Result	delete(String name) Deletes the named entry from the Directory Server.
LdapPromise<Result>	deleteAsync(DeleteRequest request) Asynchronously deletes an entry from the Directory Server using the provided delete request.
LdapPromise<Result>	deleteAsync(DeleteRequest request, IntermediateResponseHandler intermediateResponseHandler) Asynchronously deletes an entry from the Directory Server using the provided delete request.
Result	deleteSubtree(String name) Deletes the named entry and all of its subordinates from the Directory Server.
<R extends ExtendedResult> R	extendedRequest(ExtendedRequest<R> request) Requests that the Directory Server performs the provided extended request.
<R extends ExtendedResult> R	extendedRequest(ExtendedRequest<R> request, IntermediateResponseHandler handler) Requests that the Directory Server performs the provided extended request, optionally listening for any intermediate responses.
GenericExtendedResult	extendedRequest(String requestName, ByteString requestValue) Requests that the Directory Server performs the provided extended request.
<R extends ExtendedResult> LdapPromise<R>	extendedRequestAsync(ExtendedRequest<R> request) Asynchronously performs the provided extended request in the Directory Server.
<R extends ExtendedResult> LdapPromise<R>	extendedRequestAsync(ExtendedRequest<R> request, IntermediateResponseHandler intermediateResponseHandler) Asynchronously performs the provided extended request in the Directory Server.
boolean	isClosed() Indicates whether this connection has been explicitly closed by calling close.
boolean	isValid() Returns true if this connection has not been closed and no fatal errors have been detected.
Result	modify(ModifyRequest request) Modifies an entry in the Directory Server using the provided modify request.
Result	modify(String... ldifLines) Modifies an entry in the Directory Server using the provided lines of LDIF.
LdapPromise<Result>	modifyAsync(ModifyRequest request) Asynchronously modifies an entry in the Directory Server using the provided modify request.
LdapPromise<Result>	modifyAsync(ModifyRequest request, IntermediateResponseHandler intermediateResponseHandler) Asynchronously modifies an entry in the Directory Server using the provided modify request.
Result	modifyDn(ModifyDnRequest request) Renames an entry in the Directory Server using the provided modify DN request.
Result	modifyDn(String name, String newRDN) Renames the named entry in the Directory Server using the provided new RDN.
LdapPromise<Result>	modifyDnAsync(ModifyDnRequest request) Asynchronously renames an entry in the Directory Server using the provided modify DN request.
LdapPromise<Result>	modifyDnAsync(ModifyDnRequest request, IntermediateResponseHandler intermediateResponseHandler) Asynchronously renames an entry in the Directory Server using the provided modify DN request.
SearchResultEntry	readEntry(Dn name, String... attributeDescriptions) Reads the named entry from the Directory Server.
SearchResultEntry	readEntry(String name, String... attributeDescriptions) Reads the named entry from the Directory Server.
LdapPromise<SearchResultEntry>	readEntryAsync(Dn name, Collection<String> attributeDescriptions) Asynchronously reads the named entry from the Directory Server.
void	removeConnectionEventListener(ConnectionEventListener listener) 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.
ConnectionEntryReader	search(SearchRequest request) Searches the Directory Server using the provided search parameters.
Result	search(SearchRequest request, Collection<? super SearchResultEntry> entries) Searches the Directory Server using the provided search request.
Result	search(SearchRequest request, Collection<? super SearchResultEntry> entries, Collection<? super SearchResultReference> references) Searches the Directory Server using the provided search request.
Result	search(SearchRequest request, SearchResultHandler handler) Searches the Directory Server using the provided search request.
ConnectionEntryReader	search(String baseObject, SearchScope scope, String filter, String... attributeDescriptions) Searches the Directory Server using the provided search parameters.
LdapPromise<Result>	searchAsync(SearchRequest request, IntermediateResponseHandler intermediateResponseHandler, SearchResultHandler entryHandler) Asynchronously searches the Directory Server using the provided search request.
LdapPromise<Result>	searchAsync(SearchRequest request, SearchResultHandler entryHandler) Asynchronously searches the Directory Server using the provided search request.
SearchResultEntry	searchSingleEntry(SearchRequest request) Searches the Directory Server for a single entry using the provided search request.
SearchResultEntry	searchSingleEntry(String baseObject, SearchScope scope, String filter, String... attributeDescriptions) Searches the Directory Server for a single entry using the provided search parameters.
LdapPromise<SearchResultEntry>	searchSingleEntryAsync(SearchRequest request) Asynchronously searches the Directory Server for a single entry using the provided search request.

Method Detail

abandonAsync

LdapPromise<Void> abandonAsync(AbandonRequest request)

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 promise 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 promise 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 Promise.cancel(boolean) method.

Parameters:

request - The request identifying the operation to be abandoned.

Returns:

A promise whose result is Void.

Throws:

UnsupportedOperationException - If this connection does not support abandon operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

add

Result add(AddRequest request)
    throws LdapException

Adds an entry to the Directory Server using the provided add request.

Parameters:

request - The add request.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support add operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

add

Result add(Entry entry)
    throws LdapException

Adds the provided entry to the Directory Server.

This method is equivalent to the following code:

 AddRequest request = new AddRequest(entry);
 connection.add(request);
 

Parameters:

entry - The entry to be added.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support add operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If entry was null .

add

Result add(String... ldifLines)
    throws LdapException

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);
 

Parameters:

ldifLines - Lines of LDIF containing the an LDIF add change record or an LDIF entry record.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support add operations.

LocalizedIllegalArgumentException - If ldifLines was empty, or contained invalid LDIF, or could not be decoded using the default schema.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If ldifLines was null .

addAsync

LdapPromise<Result> addAsync(AddRequest request)

Asynchronously adds an entry to the Directory Server using the provided add request.

Parameters:

request - The add request.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support add operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

addAsync

LdapPromise<Result> addAsync(AddRequest request,
                             IntermediateResponseHandler intermediateResponseHandler)

Asynchronously adds an entry to the Directory Server using the provided add request.

Parameters:

request - The add request.

intermediateResponseHandler - An intermediate response handler which can be used to process any intermediate responses as they are received, may be null.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support add operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

addConnectionEventListener

void addConnectionEventListener(ConnectionEventListener listener)

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.

Parameters:

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 isClosed() == true.

NullPointerException - If the listener was null.

applyChange

Result applyChange(ChangeRecord request)
            throws LdapException

Applies the provided change request to the Directory Server.

Parameters:

request - The change request.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support the provided change request.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

applyChangeAsync

LdapPromise<Result> applyChangeAsync(ChangeRecord request)

Asynchronously applies the provided change request to the Directory Server.

Parameters:

request - The change request.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support the provided change request.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

applyChangeAsync

LdapPromise<Result> applyChangeAsync(ChangeRecord request,
                                     IntermediateResponseHandler intermediateResponseHandler)

Asynchronously applies the provided change request to the Directory Server.

Parameters:

request - The change request.

intermediateResponseHandler - An intermediate response handler which can be used to process any intermediate responses as they are received, may be null.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support the provided change request.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

bind

BindResult bind(BindRequest request)
         throws LdapException

Authenticates to the Directory Server using the provided bind request.

Parameters:

request - The bind request.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support bind operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

bind

BindResult bind(String name,
                char[] password)
         throws LdapException

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);
 

Parameters:

name - The distinguished name of the Directory object that the client wishes to bind as, which may be empty.

password - The password of the Directory object that the client wishes to bind as, which may be empty.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

LocalizedIllegalArgumentException - If name could not be decoded using the default schema.

UnsupportedOperationException - If this connection does not support bind operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If name or password was null.

bindAsync

LdapPromise<BindResult> bindAsync(BindRequest request)

Asynchronously authenticates to the Directory Server using the provided bind request.

Parameters:

request - The bind request.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support bind operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

bindAsync

LdapPromise<BindResult> bindAsync(BindRequest request,
                                  IntermediateResponseHandler intermediateResponseHandler)

Asynchronously authenticates to the Directory Server using the provided bind request.

Parameters:

request - The bind request.

intermediateResponseHandler - An intermediate response handler which can be used to process any intermediate responses as they are received, may be null.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support bind operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

close

void close()

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 close on a connection that is already closed has no effect.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

See Also:

Connections.uncloseable(Connection)

close

void close(UnbindRequest request,
           String reason)

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 close on a connection that is already closed has no effect.

Parameters:

request - The unbind request to use in the case where a physical connection is closed.

reason - A reason describing why the connection was closed.

Throws:

NullPointerException - If request was null.

compare

CompareResult compare(CompareRequest request)
               throws LdapException

Compares an entry in the Directory Server using the provided compare request.

Parameters:

request - The compare request.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support compare operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

compare

CompareResult compare(String name,
                      String attributeDescription,
                      String assertionValue)
               throws LdapException

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);
 

Parameters:

name - The distinguished name of the entry to be compared.

attributeDescription - The name of the attribute to be compared.

assertionValue - The assertion value to be compared.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

LocalizedIllegalArgumentException - If name or AttributeDescription could not be decoded using the default schema.

UnsupportedOperationException - If this connection does not support compare operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If name, attributeDescription, or assertionValue was null.

compareAsync

LdapPromise<CompareResult> compareAsync(CompareRequest request)

Asynchronously compares an entry in the Directory Server using the provided compare request.

Parameters:

request - The compare request.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support compare operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

compareAsync

LdapPromise<CompareResult> compareAsync(CompareRequest request,
                                        IntermediateResponseHandler intermediateResponseHandler)

Asynchronously compares an entry in the Directory Server using the provided compare request.

Parameters:

request - The compare request.

intermediateResponseHandler - An intermediate response handler which can be used to process any intermediate responses as they are received, may be null.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support compare operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

delete

Result delete(DeleteRequest request)
       throws LdapException

Deletes an entry from the Directory Server using the provided delete request.

Parameters:

request - The delete request.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support delete operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

delete

default Result delete(Dn name)
               throws LdapException

Deletes the named entry from the Directory Server.

This method is equivalent to the following code:

 DeleteRequest request = new DeleteRequest(name);
 connection.delete(request);
 

Parameters:

name - The distinguished name of the entry to be deleted.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

LocalizedIllegalArgumentException - If name could not be decoded using the default schema.

UnsupportedOperationException - If this connection does not support delete operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If name was null.

delete

Result delete(String name)
       throws LdapException

Deletes the named entry from the Directory Server.

This method is equivalent to the following code:

 DeleteRequest request = new DeleteRequest(name);
 connection.delete(request);
 

Parameters:

name - The distinguished name of the entry to be deleted.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

LocalizedIllegalArgumentException - If name could not be decoded using the default schema.

UnsupportedOperationException - If this connection does not support delete operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If name was null.

deleteSubtree

Result deleteSubtree(String name)
              throws LdapException

Deletes the named entry and all of its subordinates from the Directory Server.

This method is equivalent to the following code:

 DeleteRequest request = new DeleteRequest(name).addControl(
 connection.delete(request);
 

Parameters:

name - The distinguished name of the subtree base entry to be deleted.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

LocalizedIllegalArgumentException - If name could not be decoded using the default schema.

UnsupportedOperationException - If this connection does not support delete operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If name was null.

deleteAsync

LdapPromise<Result> deleteAsync(DeleteRequest request)

Asynchronously deletes an entry from the Directory Server using the provided delete request.

Parameters:

request - The delete request.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support delete operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

deleteAsync

LdapPromise<Result> deleteAsync(DeleteRequest request,
                                IntermediateResponseHandler intermediateResponseHandler)

Asynchronously deletes an entry from the Directory Server using the provided delete request.

Parameters:

request - The delete request.

intermediateResponseHandler - An intermediate response handler which can be used to process any intermediate responses as they are received, may be null.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support delete operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

extendedRequest

<R extends ExtendedResult> R extendedRequest(ExtendedRequest<R> request)
                                      throws LdapException

Requests that the Directory Server performs the provided extended request.

Type Parameters:

R - The type of result returned by the extended request.

Parameters:

request - The extended request.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support extended operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

extendedRequest

<R extends ExtendedResult> R extendedRequest(ExtendedRequest<R> request,
                                             IntermediateResponseHandler handler)
                                      throws LdapException

Requests that the Directory Server performs the provided extended request, optionally listening for any intermediate responses.

Type Parameters:

R - The type of result returned by the extended request.

Parameters:

request - The extended request.

handler - An intermediate response handler which can be used to process any intermediate responses as they are received, may be null.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support extended operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

extendedRequest

GenericExtendedResult extendedRequest(String requestName,
                                      ByteString requestValue)
                               throws LdapException

Requests that the Directory Server performs the provided extended request.

This method is equivalent to the following code:

 GenericExtendedRequest request = new GenericExtendedRequest(requestName, requestValue);
 connection.extendedRequest(request);
 

Parameters:

requestName - The dotted-decimal representation of the unique OID corresponding to the extended request.

requestValue - The content of the extended request in a form defined by the extended operation, or null if there is no content.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support extended operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If requestName was null.

extendedRequestAsync

<R extends ExtendedResult> LdapPromise<R> extendedRequestAsync(ExtendedRequest<R> request)

Asynchronously performs the provided extended request in the Directory Server.

Type Parameters:

R - The type of result returned by the extended request.

Parameters:

request - The extended request.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support extended operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

extendedRequestAsync

<R extends ExtendedResult> LdapPromise<R> extendedRequestAsync(ExtendedRequest<R> request,
                                                               IntermediateResponseHandler intermediateResponseHandler)

Asynchronously performs the provided extended request in the Directory Server.

Type Parameters:

R - The type of result returned by the extended request.

Parameters:

request - The extended request.

intermediateResponseHandler - An intermediate response handler which can be used to process any intermediate responses as they are received, may be null.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support extended operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

isClosed

boolean isClosed()

Indicates whether this connection has been explicitly closed by calling close. This method will not return true if a fatal error has occurred on the connection unless close has been called.

Returns:

true if this connection has been explicitly closed by calling close, or false otherwise.

isValid

boolean isValid()

Returns true if this connection has not been closed and no fatal errors have been detected. This method is guaranteed to return false only when it is called after the method close has been called.

Returns:

true if this connection is valid, false otherwise.

modify

Result modify(ModifyRequest request)
       throws LdapException

Modifies an entry in the Directory Server using the provided modify request.

Parameters:

request - The modify request.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support modify operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

modify

Result modify(String... ldifLines)
       throws LdapException

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);
 

Parameters:

ldifLines - Lines of LDIF containing the a single LDIF modify change record.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support modify operations.

LocalizedIllegalArgumentException - If ldifLines was empty, or contained invalid LDIF, or could not be decoded using the default schema.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If ldifLines was null .

modifyAsync

LdapPromise<Result> modifyAsync(ModifyRequest request)

Asynchronously modifies an entry in the Directory Server using the provided modify request.

Parameters:

request - The modify request.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support modify operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

modifyAsync

LdapPromise<Result> modifyAsync(ModifyRequest request,
                                IntermediateResponseHandler intermediateResponseHandler)

Asynchronously modifies an entry in the Directory Server using the provided modify request.

Parameters:

request - The modify request.

intermediateResponseHandler - An intermediate response handler which can be used to process any intermediate responses as they are received, may be null.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support modify operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

modifyDn

Result modifyDn(ModifyDnRequest request)
         throws LdapException

Renames an entry in the Directory Server using the provided modify DN request.

Parameters:

request - The modify DN request.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support modify DN operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

modifyDn

Result modifyDn(String name,
                String newRDN)
         throws LdapException

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);
 

Parameters:

name - The distinguished name of the entry to be renamed.

newRDN - The new RDN of the entry.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

LocalizedIllegalArgumentException - If name or newRDN could not be decoded using the default schema.

UnsupportedOperationException - If this connection does not support modify DN operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If name or newRDN was null.

modifyDnAsync

LdapPromise<Result> modifyDnAsync(ModifyDnRequest request)

Asynchronously renames an entry in the Directory Server using the provided modify DN request.

Parameters:

request - The modify DN request.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support modify DN operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

modifyDnAsync

LdapPromise<Result> modifyDnAsync(ModifyDnRequest request,
                                  IntermediateResponseHandler intermediateResponseHandler)

Asynchronously renames an entry in the Directory Server using the provided modify DN request.

Parameters:

request - The modify DN request.

intermediateResponseHandler - An intermediate response handler which can be used to process any intermediate responses as they are received, may be null.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support modify DN operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

readEntry

SearchResultEntry readEntry(Dn name,
                            String... attributeDescriptions)
                     throws LdapException

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 EntryNotFoundException. More specifically, this method will never return null.

This method is equivalent to the following code:

 SearchRequest request = new SearchRequest(name, SearchScope.BASE_OBJECT,
 "(objectClass=*)", attributeDescriptions);
 connection.searchSingleEntry(request);
 

Parameters:

name - The distinguished name of the entry to be read.

attributeDescriptions - The names of the attributes to be included with the entry, which may be null or empty indicating that all user attributes should be returned.

Returns:

The single search result entry returned from the search.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If the name was null.

readEntry

SearchResultEntry readEntry(String name,
                            String... attributeDescriptions)
                     throws LdapException

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 EntryNotFoundException. More specifically, this method will never return null.

This method is equivalent to the following code:

 SearchRequest request =
         new SearchRequest(name, SearchScope.BASE_OBJECT, "(objectClass=*)", attributeDescriptions);
 connection.searchSingleEntry(request);
 

Parameters:

name - The distinguished name of the entry to be read.

attributeDescriptions - The names of the attributes to be included with the entry.

Returns:

The single search result entry returned from the search.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

LocalizedIllegalArgumentException - If baseObject could not be decoded using the default schema.

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If the name was null.

readEntryAsync

LdapPromise<SearchResultEntry> readEntryAsync(Dn name,
                                              Collection<String> attributeDescriptions)

Asynchronously 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 EntryNotFoundException. More specifically, the returned promise will never return null.

This method is equivalent to the following code:

 SearchRequest request =
         new SearchRequest(name, SearchScope.BASE_OBJECT, "(objectClass=*)", attributeDescriptions);
 connection.searchSingleEntryAsync(request, resultHandler, p);
 

Parameters:

name - The distinguished name of the entry to be read.

attributeDescriptions - The names of the attributes to be included with the entry, which may be null or empty indicating that all user attributes should be returned.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If the name was null.

removeConnectionEventListener

void removeConnectionEventListener(ConnectionEventListener listener)

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.

Parameters:

listener - The listener which no longer wants to be notified when events occur on this connection.

Throws:

NullPointerException - If the listener was null.

search

ConnectionEntryReader search(SearchRequest request)

Searches the Directory Server using the provided search parameters. Any matching entries returned by the search will be exposed through the returned ConnectionEntryReader.

Unless otherwise specified, calling this method is equivalent to:

 ConnectionEntryReader reader = new ConnectionEntryReader(this, request);
 

Parameters:

request - The search request.

Returns:

The result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request or entries was null.

search

Result search(SearchRequest request,
              Collection<? super SearchResultEntry> entries)
       throws LdapException

Searches the Directory Server using the provided search request. Any matching entries returned by the search will be added to 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 OutOfMemoryError.

This method is equivalent to the following code:

 connection.search(request, entries, null);
 

Parameters:

request - The search request.

entries - The collection to which matching entries should be added.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request or entries was null.

search

Result search(SearchRequest request,
              Collection<? super SearchResultEntry> entries,
              Collection<? super SearchResultReference> references)
       throws LdapException

Searches the Directory Server using the provided search request. Any matching entries returned by the search will be added to entries, even if the final search result indicates that the search failed. Similarly, search result references returned by the search will be added to 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 OutOfMemoryError.

Parameters:

request - The search request.

entries - The collection to which matching entries should be added.

references - The collection to which search result references should be added, or null if references are to be discarded.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request or entries was null.

search

Result search(SearchRequest request,
              SearchResultHandler handler)
       throws LdapException

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.

Parameters:

request - The search request.

handler - A search result handler which can be used to process the search result entries and references as they are received, may be null.

Returns:

The result of the operation.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

search

ConnectionEntryReader search(String baseObject,
                             SearchScope scope,
                             String filter,
                             String... attributeDescriptions)

Searches the Directory Server using the provided search parameters. Any matching entries returned by the search will be exposed through the 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:

 SearchRequest request = new SearchRequest(baseDN, scope, filter, attributeDescriptions);
 connection.search(request, new LinkedBlockingQueue<Response>());
 

Parameters:

baseObject - The distinguished name of the base entry relative to which the search is to be performed.

scope - The scope of the search.

filter - The filter that defines the conditions that must be fulfilled in order for an entry to be returned.

attributeDescriptions - The names of the attributes to be included with each entry.

Returns:

An entry reader exposing the returned entries.

Throws:

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If the baseObject, scope, or filter were null.

searchAsync

LdapPromise<Result> searchAsync(SearchRequest request,
                                SearchResultHandler entryHandler)

Asynchronously searches the Directory Server using the provided search request.

Parameters:

request - The search request.

entryHandler - A search result handler which can be used to asynchronously process the search result entries and references as they are received, may be null.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

searchAsync

LdapPromise<Result> searchAsync(SearchRequest request,
                                IntermediateResponseHandler intermediateResponseHandler,
                                SearchResultHandler entryHandler)

Asynchronously searches the Directory Server using the provided search request.

Parameters:

request - The search request.

intermediateResponseHandler - An intermediate response handler which can be used to process any intermediate responses as they are received, may be null.

entryHandler - A search result handler which can be used to asynchronously process the search result entries and references as they are received, may be null.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If request was null.

searchSingleEntry

SearchResultEntry searchSingleEntry(SearchRequest request)
                             throws LdapException

Searches the Directory Server for a single entry using the provided search request.

If the requested entry is not returned by the Directory Server then the request will fail with an EntryNotFoundException. More specifically, this method will never return null. If multiple matching entries are returned by the Directory Server then the request will fail with an MultipleEntriesFoundException.

Parameters:

request - The search request.

Returns:

The single search result entry returned from the search.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If the request was null.

searchSingleEntry

SearchResultEntry searchSingleEntry(String baseObject,
                                    SearchScope scope,
                                    String filter,
                                    String... attributeDescriptions)
                             throws LdapException

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 EntryNotFoundException. More specifically, this method will never return null. If multiple matching entries are returned by the Directory Server then the request will fail with an MultipleEntriesFoundException.

This method is equivalent to the following code:

 SearchRequest request = new SearchRequest(baseObject, scope, filter, attributeDescriptions);
 connection.searchSingleEntry(request);
 

Parameters:

baseObject - The distinguished name of the base entry relative to which the search is to be performed.

scope - The scope of the search.

filter - The filter that defines the conditions that must be fulfilled in order for an entry to be returned.

attributeDescriptions - The names of the attributes to be included with each entry.

Returns:

The single search result entry returned from the search.

Throws:

LdapException - If the result code indicates that the request failed for some reason.

LocalizedIllegalArgumentException - If baseObject could not be decoded using the default schema or if filter is not a valid LDAP string representation of a filter.

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If the baseObject, scope, or filter were null.

searchSingleEntryAsync

LdapPromise<SearchResultEntry> searchSingleEntryAsync(SearchRequest request)

Asynchronously searches the Directory Server for a single entry using the provided search request.

If the requested entry is not returned by the Directory Server then the request will fail with an EntryNotFoundException. More specifically, the returned promise will never return null. If multiple matching entries are returned by the Directory Server then the request will fail with an MultipleEntriesFoundException.

Parameters:

request - The search request.

Returns:

A promise representing the result of the operation.

Throws:

UnsupportedOperationException - If this connection does not support search operations.

IllegalStateException - If this connection has already been closed, i.e. if isClosed() == true.

NullPointerException - If the request was null.