Package com.unboundid.ldap.sdk.migrate.ldapjdk

Class LDAPConnection

java.lang.Object
com.unboundid.ldap.sdk.migrate.ldapjdk.LDAPConnection
@Mutable @NotExtensible @ThreadSafety(level=NOT_THREADSAFE) public class LDAPConnection extends Object
This class provides an object that may be used to communicate with an LDAP directory server.

This class is primarily intended to be used in the process of updating applications which use the Netscape Directory SDK for Java to switch to or coexist with the UnboundID LDAP SDK for Java. For applications not written using the Netscape Directory SDK for Java, the LDAPConnection class should be used instead.

  • Field Details

    • DEREF_NEVER

      public static final int DEREF_NEVER
      The integer value for the DEREF_NEVER dereference policy.

    • DEREF_SEARCHING

      public static final int DEREF_SEARCHING
      The integer value for the DEREF_SEARCHING dereference policy.

    • DEREF_FINDING

      public static final int DEREF_FINDING
      The integer value for the DEREF_FINDING dereference policy.

    • DEREF_ALWAYS

      public static final int DEREF_ALWAYS
      The integer value for the DEREF_ALWAYS dereference policy.

    • SCOPE_BASE

      public static final int SCOPE_BASE
      The integer value for the SCOPE_BASE search scope.
      See Also:

    • SCOPE_ONE

      public static final int SCOPE_ONE
      The integer value for the SCOPE_ONE search scope.
      See Also:

    • SCOPE_SUB

      public static final int SCOPE_SUB
      The integer value for the SCOPE_SUB search scope.
      See Also:

  • Constructor Details

    • LDAPConnection

      public LDAPConnection()
      Creates a new LDAP connection which will use the default socket factory.

    • LDAPConnection

      public LDAPConnection(@Nullable LDAPSocketFactory socketFactory)
      Creates a new LDAP connection which will use the provided socket factory.
      Parameters:
      socketFactory - The socket factory to use when creating the socket to use for communicating with the server.

  • Method Details

    • finalize

      protected void finalize() throws Throwable
      Closes the connection to the server if the client forgets to do so.
      Overrides:
      finalize in class Object
      Throws:
      Throwable - If a problem occurs.

    • getSDKConnection

      @NotNull public LDAPConnection getSDKConnection()
      Retrieves the LDAPConnection object used to back this connection.
      Returns:
      The com.unboundid.ldap.sdk.LDAPConnection object used to back this connection.

    • getHost

      @Nullable public String getHost()
      Retrieves the address to which the connection is established.
      Returns:
      The address to which the connection is established.

    • getPort

      public int getPort()
      Retrieves the port to which the connection is established.
      Returns:
      The port to which the connection is established.

    • getAuthenticationDN

      @Nullable public String getAuthenticationDN()
      Retrieves the DN of the user that last authenticated on this connection.
      Returns:
      The DN of the user that last authenticated on this connection, or null if it is not available.

    • getAuthenticationPassword

      @Nullable public String getAuthenticationPassword()
      Retrieves the password of the user that last authenticated on this connection.
      Returns:
      The password of the user that last authenticated on this connection, or null if it is not available.

    • getConnectTimeout

      public int getConnectTimeout()
      Retrieves the maximum length of time to wait for the connection to be established, in seconds.
      Returns:
      The maximum length of time to wait for the connection to be established.

    • setConnectTimeout

      public void setConnectTimeout(int timeout)
      Specifies the maximum length of time to wait for the connection to be established, in seconds.
      Parameters:
      timeout - The maximum length of time to wait for the connection to be established.

    • getSocketFactory

      @Nullable public LDAPSocketFactory getSocketFactory()
      Retrieves the socket factory for this LDAP connection, if specified.
      Returns:
      The socket factory for this LDAP connection, or null if none has been provided.

    • setSocketFactory

      public void setSocketFactory(@Nullable LDAPSocketFactory socketFactory)
      Sets the socket factory for this LDAP connection.
      Parameters:
      socketFactory - The socket factory for this LDAP connection.

    • getConstraints

      @NotNull public LDAPConstraints getConstraints()
      Retrieves the constraints for this connection.
      Returns:
      The constraints for this connection.

    • setConstraints

      public void setConstraints(@Nullable LDAPConstraints constraints)
      Updates the constraints for this connection.
      Parameters:
      constraints - The constraints for this connection.

    • getSearchConstraints

      @NotNull public LDAPSearchConstraints getSearchConstraints()
      Retrieves the search constraints for this connection.
      Returns:
      The search constraints for this connection.

    • setSearchConstraints

      public void setSearchConstraints(@Nullable LDAPSearchConstraints searchConstraints)
      Updates the search constraints for this connection.
      Parameters:
      searchConstraints - The search constraints for this connection.

    • getResponseControls

      @Nullable public LDAPControl[] getResponseControls()
      Retrieves the response controls from the last operation processed on this connection.
      Returns:
      The response controls from the last operation processed on this connection, or null if there were none.

    • isConnected

      public boolean isConnected()
      Indicates whether this connection is currently established.
      Returns:
      true if this connection is currently established, or false if not.

    • connect

      public void connect(@NotNull String host, int port) throws LDAPException
      Attempts to establish this connection with the provided information.
      Parameters:
      host - The address of the server to which the connection should be established.
      port - The port of the server to which the connection should be established.
      Throws:
      LDAPException - If a problem occurs while attempting to establish this connection.

    • connect

      public void connect(@NotNull String host, int port, @Nullable String dn, @Nullable String password) throws LDAPException
      Attempts to establish and authenticate this connection with the provided information.
      Parameters:
      host - The address of the server to which the connection should be established.
      port - The port of the server to which the connection should be established.
      dn - The DN to use to bind to the server.
      password - The password to use to bind to the server.
      Throws:
      LDAPException - If a problem occurs while attempting to establish or authenticate this connection. If an exception is thrown, then the connection will not be established.

    • connect

      public void connect(@NotNull String host, int port, @Nullable String dn, @Nullable String password, @Nullable LDAPConstraints constraints) throws LDAPException
      Attempts to establish and authenticate this connection with the provided information.
      Parameters:
      host - The address of the server to which the connection should be established.
      port - The port of the server to which the connection should be established.
      dn - The DN to use to bind to the server.
      password - The password to use to bind to the server.
      constraints - The constraints to use when processing the bind.
      Throws:
      LDAPException - If a problem occurs while attempting to establish or authenticate this connection. If an exception is thrown, then the connection will not be established.

    • connect

      public void connect(int version, @NotNull String host, int port, @Nullable String dn, @Nullable String password) throws LDAPException
      Attempts to establish and authenticate this connection with the provided information.
      Parameters:
      version - The LDAP protocol version to use for the connection. This will be ignored, since this implementation only supports LDAPv3.
      host - The address of the server to which the connection should be established.
      port - The port of the server to which the connection should be established.
      dn - The DN to use to bind to the server.
      password - The password to use to bind to the server.
      Throws:
      LDAPException - If a problem occurs while attempting to establish or authenticate this connection. If an exception is thrown, then the connection will not be established.

    • connect

      public void connect(int version, @NotNull String host, int port, @Nullable String dn, @Nullable String password, @Nullable LDAPConstraints constraints) throws LDAPException
      Attempts to establish and authenticate this connection with the provided information.
      Parameters:
      version - The LDAP protocol version to use for the connection. This will be ignored, since this implementation only supports LDAPv3.
      host - The address of the server to which the connection should be established.
      port - The port of the server to which the connection should be established.
      dn - The DN to use to bind to the server.
      password - The password to use to bind to the server.
      constraints - The constraints to use when processing the bind.
      Throws:
      LDAPException - If a problem occurs while attempting to establish or authenticate this connection. If an exception is thrown, then the connection will not be established.

    • disconnect

      public void disconnect() throws LDAPException
      Unbinds and disconnects from the directory server.
      Throws:
      LDAPException - If a problem occurs.

    • reconnect

      public void reconnect() throws LDAPException
      Disconnects from the directory server and attempts to re-connect and re-authenticate.
      Throws:
      LDAPException - If a problem occurs. If an exception is thrown, the connection will have been closed.

    • abandon

      public void abandon(int id) throws LDAPException
      Sends a request to abandon the request with the specified message ID.
      Parameters:
      id - The message ID of the operation to abandon.
      Throws:
      LDAPException - If a problem occurs while sending the request.

    • abandon

      public void abandon(@NotNull LDAPSearchResults searchResults) throws LDAPException
      Sends a request to abandon the provided search operation.
      Parameters:
      searchResults - The search results object for the search to abandon.
      Throws:
      LDAPException - If a problem occurs while sending the request.

    • add

      public void add(@NotNull LDAPEntry entry) throws LDAPException
      Adds the provided entry to the directory.
      Parameters:
      entry - The entry to be added.
      Throws:
      LDAPException - If a problem occurs while adding the entry.

    • add

      public void add(@NotNull LDAPEntry entry, @Nullable LDAPConstraints constraints) throws LDAPException
      Adds the provided entry to the directory.
      Parameters:
      entry - The entry to be added.
      constraints - The constraints to use for the add operation.
      Throws:
      LDAPException - If a problem occurs while adding the entry.

    • authenticate

      public void authenticate(@Nullable String dn, @Nullable String password) throws LDAPException
      Authenticates to the directory server using a simple bind with the provided information.
      Parameters:
      dn - The DN of the user for the bind.
      password - The password to use for the bind.
      Throws:
      LDAPException - If the bind attempt fails.

    • authenticate

      public void authenticate(@Nullable String dn, @Nullable String password, @Nullable LDAPConstraints constraints) throws LDAPException
      Authenticates to the directory server using a simple bind with the provided information.
      Parameters:
      dn - The DN of the user for the bind.
      password - The password to use for the bind.
      constraints - The constraints to use for the bind operation.
      Throws:
      LDAPException - If the bind attempt fails.

    • authenticate

      public void authenticate(int version, @Nullable String dn, @Nullable String password) throws LDAPException
      Authenticates to the directory server using a simple bind with the provided information.
      Parameters:
      version - The LDAP protocol version to use. This will be ignored, since this implementation only supports LDAPv3.
      dn - The DN of the user for the bind.
      password - The password to use for the bind.
      Throws:
      LDAPException - If the bind attempt fails.

    • authenticate

      public void authenticate(int version, @Nullable String dn, @Nullable String password, @Nullable LDAPConstraints constraints) throws LDAPException
      Authenticates to the directory server using a simple bind with the provided information.
      Parameters:
      version - The LDAP protocol version to use. This will be ignored, since this implementation only supports LDAPv3.
      dn - The DN of the user for the bind.
      password - The password to use for the bind.
      constraints - The constraints to use for the bind operation.
      Throws:
      LDAPException - If the bind attempt fails.

    • bind

      public void bind(@Nullable String dn, @Nullable String password) throws LDAPException
      Authenticates to the directory server using a simple bind with the provided information.
      Parameters:
      dn - The DN of the user for the bind.
      password - The password to use for the bind.
      Throws:
      LDAPException - If the bind attempt fails.

    • bind

      public void bind(@Nullable String dn, @Nullable String password, @Nullable LDAPConstraints constraints) throws LDAPException
      Authenticates to the directory server using a simple bind with the provided information.
      Parameters:
      dn - The DN of the user for the bind.
      password - The password to use for the bind.
      constraints - The constraints to use for the bind operation.
      Throws:
      LDAPException - If the bind attempt fails.

    • bind

      public void bind(int version, @Nullable String dn, @Nullable String password) throws LDAPException
      Authenticates to the directory server using a simple bind with the provided information.
      Parameters:
      version - The LDAP protocol version to use. This will be ignored, since this implementation only supports LDAPv3.
      dn - The DN of the user for the bind.
      password - The password to use for the bind.
      Throws:
      LDAPException - If the bind attempt fails.

    • bind

      public void bind(int version, @Nullable String dn, @Nullable String password, @Nullable LDAPConstraints constraints) throws LDAPException
      Authenticates to the directory server using a simple bind with the provided information.
      Parameters:
      version - The LDAP protocol version to use. This will be ignored, since this implementation only supports LDAPv3.
      dn - The DN of the user for the bind.
      password - The password to use for the bind.
      constraints - The constraints to use for the bind operation.
      Throws:
      LDAPException - If the bind attempt fails.

    • compare

      public boolean compare(@NotNull String dn, @NotNull LDAPAttribute attribute) throws LDAPException
      Indicates whether the specified entry has the given attribute value.
      Parameters:
      dn - The DN of the entry to compare.
      attribute - The attribute (which must have exactly one value) to use for the comparison.
      Returns:
      true if the compare matched the target entry, or false if not.
      Throws:
      LDAPException - If a problem occurs while processing the compare.

    • compare

      public boolean compare(@NotNull String dn, @NotNull LDAPAttribute attribute, @Nullable LDAPConstraints constraints) throws LDAPException
      Indicates whether the specified entry has the given attribute value.
      Parameters:
      dn - The DN of the entry to compare.
      attribute - The attribute (which must have exactly one value) to use for the comparison.
      constraints - The constraints to use for the compare operation.
      Returns:
      true if the compare matched the target entry, or false if not.
      Throws:
      LDAPException - If a problem occurs while processing the compare.

    • delete

      public void delete(@NotNull String dn) throws LDAPException
      Removes an entry from the directory.
      Parameters:
      dn - The DN of the entry to delete.
      Throws:
      LDAPException - If a problem occurs while processing the delete.

    • delete

      public void delete(@NotNull String dn, @Nullable LDAPConstraints constraints) throws LDAPException
      Removes an entry from the directory.
      Parameters:
      dn - The DN of the entry to delete.
      constraints - The constraints to use for the delete operation.
      Throws:
      LDAPException - If a problem occurs while processing the delete.

    • extendedOperation

      @NotNull public LDAPExtendedOperation extendedOperation(@NotNull LDAPExtendedOperation extendedOperation) throws LDAPException
      Processes an extended operation in the directory.
      Parameters:
      extendedOperation - The extended operation to process.
      Returns:
      The result returned from the extended operation.
      Throws:
      LDAPException - If a problem occurs while processing the operation.

    • extendedOperation

      @NotNull public LDAPExtendedOperation extendedOperation(@NotNull LDAPExtendedOperation extendedOperation, @Nullable LDAPConstraints constraints) throws LDAPException
      Processes an extended operation in the directory.
      Parameters:
      extendedOperation - The extended operation to process.
      constraints - The constraints to use for the operation.
      Returns:
      The result returned from the extended operation.
      Throws:
      LDAPException - If a problem occurs while processing the operation.

    • modify

      public void modify(@NotNull String dn, @NotNull LDAPModification mod) throws LDAPException
      Modifies an entry in the directory.
      Parameters:
      dn - The DN of the entry to modify.
      mod - The modification to apply to the entry.
      Throws:
      LDAPException - If a problem occurs while processing the delete.

    • modify

      public void modify(@NotNull String dn, @NotNull LDAPModification[] mods) throws LDAPException
      Modifies an entry in the directory.
      Parameters:
      dn - The DN of the entry to modify.
      mods - The modifications to apply to the entry.
      Throws:
      LDAPException - If a problem occurs while processing the delete.

    • modify

      public void modify(@NotNull String dn, @NotNull LDAPModification mod, @Nullable LDAPConstraints constraints) throws LDAPException
      Modifies an entry in the directory.
      Parameters:
      dn - The DN of the entry to modify.
      mod - The modification to apply to the entry.
      constraints - The constraints to use for the modify operation.
      Throws:
      LDAPException - If a problem occurs while processing the delete.

    • modify

      public void modify(@NotNull String dn, @NotNull LDAPModification[] mods, @Nullable LDAPConstraints constraints) throws LDAPException
      Modifies an entry in the directory.
      Parameters:
      dn - The DN of the entry to modify.
      mods - The modifications to apply to the entry.
      constraints - The constraints to use for the modify operation.
      Throws:
      LDAPException - If a problem occurs while processing the delete.

    • modify

      public void modify(@NotNull String dn, @NotNull LDAPModificationSet mods) throws LDAPException
      Modifies an entry in the directory.
      Parameters:
      dn - The DN of the entry to modify.
      mods - The modifications to apply to the entry.
      Throws:
      LDAPException - If a problem occurs while processing the delete.

    • modify

      public void modify(@NotNull String dn, @NotNull LDAPModificationSet mods, @Nullable LDAPConstraints constraints) throws LDAPException
      Modifies an entry in the directory.
      Parameters:
      dn - The DN of the entry to modify.
      mods - The modifications to apply to the entry.
      constraints - The constraints to use for the modify operation.
      Throws:
      LDAPException - If a problem occurs while processing the delete.

    • read

      @NotNull public LDAPEntry read(@NotNull String dn) throws LDAPException
      Retrieves an entry from the directory server.
      Parameters:
      dn - The DN of the entry to retrieve.
      Returns:
      The entry that was read.
      Throws:
      LDAPException - If a problem occurs while performing the search.

    • read

      @NotNull public LDAPEntry read(@NotNull String dn, @Nullable LDAPSearchConstraints constraints) throws LDAPException
      Retrieves an entry from the directory server.
      Parameters:
      dn - The DN of the entry to retrieve.
      constraints - The constraints to use for the search operation.
      Returns:
      The entry that was read.
      Throws:
      LDAPException - If a problem occurs while performing the search.

    • read

      @NotNull public LDAPEntry read(@NotNull String dn, @Nullable String[] attrs) throws LDAPException
      Retrieves an entry from the directory server.
      Parameters:
      dn - The DN of the entry to retrieve.
      attrs - The set of attributes to request.
      Returns:
      The entry that was read.
      Throws:
      LDAPException - If a problem occurs while performing the search.

    • read

      @NotNull public LDAPEntry read(@NotNull String dn, @Nullable String[] attrs, @Nullable LDAPSearchConstraints constraints) throws LDAPException
      Retrieves an entry from the directory server.
      Parameters:
      dn - The DN of the entry to retrieve.
      attrs - The set of attributes to request.
      constraints - The constraints to use for the search operation.
      Returns:
      The entry that was read.
      Throws:
      LDAPException - If a problem occurs while performing the search.

    • rename

      public void rename(@NotNull String dn, @NotNull String newRDN, boolean deleteOldRDN) throws LDAPException
      Alters the DN of an entry in the directory.
      Parameters:
      dn - The DN of the entry to modify.
      newRDN - The new RDN to use for the entry.
      deleteOldRDN - Indicates whether to remove the old RDN value(s).
      Throws:
      LDAPException - If a problem occurs while processing the delete.

    • rename

      public void rename(@NotNull String dn, @NotNull String newRDN, boolean deleteOldRDN, @Nullable LDAPConstraints constraints) throws LDAPException
      Alters the DN of an entry in the directory.
      Parameters:
      dn - The DN of the entry to modify.
      newRDN - The new RDN to use for the entry.
      deleteOldRDN - Indicates whether to remove the old RDN value(s).
      constraints - The constraints to use for the modify operation.
      Throws:
      LDAPException - If a problem occurs while processing the delete.

    • rename

      public void rename(@NotNull String dn, @NotNull String newRDN, @Nullable String newParentDN, boolean deleteOldRDN) throws LDAPException
      Alters the DN of an entry in the directory.
      Parameters:
      dn - The DN of the entry to modify.
      newRDN - The new RDN to use for the entry.
      newParentDN - The DN of the new parent, or null if it should not be moved below a new parent.
      deleteOldRDN - Indicates whether to remove the old RDN value(s).
      Throws:
      LDAPException - If a problem occurs while processing the delete.

    • rename

      public void rename(@NotNull String dn, @NotNull String newRDN, @Nullable String newParentDN, boolean deleteOldRDN, @Nullable LDAPConstraints constraints) throws LDAPException
      Alters the DN of an entry in the directory.
      Parameters:
      dn - The DN of the entry to modify.
      newRDN - The new RDN to use for the entry.
      newParentDN - The DN of the new parent, or null if it should not be moved below a new parent.
      deleteOldRDN - Indicates whether to remove the old RDN value(s).
      constraints - The constraints to use for the modify operation.
      Throws:
      LDAPException - If a problem occurs while processing the delete.

    • search

      @NotNull public LDAPSearchResults search(@NotNull String baseDN, int scope, @NotNull String filter, @Nullable String[] attributes, boolean typesOnly) throws LDAPException
      Processes a search in the directory server.
      Parameters:
      baseDN - The base DN for the search.
      scope - The scope for the search.
      filter - The filter for the search.
      attributes - The set of attributes to request.
      typesOnly - Indicates whether to return attribute types only or both types and values.
      Returns:
      The entry that was read.
      Throws:
      LDAPException - If a problem occurs while performing the search.

    • search

      @NotNull public LDAPSearchResults search(@NotNull String baseDN, int scope, @NotNull String filter, @Nullable String[] attributes, boolean typesOnly, @Nullable LDAPSearchConstraints constraints) throws LDAPException
      Processes a search in the directory server.
      Parameters:
      baseDN - The base DN for the search.
      scope - The scope for the search.
      filter - The filter for the search.
      attributes - The set of attributes to request.
      typesOnly - Indicates whether to return attribute types only or both types and values.
      constraints - The constraints to use for the search operation.
      Returns:
      The entry that was read.
      Throws:
      LDAPException - If a problem occurs while performing the search.