Package org.forgerock.opendj.ldap

Interface LdapClientSocket

All Superinterfaces:

AutoCloseable, Closeable

public interface LdapClientSocket
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 are performed asynchronously once the Flowable has been subscribed to. As as result, send(Request, RequestHandle) will send the request only once the returned Flowable has been subscribed.

Cancellation

Request cancellation can be done in different ways:

• Using the standard reactive-stream way: Using the Subscription the Subscriber received upon its subscription to the response, it's possible to invoke Subscription.cancel(). This will send an AbandonRequest to the server.
• Another way is to use the RequestHandle.abandon() or RequestHandle.cancel() to respectively send an AbandonRequest or a CancelExtendedRequest.

See Also:

LdapClient.connect()

Method Summary

Modifier and Type	Method	Description
default Single<Result>	add(AddRequest request)	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.
default Single<Result>	applyChange(ChangeRecord request)	Applies the provided change request to the Directory Server.
default Single<BindResult>	bind(BindRequest request)	Authenticates to the Directory Server using the provided bind request.
default void	close()	Releases any resources associated with this connection.
void	close(UnbindRequest request, String reason)	Releases any resources associated with this connection.
default Single<CompareResult>	compare(CompareRequest request)	Asynchronously compares an entry in the Directory Server using the provided compare request.
default Single<Result>	delete(DeleteRequest request)	Deletes an entry from the Directory Server using the provided delete request.
default <R extends ExtendedResult> Single<R>	extendedRequest(ExtendedRequest<R> request)	Requests that the Directory Server performs the provided extended request.
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.
default Single<Result>	modify(ModifyRequest request)	Modifies an entry in the Directory Server using the provided modify request.
default Single<Result>	modifyDn(ModifyDnRequest request)	Renames an entry in the Directory Server using the provided modify DN request.
default Single<SearchResultEntry>	readEntry(Dn name, String... attributeDescriptions)	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.
default Flowable<SearchResultEntry>	search(SearchRequest request)	Searches the Directory Server using the provided search request.
default Single<SearchResultEntry>	searchSingleEntry(SearchRequest request)	Searches the Directory Server for a single entry using the provided search request.
default Flowable<Response>	send(Request request)	Sends a request to the Directory Server.
Flowable<Response>	send(Request request, RequestHandle handle)	Sends a request to the Directory Server.

Method Detail

send

Flowable<Response> send(Request request,
                        RequestHandle handle)

Sends a request to the Directory Server.

Note that the request will only be sent when the returned Flowable has been subscribed.

Parameters:

request - The request to send.

handle - The RequestHandle to track the request cancellation.

Returns:

The asynchronous result of the operation. Note that this Flowable can be subscribed only once. Canceling the subscription of this Flowable will send an AbandonRequest to the server.

Throws:

NullPointerException - If request or handle was null.

See Also:

Flowable, RequestHandle

send

default Flowable<Response> send(Request request)

Sends a request to the Directory Server.

Note that the request will only be sent when the returned Flowable has been subscribed.

Parameters:

request - The request to send.

Returns:

The asynchronous result of the operation. Note that this Flowable can be subscribed only once. Canceling the subscription of this Flowable will send an AbandonRequest to the server.

Throws:

NullPointerException - If request was null.

See Also:

Flowable

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.

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.

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.

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.

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.

This method is not blocking and as such, does not guarantee that the socket is being effectively closed when this method returns.

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.

close

default 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, null);
 

Calling this method on a connection that is already closed has no effect.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

bind

default Single<BindResult> bind(BindRequest request)

Authenticates to the Directory Server using the provided bind request.

If you need to handle IntermediateResponses, please use send(Request) instead.

Note that the request will only be sent when the returned Single has been subscribed.

Parameters:

request - The bind request.

Returns:

The asynchronous result of the operation. Note that this Single can be subscribed only once. Canceling the subscription of this Single will send an AbandonRequest to the server.

Throws:

UnsupportedOperationException - If this socket does not support bind operations.

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

NullPointerException - If request was null.

See Also:

Single

searchSingleEntry

default Single<SearchResultEntry> searchSingleEntry(SearchRequest request)

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. If multiple matching entries are returned by the Directory Server then the request will fail with an MultipleEntriesFoundException.

Note that the request will only be sent when the returned Single has been subscribed.

Parameters:

request - The request to send.

Returns:

The asynchronous result of the operation. Note that this Single can be subscribed only once. Canceling the subscription of this Single will send an AbandonRequest to the server.

Throws:

UnsupportedOperationException - If this connection does not support search operations.

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

NullPointerException - If the request was null.

See Also:

Single

search

default Flowable<SearchResultEntry> search(SearchRequest request)

Searches the Directory Server using the provided search request. Note that only SearchResultEntry will be returned throughout the Flowable.

If you need to handle the search Result (e.g. for processing paged results), SearchResultReference, or SearchResultReference or IntermediateResponses, please use send(Request) instead.

Note that the request will only be sent when the returned Flowable has been subscribed.

Parameters:

request - The request to send.

Returns:

The asynchronous result of the operation. Note that this Flowable can be subscribed only once. Canceling the subscription of this Flowable will send an AbandonRequest to the server.

Throws:

UnsupportedOperationException - If this connection does not support search operations.

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

NullPointerException - If the request was null.

See Also:

Flowable

readEntry

default Single<SearchResultEntry> readEntry(Dn name,
                                            String... attributeDescriptions)

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.

This method is equivalent to the following code:

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

Note that the request will only be sent when the returned Single has been subscribed.

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 asynchronous result of the operation. Note that this Single can be subscribed only once. Canceling the subscription of this Single will send an AbandonRequest to the server.

Throws:

UnsupportedOperationException - If this socket does not support search operations.

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

NullPointerException - If the name was null.

modify

default Single<Result> modify(ModifyRequest request)

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

If you need to handle IntermediateResponses, please use send(Request) instead.

Note that the request will only be sent when the returned Single has been subscribed.

Parameters:

request - The modify request.

Returns:

The asynchronous result of the operation. Note that this Single can be subscribed only once. Canceling the subscription of this Single will send an AbandonRequest to the server.

Throws:

UnsupportedOperationException - If this connection does not support modify operations.

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

NullPointerException - If request was null.

See Also:

Single

add

default Single<Result> add(AddRequest request)

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

If you need to handle IntermediateResponses, please use send(Request) instead.

Note that the request will only be sent when the returned Single has been subscribed.

Parameters:

request - The add request.

Returns:

The asynchronous result of the operation. Note that this Single can be subscribed only once. Canceling the subscription of this Single will send an AbandonRequest to the server.

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.

See Also:

Single

modifyDn

default Single<Result> modifyDn(ModifyDnRequest request)

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

If you need to handle IntermediateResponses, please use send(Request) instead.

Note that the request will only be sent when the returned Single has been subscribed.

Parameters:

request - The modify DN request.

Returns:

The asynchronous result of the operation. Note that this Single can be subscribed only once. Canceling the subscription of this Single will send an AbandonRequest to the server.

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.

See Also:

Single

delete

default Single<Result> delete(DeleteRequest request)

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

If you need to handle IntermediateResponses, please use send(Request) instead.

Note that the request will only be sent when the returned Single has been subscribed.

Parameters:

request - The delete request.

Returns:

The asynchronous result of the operation. Note that this Single can be subscribed only once. Canceling the subscription of this Single will send an AbandonRequest to the server.

Throws:

UnsupportedOperationException - If this connection does not support delete operations.

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

NullPointerException - If request was null.

See Also:

Single

compare

default Single<CompareResult> compare(CompareRequest request)

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

If you need to handle IntermediateResponses, please use send(Request) instead.

Note that the request will only be sent when the returned Single has been subscribed.

Parameters:

request - The compare request.

Returns:

The asynchronous result of the operation. Note that this Single can be subscribed only once. Canceling the subscription of this Single will send an AbandonRequest to the server.

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.

See Also:

Single

extendedRequest

default <R extends ExtendedResult> Single<R> extendedRequest(ExtendedRequest<R> request)

Requests that the Directory Server performs the provided extended request.

If you need to handle IntermediateResponses, please use send(Request) instead.

Note that the request will only be sent when the returned Single has been subscribed.

Type Parameters:

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

Parameters:

request - The extended request.

Returns:

The asynchronous result of the operation. Note that this Single can be subscribed only once. Canceling the subscription of this Single will send an AbandonRequest to the server.

Throws:

UnsupportedOperationException - If this socket does not support extended operations.

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

NullPointerException - If request was null.

See Also:

Single

applyChange

default Single<Result> applyChange(ChangeRecord request)

Applies the provided change request to the Directory Server.

If you need to handle IntermediateResponses, please use send(Request) instead.

Note that the request will only be sent when the returned Single has been subscribed.

Parameters:

request - The change request.

Returns:

The asynchronous result of the operation. Note that this Single can be subscribed only once. Canceling the subscription of this Single will send an AbandonRequest to the server.

Throws:

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

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

NullPointerException - If request was null.

See Also:

Single