This class provides a facility for interacting with an LDAPv3 directory
server. It provides a means of establishing a connection to the server,
sending requests, and reading responses. See
RFC 4511 for the LDAPv3
protocol specification and more information about the types of operations
defined in LDAP.
Creating, Establishing, and Authenticating Connections
An LDAP connection can be established either at the time that the object is
created or as a separate step. Similarly, authentication can be performed on
the connection at the time it is created, at the time it is established, or
as a separate process. For example:
// Create a new, unestablished connection. Then connect and perform a
// simple bind as separate operations.
LDAPConnection c = new LDAPConnection();
c.connect(address, port);
BindResult bindResult = c.bind(bindDN, password);
// Create a new connection that is established at creation time, and then
// authenticate separately using simple authentication.
LDAPConnection c = new LDAPConnection(address, port);
BindResult bindResult = c.bind(bindDN, password);
// Create a new connection that is established and bound using simple
// authentication all in one step.
LDAPConnection c = new LDAPConnection(address, port, bindDN, password);
When authentication is performed at the time that the connection is
established, it is only possible to perform a simple bind and it is not
possible to include controls in the bind request, nor is it possible to
receive response controls if the bind was successful. Therefore, it is
recommended that authentication be performed as a separate step if the server
may return response controls even in the event of a successful authentication
(e.g., a control that may indicate that the user's password will soon
expire). See the
BindRequest class for more information about
authentication in the UnboundID LDAP SDK for Java.
By default, connections will use standard unencrypted network sockets.
However, it may be desirable to create connections that use SSL/TLS to
encrypt communication. This can be done by specifying a
javax.net.SocketFactory that should be used to create the socket to
use to communicate with the directory server. The
javax.net.ssl.SSLSocketFactory#getDefault method or the
javax.net.ssl.SSLContext#getSocketFactory method may be used to
obtain a socket factory for performing SSL communication. See the
JSSE Reference Guide for more information on using these classes.
Alternately, you may use the
com.unboundid.util.ssl.SSLUtil class to
simplify the process.
Whenever the connection is no longer needed, it may be terminated using the
LDAPConnection#close method.
Processing LDAP Operations
This class provides a number of methods for processing the different types of
operations. The types of operations that can be processed include:
- Abandon -- This may be used to request that the server stop processing
on an operation that has been invoked asynchronously.
- Add -- This may be used to add a new entry to the directory
server. See the
AddRequest class for more information about
processing add operations.
- Bind -- This may be used to authenticate to the directory server. See
the
BindRequest class for more information about processing
bind operations.
- Compare -- This may be used to determine whether a specified entry has
a given attribute value. See the
CompareRequest class for more
information about processing compare operations.
- Delete -- This may be used to remove an entry from the directory
server. See the
DeleteRequest class for more information about
processing delete operations.
- Extended -- This may be used to process an operation which is not
part of the core LDAP protocol but is a custom extension supported by
the directory server. See the
ExtendedRequest class for more
information about processing extended operations.
- Modify -- This may be used to alter an entry in the directory
server. See the
ModifyRequest class for more information about
processing modify operations.
- Modify DN -- This may be used to rename an entry or subtree and/or move
that entry or subtree below a new parent in the directory server. See
the
ModifyDNRequest class for more information about processing
modify DN operations.
- Search -- This may be used to retrieve a set of entries in the server
that match a given set of criteria. See the
SearchRequestclass for more information about processing search operations.
Most of the methods in this class used to process operations operate in a
synchronous manner. In these cases, the SDK will send a request to the
server and wait for a response to arrive before returning to the caller. In
these cases, the value returned will include the contents of that response,
including the result code, diagnostic message, matched DN, referral URLs, and
any controls that may have been included. However, it also possible to
process operations asynchronously, in which case the SDK will return control
back to the caller after the request has been sent to the server but before
the response has been received. In this case, the SDK will return an
AsyncRequestID object which may be used to later abandon or cancel
that operation if necessary, and will notify the client when the response
arrives via a listener interface.
This class is mostly threadsafe. It is possible to process multiple
concurrent operations over the same connection as long as the methods being
invoked will not change the state of the connection in a way that might
impact other operations in progress in unexpected ways. In particular, the
following should not be attempted while any other operations may be in
progress on this connection:
-
Using one of the
connect methods to re-establish the connection.
-
Using one of the
close methods to terminate the connection.
-
Using one of the
bind methods to attempt to authenticate the
connection (unless you are certain that the bind will not impact the
identity of the associated connection, for example by including the
retain identity request control in the bind request if using the
Commercial Edition of the LDAP SDK in conjunction with a Ping Identity,
UnboundID, or Alcatel-Lucent 8661 Directory Server).
-
Attempting to make a change to the way that the underlying communication
is processed (e.g., by using the StartTLS extended operation to convert
an insecure connection into a secure one).