Package netscape.ldap

Class LDAPConnection

java.lang.Object
netscape.ldap.LDAPConnection
All Implemented Interfaces:
Serializable, Cloneable, LDAPAsynchronousConnection, LDAPv2, LDAPv3

public class LDAPConnection extends Object implements LDAPv3, LDAPAsynchronousConnection, Cloneable, Serializable
Represents a connection to an LDAP server.

Use objects of this class to perform LDAP operations (such as search, modify, and add) on an LDAP server.

To perform an LDAP operation on a server, you need to follow these steps:

  1. Create a new LDAPConnection object.
  2. Use the connect method to connect to the LDAP server.
  3. Use the authenticate method to authenticate to server.
  4. Perform the LDAP operation.
  5. Use the disconnect method to disconnect from the server when done.

All operations block until completion (with the exception of the search method in which the results may not all return at the same time).

This class also specifies a default set of constraints (such as the maximum length of time to allow for an operation before timing out) which apply to all operations. To get and set these constraints, use the getOption and setOption methods. To override these constraints for an individual operation, define a new set of constraints by creating a LDAPConstraints object and pass the object to the method for the operation. For search operations, additional constraints are defined in LDAPSearchConstraints (a subclass of LDAPConstraints). To override the default search constraints, create an LDAPSearchConstraints object and pass it to the search method.

If you set up your client to follow referrals automatically, an operation that results in a referral will create a new connection to the LDAP server identified in the referral. In order to have your client authenticate to that LDAP server automatically, you need to define a class that implements the LDAPRebind interface. In your definition of the class, you need to define a getRebindAuthentication method that creates an LDAPRebindAuth object containing the distinguished name and password to use for reauthentication.

Most errors that occur raise the same exception (LDAPException). In order to determine the exact problem that occurred, you can retrieve the result code from this exception and compare its value against a set of defined result codes.

Version:
1.0
See Also:
  • Field Details

    • LDAP_VERSION

      public static final int LDAP_VERSION
      Version of the LDAP protocol used by default. LDAP_VERSION is 2, so your client will attempt to authenticate to LDAP servers as an LDAP v2 client. The following is an example of some code that prints the value of this variable:

       LDAPConnection ld = new LDAPConnection();
       System.out.println( "The default LDAP protocol version used is "
                            ld.LDAP_VERSION );
       
      If you want to authenticate as an LDAP v3 client, use the authenticate(int version, String dn, String passwd) method. For example:

       ld.authenticate( 3, myDN, myPW );
       
      See Also:
    • LDAP_PROPERTY_SDK

      public static final String LDAP_PROPERTY_SDK
      Name of the property specifying the version of the SDK.

      To get the version number, pass this name to the getProperty method. The SDK version number is of the type Float. For example:

            ...
            Float sdkVersion = ( Float )myConn.getProperty( myConn.LDAP_PROPERTY_SDK );
            System.out.println( "SDK version: " + sdkVersion );
            ... 
      See Also:
    • LDAP_PROPERTY_PROTOCOL

      public static final String LDAP_PROPERTY_PROTOCOL
      Name of the property specifying the highest supported version of the LDAP protocol.

      To get the version number, pass this name to the getProperty method. The LDAP protocol version number is of the type Float. For example:

            ...
            Float LDAPVersion = ( Float )myConn.getProperty( myConn.LDAP_PROPERTY_PROTOCOL );
            System.out.println( "Highest supported LDAP protocol version: " + LDAPVersion );
            ... 
      See Also:
    • LDAP_PROPERTY_SECURITY

      public static final String LDAP_PROPERTY_SECURITY
      Name of the property specifying the types of authentication allowed by this API (for example, anonymous authentication and simple authentication).

      To get the supported types, pass this name to the getProperty method. The value of this property is of the type String. For example:

            ...
            String authTypes = ( String )myConn.getProperty( myConn.LDAP_PROPERTY_SECURITY );
            System.out.println( "Supported authentication types: " + authTypes );
            ... 
      See Also:
    • TRACE_PROPERTY

      public static final String TRACE_PROPERTY
      Name of the property to enable/disable LDAP message trace.

      The property can be specified either as a system property (java -D command line option), or programmatically with the setProperty method.

      When -D command line option is used, defining the property with no value will send the trace output to the standard error. If the value is defined, it is assumed to be the name of an output file. If the file name is prefixed with a '+' character, the file is opened in append mode.

      When the property is set with the getProperty method, the property value must be either a String (represents a file name) an OutputStream or an instance of LDAPTraceWriter. To stop tracing, null should be passed as the property value.

      See Also:
    • NODELAY_SERIAL

      public static final int NODELAY_SERIAL
      Specifies the serial connection setup policy when a list of hosts is passed to the connect method.
      See Also:
    • NODELAY_PARALLEL

      public static final int NODELAY_PARALLEL
      Specifies the parallel connection setup policy with no delay when a list of hosts is passed to the connect method. For each host in the list, a separate thread is created to attempt to connect to the host. All threads are started simultaneously.
      See Also:
    • MAXBACKLOG

      public static final int MAXBACKLOG
      Option specifying the maximum number of unread entries to be cached in any LDAPSearchResults without suspending reading from the server.
      See Also:
  • Constructor Details

  • Method Details

    • finalize

      public void finalize() throws LDAPException
      Finalize method, which disconnects from the LDAP server.
      Overrides:
      finalize in class Object
      Throws:
      LDAPException - Thrown when the connection cannot be disconnected.
    • setCache

      public void setCache(LDAPCache cache)
      Sets the specified LDAPCache object as the cache for the LDAPConnection object.

      Parameters:
      cache - the LDAPCache object representing the cache that the current connection should use
      See Also:
    • getCache

      public LDAPCache getCache()
      Gets the LDAPCache object associated with the current LDAPConnection object.

      Returns:
      the LDAPCache object representing the cache that the current connection should use
      See Also:
    • getProperty

      public Object getProperty(String name) throws LDAPException
      Gets a property of a connection.

      You can get the following properties for a given connection:

      • LDAP_PROPERTY_SDK

        To get the version of this SDK, get this property. The value of this property is of the type Float.

      • LDAP_PROPERTY_PROTOCOL

        To get the highest supported version of the LDAP protocol, get this property. The value of this property is of the type Float.

      • LDAP_PROPERTY_SECURITY

        To get a comma-separated list of the types of authentication supported, get this property. The value of this property is of the type String.

      For example, the following section of code gets the version of the SDK.

             ...
             Float sdkVersion = ( Float )myConn.getProperty( myConn.LDAP_PROPERTY_SDK );
             System.out.println( "SDK version: " + sdkVersion );
             ... 
      Parameters:
      name - name of the property (for example, LDAP_PROPERTY_SDK)

      Returns:
      the value of the property.

      Since the return value is an object, you should recast it as the appropriate type. (For example, when getting the LDAP_PROPERTY_SDK property, recast the return value as a Float.)

      If you pass this method an unknown property name, the method returns null.

      Throws:
      LDAPException - Unable to get the value of the specified property.

      See Also:
    • setProperty

      public void setProperty(String name, Object val) throws LDAPException
      Change a property of a connection.

      The following properties are defined:
      com.netscape.ldap.schema.quoting - "standard" or "NetscapeBug"
      Note: if this property is not set, the SDK will query the server to determine if attribute syntax values and objectclass superior values must be quoted when adding schema.
      com.netscape.ldap.saslpackage - the default is "com.netscape.sasl"

      Parameters:
      name - name of the property to set
      val - value to set
      Throws:
      LDAPException - Unable to set the value of the specified property.
    • getHost

      public String getHost()
      Returns the host name of the LDAP server to which you are connected.
      Returns:
      host name of the LDAP server.
    • getPort

      public int getPort()
      Returns the port number of the LDAP server to which you are connected.
      Returns:
      port number of the LDAP server.
    • getAuthenticationDN

      public String getAuthenticationDN()
      Returns the distinguished name (DN) used for authentication over this connection.
      Returns:
      distinguished name used for authentication over this connection.
    • getAuthenticationPassword

      public String getAuthenticationPassword()
      Returns the password used for authentication over this connection.
      Returns:
      password used for authentication over this connection.
    • getConnectTimeout

      public int getConnectTimeout()
      Returns the maximum time to wait for the connection to be established.
      Returns:
      the maximum connect time in seconds or 0 (unlimited)
      See Also:
    • setConnectTimeout

      public void setConnectTimeout(int timeout)
      Specifies the maximum time to wait for the connection to be established. If the value is 0, the time is not limited.
      Parameters:
      timeout - the maximum connect time in seconds or 0 (unlimited)
    • getConnSetupDelay

      public int getConnSetupDelay()
      Returns the delay in seconds when making concurrent connection attempts to multiple servers.
      Returns:
      the delay in seconds between connection attempts:
      The serial connection setup policy is enabled (no concurrency).
      The parallel connection setup policy with no delay is enabled.
      The parallel connection setup policy with the delay of seconds is enabled.
      See Also:
    • setConnSetupDelay

      public void setConnSetupDelay(int delay)
      Specifies the delay in seconds when making concurrent connection attempts to multiple servers.

      Effectively, selects the connection setup policy when a list of hosts is passed to the method.
      If the serial policy is selected, the default one, an attempt is made to connect to the first host in the list. The next entry in the list is tried only if the attempt to connect to the current host fails. This might cause your application to block for unacceptably long time if a host is down.
      If the parallel policy is selected, multiple connection attempts may run concurrently on a separate thread. A new connection attempt to the next entry in the list can be started with or without delay.

      You must set the before making the call to the method.

      Parameters:
      delay - the delay in seconds between connection attempts. Possible values are:
      Use the serial connection setup policy.
      Use the parallel connection setup policy with no delay. Start all connection setup threads immediately.
      Use the parallel connection setup policy with delay. Start another connection setup thread after seconds.
      See Also:
    • getSocketFactory

      public LDAPSocketFactory getSocketFactory()
      Gets the object representing the socket factory used to establish a connection to the LDAP server or for the start TLS operation.

      Returns:
      the object representing the socket factory used to establish a connection to a server or for the start TLS operation.
      See Also:
    • setSocketFactory

      public void setSocketFactory(LDAPSocketFactory factory)
      Specifies the object representing the socket factory that you want to use to establish a connection to a server or for the start TLS operation.

      If the socket factory is to be used to establish a connection setSocketFactory() must be called before connect(). For the start TLS operation setSocketFactory() must be called after connect().

      Parameters:
      factory - the object representing the socket factory that you want to use to establish a connection to a server or for the start TLS operation.
      See Also:
    • isConnected

      public boolean isConnected()
      Indicates whether the connection represented by this object is open at this time.
      Returns:
      true if connected to an LDAP server over this connection. If not connected to an LDAP server, returns false.
    • isAuthenticated

      public boolean isAuthenticated()
      Indicates whether this client has authenticated to the LDAP server
      Returns:
      true,, if authenticated. If not authenticated, or if authenticated as an anonymous user (with either a blank name or password), returns false.
    • connect

      public void connect(String host, int port) throws LDAPException
      Connects to the specified host and port. If this LDAPConnection object represents an open connection, the connection is closed first before the new connection is opened.

      For example, the following section of code establishes a connection with the LDAP server running on the host ldap.netscape.com and the port 389.

       String ldapHost = "ldap.netscape.com";
       int ldapPort = 389;
       LDAPConnection myConn = new LDAPConnection();
       try {
           myConn.connect( ldapHost, ldapPort );
       } catch ( LDAPException e ) {
           System.out.println( "Unable to connect to " + ldapHost +
                               " at port " + ldapPort );
           return;
       }
       System.out.println( "Connected to " + ldapHost + " at port " + ldapPort )
       

      You can limit the time spent waiting for the connection to be established by calling setConnectTimeout before connect.

      Specified by:
      connect in interface LDAPv2
      Parameters:
      host - host name of the LDAP server to which you want to connect. This value can also be a space-delimited list of hostnames or hostnames and port numbers (using the syntax hostname:portnumber). For example, you can specify the following values for the host argument:
         myhost
         myhost hishost:389 herhost:5000 whathost
         myhost:686 myhost:389 hishost:5000 whathost:1024
      
      If multiple servers are specified in the host list, the connection setup policy specified with the ConnSetupDelay property controls whether connection attempts are made serially or concurrently.

      port - port number of the LDAP server to which you want to connect. This parameter is ignored for any host in the host parameter which includes a colon and port number.
      Throws:
      LDAPException - The connection failed.
      See Also:
    • connect

      public void connect(String host, int port, String dn, String passwd) throws LDAPException
      Connects to the specified host and port and uses the specified DN and password to authenticate to the server. If this LDAPConnection object represents an open connection, the connection is closed first before the new connection is opened.

      For example, the following section of code establishes a connection with the LDAP server running on ldap.netscape.com at port 389. The example also attempts to authenticate the client as Barbara Jensen.

       String ldapHost = "ldap.netscape.com";
       int ldapPort = 389;
       String myDN = "cn=Barbara Jensen,ou=Product Development,o=Ace Industry,c=US";
       String myPW = "hifalutin";
       LDAPConnection myConn = new LDAPConnection();
       try {
           myConn.connect( ldapHost, ldapPort, myDN, myPW );
       } catch ( LDAPException e ) {
           switch( e.getLDAPResultCode() ) {
               case e.NO_SUCH_OBJECT:
                   System.out.println( "The specified user does not exist." );
                   break;
               case e.INVALID_CREDENTIALS:
                   System.out.println( "Invalid password." );
                   break;
               default:
                   System.out.println( "Error number: " + e.getLDAPResultCode() );
                   System.out.println( "Failed to connect to " + ldapHost + " at port " + ldapPort );
                   break;
           }
           return;
       }
       System.out.println( "Connected to " + ldapHost + " at port " + ldapPort );
       

      You can limit the time spent waiting for the connection to be established by calling setConnectTimeout before connect.

      Specified by:
      connect in interface LDAPv2
      Parameters:
      host - host name of the LDAP server to which you want to connect. This value can also be a space-delimited list of hostnames or hostnames and port numbers (using the syntax hostname:portnumber). For example, you can specify the following values for the host argument:
         myhost
         myhost hishost:389 herhost:5000 whathost
         myhost:686 myhost:389 hishost:5000 whathost:1024
      
      If multiple servers are specified in the host list, the connection setup policy specified with the ConnSetupDelay property controls whether connection attempts are made serially or concurrently.

      port - port number of the LDAP server to which you want to connect. This parameter is ignored for any host in the host parameter which includes a colon and port number.
      dn - distinguished name used for authentication
      passwd - password used for authentication
      Throws:
      LDAPException - The connection or authentication failed.
      See Also:
    • connect

      public void connect(String host, int port, String dn, String passwd, LDAPConstraints cons) throws LDAPException
      Connects to the specified host and port and uses the specified DN and password to authenticate to the server. If this LDAPConnection object represents an open connection, the connection is closed first before the new connection is opened. This method allows the user to specify the preferences for the bind operation.

      You can limit the time spent waiting for the connection to be established by calling setConnectTimeout before connect.

      Parameters:
      host - host name of the LDAP server to which you want to connect. This value can also be a space-delimited list of hostnames or hostnames and port numbers (using the syntax hostname:portnumber). For IPv6 enclose the address in square brackets. For example, you can specify the following values for the host argument:
         myhost
         myhost hishost:389 herhost:5000 whathost
         myhost:686 myhost:389 hishost:5000 whathost:1024
         [::1]:389 [2620:52:0:102f:5054:1ff:fe2c:e12d]:636
      
      If multiple servers are specified in the host list, the connection setup policy specified with the ConnSetupDelay property controls whether connection attempts are made serially or concurrently.

      port - port number of the LDAP server to which you want to connect. This parameter is ignored for any host in the host parameter which includes a colon and port number.
      dn - distinguished name used for authentication
      passwd - password used for authentication
      cons - preferences for the bind operation
      Throws:
      LDAPException - The connection or authentication failed.
      See Also:
    • connect

      @Deprecated public void connect(String host, int port, String dn, String passwd, LDAPSearchConstraints cons) throws LDAPException
      Deprecated.
      Please use the method signature where cons is LDAPConstraints instead of LDAPSearchConstraints
      Throws:
      LDAPException
    • connect

      public void connect(int version, String host, int port, String dn, String passwd) throws LDAPException
      Connects to the specified host and port and uses the specified DN and password to authenticate to the server, with the specified LDAP protocol version. If the server does not support the requested protocol version, an exception is thrown. If this LDAPConnection object represents an open connection, the connection is closed first before the new connection is opened. This is equivalent to connect(host, port) followed by authenticate(version, dn, passwd).

      Specified by:
      connect in interface LDAPv3
      Parameters:
      version - requested version of LDAP: currently 2 or 3
      host - a hostname to which to connect or a dotted string representing the IP address of this host. Alternatively, this can be a space-delimited list of host names. Each host name may include a trailing colon and port number. In the case where more than one host name is specified, the connection setup policy specified with the ConnSetupDelay property controls whether connection attempts are made serially or concurrently.

         Examples:
            "directory.knowledge.com"
            "199.254.1.2"
            "directory.knowledge.com:1050 people.catalog.com 199.254.1.2"
       
      port - the TCP or UDP port number to which to connect or contact. The default LDAP port is 389. "port" is ignored for any host name which includes a colon and port number.
      dn - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name
      passwd - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name and passwd as password.
      Throws:
      LDAPException - The connection or authentication failed.
      See Also:
    • connect

      public void connect(int version, String host, int port, String dn, String passwd, LDAPConstraints cons) throws LDAPException
      Connects to the specified host and port and uses the specified DN and password to authenticate to the server, with the specified LDAP protocol version. If the server does not support the requested protocol version, an exception is thrown. This method allows the user to specify preferences for the bind operation. If this LDAPConnection object represents an open connection, the connection is closed first before the new connection is opened. This is equivalent to connect(host, port) followed by authenticate(version, dn, passwd).

      Parameters:
      version - requested version of LDAP: currently 2 or 3
      host - a hostname to which to connect or a dotted string representing the IP address of this host. Alternatively, this can be a space-delimited list of host names. Each host name may include a trailing colon and port number. In the case where more than one host name is specified, the connection setup policy specified with the ConnSetupDelay property controls whether connection attempts are made serially or concurrently.

         Examples:
            "directory.knowledge.com"
            "199.254.1.2"
            "directory.knowledge.com:1050 people.catalog.com 199.254.1.2"
       
      port - the TCP or UDP port number to which to connect or contact. The default LDAP port is 389. "port" is ignored for any host name which includes a colon and port number.
      dn - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name
      passwd - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name and passwd as password
      cons - preferences for the bind operation
      Throws:
      LDAPException - The connection or authentication failed.
      See Also:
    • connect

      @Deprecated public void connect(int version, String host, int port, String dn, String passwd, LDAPSearchConstraints cons) throws LDAPException
      Deprecated.
      Please use the method signature where cons is LDAPConstraints instead of LDAPSearchConstraints
      Throws:
      LDAPException
    • abandon

      public void abandon(LDAPSearchResults searchResults) throws LDAPException
      Abandons a current search operation, notifying the server not to send additional search results.
      Specified by:
      abandon in interface LDAPv2
      Parameters:
      searchResults - the search results returned when the search was started
      Throws:
      LDAPException - Failed to notify the LDAP server.
      See Also:
    • authenticate

      public void authenticate(String dn, String passwd) throws LDAPException
      Authenticates to the LDAP server (to which you are currently connected) using the specified name and password. If you are not connected to the LDAP server, this method attempts to reconnect to the server.

      For example, the following section of code authenticates the client as Barbara Jensen. The code assumes that the client has already established a connection with an LDAP server.

       String myDN = "cn=Barbara Jensen,ou=Product Development,o=Ace Industry,c=US";
       String myPW = "hifalutin";
       try {
           myConn.authenticate( myDN, myPW );
       } catch ( LDAPException e ) {
           switch( e.getLDAPResultCode() ) {
               case e.NO_SUCH_OBJECT:
                   System.out.println( "The specified user does not exist." );
                   break;
               case e.INVALID_CREDENTIALS:
                   System.out.println( "Invalid password." );
                   break;
               default:
                   System.out.println( "Error number: " + e.getLDAPResultCode() );
                   System.out.println( "Failed to authentice as " + myDN );
                   break;
           }
           return;
       }
       System.out.println( "Authenticated as " + myDN );
       
      Specified by:
      authenticate in interface LDAPv2
      Parameters:
      dn - distinguished name used for authentication
      passwd - password used for authentication
      Throws:
      LDAPException - Failed to authenticate to the LDAP server.
    • authenticate

      public void authenticate(String dn, String passwd, LDAPConstraints cons) throws LDAPException
      Authenticates to the LDAP server (to which you are currently connected) using the specified name and password. The default protocol version (version 2) is used. If the server doesn't support the default version, an LDAPException is thrown with the error code PROTOCOL_ERROR. This method allows the user to specify the preferences for the bind operation.
      Parameters:
      dn - distinguished name used for authentication
      passwd - password used for authentication
      cons - preferences for the bind operation
      Throws:
      LDAPException - Failed to authenticate to the LDAP server.
    • authenticate

      @Deprecated public void authenticate(String dn, String passwd, LDAPSearchConstraints cons) throws LDAPException
      Deprecated.
      Please use the method signature where cons is LDAPConstraints instead of LDAPSearchConstraints
      Throws:
      LDAPException
    • authenticate

      public void authenticate(int version, String dn, String passwd) throws LDAPException
      Authenticates to the LDAP server (that you are currently connected to) using the specified name and password, and requesting that the server use at least the specified protocol version. If the server doesn't support that level, an LDAPException is thrown with the error code PROTOCOL_ERROR.
      Specified by:
      authenticate in interface LDAPv3
      Parameters:
      version - required LDAP protocol version
      dn - distinguished name used for authentication
      passwd - password used for authentication
      Throws:
      LDAPException - Failed to authenticate to the LDAP server.
    • authenticate

      public void authenticate(int version, String dn, String passwd, LDAPConstraints cons) throws LDAPException
      Authenticates to the LDAP server (to which you are currently connected) using the specified name and password, and requesting that the server use at least the specified protocol version. If the server doesn't support that level, an LDAPException is thrown with the error code PROTOCOL_ERROR. This method allows the user to specify the preferences for the bind operation.
      Parameters:
      version - required LDAP protocol version
      dn - distinguished name used for authentication
      passwd - password used for authentication
      cons - preferences for the bind operation
      Throws:
      LDAPException - Failed to authenticate to the LDAP server.
    • authenticate

      @Deprecated public void authenticate(int version, String dn, String passwd, LDAPSearchConstraints cons) throws LDAPException
      Deprecated.
      Please use the method signature where cons is LDAPConstraints instead of LDAPSearchConstraints
      Throws:
      LDAPException
    • authenticate

      public void authenticate(String dn, Hashtable<Object,Object> props, Object cbh) throws LDAPException
      Authenticates to the LDAP server (that the object is currently connected to) using the specified name and whatever SASL mechanisms are supported by the server. Each supported mechanism in turn is tried until authentication succeeds or an exception is thrown. If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object had already authenticated, the old authentication is discarded.
      Parameters:
      dn - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name
      cbh - a class which the SASL framework can call to obtain additional required information
      Throws:
      LDAPException - Failed to authenticate to the LDAP server.
    • authenticate

      public void authenticate(String dn, String[] mechanisms, Hashtable<Object,Object> props, Object cbh) throws LDAPException
      Authenticates to the LDAP server (to which the object is currently connected) using the specified name and a specified SASL mechanism or set of mechanisms. If the requested SASL mechanism is not available, an exception is thrown. If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object had already authenticated, the old authentication is discarded.
      Parameters:
      dn - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name
      mechanisms - a list of acceptable mechanisms. The first one for which a Mechanism Driver can be instantiated is returned.
      cbh - a class which the SASL framework can call to obtain additional required information
      Throws:
      LDAPException - Failed to authenticate to the LDAP server.
      See Also:
    • authenticate

      @Deprecated public void authenticate(String dn, String mechanism, String packageName, Hashtable<Object,Object> props, Object cbh) throws LDAPException
      Deprecated.
      Please use authenticate without packageName instead.
      Authenticates to the LDAP server (to which the object is currently connected) using the specified name and a specified SASL mechanism or set of mechanisms. If the requested SASL mechanism is not available, an exception is thrown. If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object had already authenticated, the old authentication is discarded.
      Parameters:
      dn - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name
      mechanism - a single mechanism name, e.g. "GSSAPI"
      packageName - a package containing a SASL ClientFactory, e.g. "myclasses.SASL". If null, a system default is used.
      cbh - a class which the SASL framework can call to obtain additional required information
      Throws:
      LDAPException - Failed to authenticate to the LDAP server.
    • authenticate

      @Deprecated public void authenticate(String dn, String[] mechanisms, String packageName, Hashtable<Object,Object> props, Object cbh) throws LDAPException
      Deprecated.
      Please use authenticate without packageName instead.
      Authenticates to the LDAP server (to which the object is currently connected) using the specified name and a specified SASL mechanism or set of mechanisms. If the requested SASL mechanism is not available, an exception is thrown. If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object had already authenticated, the old authentication is discarded.
      Parameters:
      dn - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name
      mechanisms - a list of acceptable mechanisms. The first one for which a Mechanism Driver can be instantiated is returned.
      packageName - a package containing a SASL ClientFactory, e.g. "myclasses.SASL". If null, a system default is used.
      cbh - a class which the SASL framework can call to obtain additional required information
      Throws:
      LDAPException - Failed to authenticate to the LDAP server.
    • authenticate

      public LDAPResponseListener authenticate(int version, String dn, String passwd, LDAPResponseListener listener, LDAPConstraints cons) throws LDAPException
      Authenticates to the LDAP server (that the object is currently connected to) using the specified name and password and allows you to specify constraints for this LDAP add operation by using an LDAPConstraints object. If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object had already authenticated, the old authentication is discarded.
      Parameters:
      version - Required LDAP protocol version.
      dn - If non-null and non-empty, specifies that the connection and all operations through it should be authenticated with dn as the distinguished name.
      passwd - If non-null and non-empty, specifies that the connection and all operations through it should be authenticated with dn as the distinguished name and passwd as password.
      listener - Handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      cons - Constraints specific to the operation.
      Returns:
      LDAPResponseListener Handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • authenticate

      public LDAPResponseListener authenticate(int version, String dn, String passwd, LDAPResponseListener listener) throws LDAPException
      Authenticates to the LDAP server (that the object is currently connected to) using the specified name and password and allows you to specify constraints for this LDAP add operation by using an LDAPConstraints object. If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object had already authenticated, the old authentication is discarded.
      Parameters:
      version - Required LDAP protocol version.
      dn - If non-null and non-empty, specifies that the connection and all operations through it should be authenticated with dn as the distinguished name.
      passwd - If non-null and non-empty, specifies that the connection and all operations through it should be authenticated with dn as the distinguished name and passwd as password.
      listener - Handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      Returns:
      LDAPResponseListener Handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • bind

      public void bind(String dn, String passwd) throws LDAPException
      Authenticates to the LDAP server (to which you are currently connected) using the specified name and password. If you are not already connected to the LDAP server, this method attempts to reconnect to the server.

      For example, the following section of code authenticates the client as Barbara Jensen. The code assumes that the client has already established a connection with an LDAP server.

       String myDN = "cn=Barbara Jensen,ou=Product Development,o=Ace Industry,c=US";
       String myPW = "hifalutin";
       try {
           myConn.bind( myDN, myPW );
       } catch ( LDAPException e ) {
           switch( e.getLDAPResultCode() ) {
               case e.NO_SUCH_OBJECT:
                   System.out.println( "The specified user does not exist." );
                   break;
               case e.INVALID_CREDENTIALS:
                   System.out.println( "Invalid password." );
                   break;
               default:
                   System.out.println( "Error number: " + e.getLDAPResultCode() );
                   System.out.println( "Failed to authentice as " + myDN );
                   break;
           }
           return;
       }
       System.out.println( "Authenticated as " + myDN );
       
      Specified by:
      bind in interface LDAPv2
      Parameters:
      dn - distinguished name used for authentication
      passwd - password used for authentication
      Throws:
      LDAPException - Failed to authenticate to the LDAP server.
    • bind

      public void bind(String dn, String passwd, LDAPConstraints cons) throws LDAPException
      Authenticates to the LDAP server (to which you are currently connected) using the specified name and password. The default protocol version (version 2) is used. If the server doesn't support the default version, an LDAPException is thrown with the error code PROTOCOL_ERROR. This method allows the user to specify the preferences for the bind operation.
      Parameters:
      dn - distinguished name used for authentication
      passwd - password used for authentication
      cons - preferences for the bind operation
      Throws:
      LDAPException - Failed to authenticate to the LDAP server.
    • bind

      public void bind(int version, String dn, String passwd) throws LDAPException
      Authenticates to the LDAP server (to which you are currently connected) using the specified name and password, and requests that the server use at least the specified protocol version. If the server doesn't support that level, an LDAPException is thrown with the error code PROTOCOL_ERROR.
      Specified by:
      bind in interface LDAPv3
      Parameters:
      version - required LDAP protocol version
      dn - distinguished name used for authentication
      passwd - password used for authentication
      Throws:
      LDAPException - Failed to authenticate to the LDAP server.
    • bind

      public void bind(int version, String dn, String passwd, LDAPConstraints cons) throws LDAPException
      Authenticates to the LDAP server (to which you are currently connected) using the specified name and password, and requesting that the server use at least the specified protocol version. If the server doesn't support that level, an LDAPException is thrown with the error code PROTOCOL_ERROR. This method allows the user to specify the preferences for the bind operation.
      Parameters:
      version - required LDAP protocol version
      dn - distinguished name used for authentication
      passwd - password used for authentication
      cons - preferences for the bind operation
      Throws:
      LDAPException - Failed to authenticate to the LDAP server.
    • bind

      public void bind(String dn, Hashtable<Object,Object> props, Object cbh) throws LDAPException
      Authenticates to the LDAP server (to which the object is currently connected) using the specified name and whatever SASL mechanisms are supported by the server. Each supported mechanism in turn is tried until authentication succeeds or an exception is thrown. If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object had already authenticated, the old authentication is discarded.
      Parameters:
      dn - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name
      cbh - a class which the SASL framework can call to obtain additional required information
      Throws:
      LDAPException - Failed to authenticate to the LDAP server.
    • bind

      public void bind(String dn, String[] mechanisms, Hashtable<Object,Object> props, Object cbh) throws LDAPException
      Authenticates to the LDAP server (to which the object is currently connected) using the specified name and a specified SASL mechanism or set of mechanisms. If the requested SASL mechanism is not available, an exception is thrown. If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object had already authenticated, the old authentication is discarded.
      Parameters:
      dn - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name
      mechanisms - a list of acceptable mechanisms. The first one for which a Mechanism Driver can be instantiated is returned.
      cbh - a class which the SASL framework can call to obtain additional required information
      Throws:
      LDAPException - Failed to authenticate to the LDAP server.
      See Also:
    • startTLS

      public void startTLS() throws LDAPException
      Begin using the Transport Layer Security (TLS) protocol for session privacy.

      Before startTLS() is called, a socket factory of type LDAPTLSSocketFactory must be set for the connection. The factory must be set after the connect() call.

       LDAPConnection ldc = new LDAPConnection();
       try {
           ldc.connect(host, port);
           ldc.setSocketFactory(new JSSSocketFactory());
           ldc.startTLS();
           ldc.autheticate(3, userdn, userpw);
       }
       catch (LDAPException e) {
       ...
       }
       

      If the socket factory of the connection is not capable of initiating a TLS session , an LDAPException is thrown with the error code TLS_NOT_SUPPORTED.

      If the server does not support the transition to a TLS session, an LDAPException is thrown with the error code returned by the server. If there are outstanding LDAP operations on the connection or the connection is already in the secure mode, an LDAPException is thrown.

      Throws:
      LDAPException - Failed to convert to a TLS session.
      Since:
      LDAPJDK 4.17
      See Also:
    • isTLS

      public boolean isTLS()
      Indicates if the session is currently protected by TLS.
      Returns:
      true if TLS was activated.
      Since:
      LDAPJDK 4.17
      See Also:
    • getAuthenticationMethod

      public String getAuthenticationMethod()
      Gets the authentication method used to bind:
      "none", "simple", or "sasl"
      Returns:
      the authentication method, or "none"
    • reconnect

      public void reconnect() throws LDAPException
      Disconnect from the server and then reconnect using the current credentials and authentication method.

      If TLS was enabled with the startTLS() call, reenable TLS after reconnect.

      Throws:
      LDAPException - if not previously connected, or if there is a failure on disconnecting or on connecting
    • disconnect

      public void disconnect() throws LDAPException
      Disconnects from the LDAP server. Before you can perform LDAP operations again, you need to reconnect to the server by calling connect.
      Specified by:
      disconnect in interface LDAPv2
      Throws:
      LDAPException - Failed to disconnect from the LDAP server.
      See Also:
    • close

      public void close()
    • read

      public LDAPEntry read(String DN) throws LDAPException
      Reads the entry for the specified distiguished name (DN) and retrieves all attributes for the entry.

      For example, the following section of code reads the entry for Barbara Jensen and retrieves all attributes for that entry.

       String findDN = "cn=Barbara Jensen,ou=Product Development,o=Ace Industry,c=US";
       LDAPEntry foundEntry = null;
       try {
           foundEntry = myConn.read( findDN );
       } catch ( LDAPException e ) {
           switch( e.getLDAPResultCode() ) {
               case e.NO_SUCH_OBJECT:
                   System.out.println( "The specified entry does not exist." );
                   break;
               case e.LDAP_PARTIAL_RESULTS:
                   System.out.println( "Entry served by a different LDAP server." );
                   break;
               case e.INSUFFICIENT_ACCESS_RIGHTS:
                   System.out.println( "You do not have the access rights to perform this operation." );
                   break;
               default:
                   System.out.println( "Error number: " + e.getLDAPResultCode() );
                   System.out.println( "Could not read the specified entry." );
                   break;
           }
           return;
       }
       System.out.println( "Found the specified entry." );
       
      Specified by:
      read in interface LDAPv2
      Parameters:
      DN - distinguished name of the entry to retrieve
      Returns:
      LDAPEntry returns the specified entry or raises an exception if the entry is not found.
      Throws:
      LDAPException - Failed to find or read the specified entry from the directory.
    • read

      public LDAPEntry read(String DN, LDAPSearchConstraints cons) throws LDAPException
      Reads the entry for the specified distiguished name (DN) and retrieves all attributes for the entry. This method allows the user to specify the preferences for the read operation.

      For example, the following section of code reads the entry for Barbara Jensen and retrieves all attributes for that entry.

       String findDN = "cn=Barbara Jensen,ou=Product Development,o=Ace Industry,c=US";
       LDAPEntry foundEntry = null;
       try {
           foundEntry = myConn.read( findDN );
       } catch ( LDAPException e ) {
           switch( e.getLDAPResultCode() ) {
               case e.NO_SUCH_OBJECT:
                   System.out.println( "The specified entry does not exist." );
                   break;
               case e.LDAP_PARTIAL_RESULTS:
                   System.out.println( "Entry served by a different LDAP server." );
                   break;
               case e.INSUFFICIENT_ACCESS_RIGHTS:
                   System.out.println( "You do not have the access rights to perform this operation." );
                   break;
               default:
                   System.out.println( "Error number: " + e.getLDAPResultCode() );
                   System.out.println( "Could not read the specified entry." );
                   break;
           }
           return;
       }
       System.out.println( "Found the specified entry." );
       
      Parameters:
      DN - distinguished name of the entry to retrieve
      cons - preferences for the read operation
      Returns:
      LDAPEntry returns the specified entry or raises an exception if the entry is not found.
      Throws:
      LDAPException - Failed to find or read the specified entry from the directory.
    • read

      public LDAPEntry read(String DN, String[] attrs) throws LDAPException
      Reads the entry for the specified distinguished name (DN) and retrieves only the specified attributes from the entry.

      For example, the following section of code reads the entry for Barbara Jensen and retrieves only the cn and sn attributes. The example prints out all attributes that have been retrieved (the two specified attributes).

       String findDN = "cn=Barbara Jensen,ou=Product Development,o=Ace Industry,c=US";
       LDAPEntry foundEntry = null;
       String getAttrs[] = { "cn", "sn" };
       try {
            foundEntry = myConn.read( findDN, getAttrs );
       } catch ( LDAPException e ) {
            switch( e.getLDAPResultCode() ) {
                 case e.NO_SUCH_OBJECT:
                     System.out.println( "The specified entry does not exist." );
                     break;
                 case e.LDAP_PARTIAL_RESULTS:
                     System.out.println( "Entry served by a different LDAP server." );
                     break;
                 case e.INSUFFICIENT_ACCESS_RIGHTS:
                     System.out.println( "You do not have the access " +
                                         "rights to perform this operation." );
                     break;
                 default:
                     System.out.println( "Error number: " + e.getLDAPResultCode() );
                     System.out.println( "Could not read the specified entry." );
                     break;
            }
            return;
       }
      
       LDAPAttributeSet foundAttrs = foundEntry.getAttributeSet();
       int size = foundAttrs.size();
       Enumeration itrAttrs = foundAttrs.getAttributes();
       System.out.println( "Attributes: " );
      
       while ( itrAttrs.hasMoreElements() ) {
            LDAPAttribute anAttr = ( LDAPAttribute )itrAttrs.nextElement();
            String attrName = anAttr.getName();
            System.out.println( "\t" + attrName );
            Enumeration itrVals = anAttr.getStringValues();
            while ( itrVals.hasMoreElements() ) {
                 String aVal = ( String )itrVals.nextElement();
                 System.out.println( "\t\t" + aVal );
            }
       }
       
      Specified by:
      read in interface LDAPv2
      Parameters:
      DN - distinguished name of the entry to retrieve
      attrs - names of attributes to retrieve
      Returns:
      LDAPEntry returns the specified entry (or raises an exception if the entry is not found).
      Throws:
      LDAPException - Failed to read the specified entry from the directory.
    • read

      public LDAPEntry read(String DN, String[] attrs, LDAPSearchConstraints cons) throws LDAPException
      Description copied from interface: LDAPv2
      Read the entry corresponding to the specified distinguished name (DN), and retrieve only the specified attributes.
      Specified by:
      read in interface LDAPv2
      Parameters:
      DN - distinguished name of the entry to retrieve
      attrs - names of attributes to retrieve
      cons - the constraints set for the read operation
      Throws:
      LDAPException - Failed to retrieve the specified entry.
    • read

      public static LDAPEntry read(LDAPUrl toGet) throws LDAPException
      Reads the entry specified by the LDAP URL.

      When you call this method, a new connection is created automatically, using the host and port specified in the URL. After finding the entry, the method closes this connection (in other words, it disconnects from the LDAP server).

      If the URL specifies a filter and scope, these are not used. Of the information specified in the URL, this method only uses the LDAP host name and port number, the base distinguished name (DN), and the list of attributes to return.

      The method returns the entry specified by the base DN.

      (Note: If you want to search for more than one entry, use the search( LDAPUrl ) method instead.)

      For example, the following section of code reads the entry specified by the LDAP URL.

       String flatURL = "ldap://alway.mcom.com:3890/cn=Barbara Jenson,ou=Product Development,o=Ace Industry,c=US?cn,sn,mail";
       LDAPUrl myURL;
       try {
          myURL = new LDAPUrl( flatURL );
       } catch ( java.net.MalformedURLException e ) {
          System.out.println( "BAD URL!!!  BAD, BAD, BAD URL!!!" );
          return;
       }
       LDAPEntry myEntry = null;
       try {
          myEntry = myConn.read( myURL );
       } catch ( LDAPException e ) {
          int errCode = e.getLDAPResultCode();
          switch( errCode ) {
              case ( e.NO_SUCH_OBJECT ):
                  System.out.println( "The specified entry " + myDN +
                                      " does not exist in the directory." );
                  return;
              default:
                  System.out.println( "An internal error occurred." );
                  return;
          }
       }
       
      Parameters:
      toGet - LDAP URL specifying the entry to read
      Returns:
      LDAPEntry returns the entry specified by the URL (or raises an exception if the entry is not found).
      Throws:
      LDAPException - Failed to read the specified entry from the directory.
      See Also:
    • search

      public static LDAPSearchResults search(LDAPUrl toGet) throws LDAPException
      Performs the search specified by the LDAP URL.

      For example, the following section of code searches for all entries under the ou=Product Development,o=Ace Industry,c=US subtree of a directory. The example gets and prints the mail attribute for each entry found.

       String flatURL = "ldap://alway.mcom.com:3890/ou=Product Development,o=Ace Industry,c=US?mail?sub?objectclass=*";
       LDAPUrl myURL;
       try {
          myURL = new LDAPUrl( flatURL );
       } catch ( java.net.MalformedURLException e ) {
          System.out.println( "Incorrect URL syntax." );
          return;
       }
      
       LDAPSearchResults myResults = null;
       try {
          myResults = myConn.search( myURL );
       } catch ( LDAPException e ) {
          int errCode = e.getLDAPResultCode();
          System.out.println( "LDAPException: return code:" + errCode );
          return;
       }
      
       while ( myResults.hasMoreElements() ) {
          LDAPEntry myEntry = myResults.next();
          String nextDN = myEntry.getDN();
          System.out.println( nextDN );
          LDAPAttributeSet entryAttrs = myEntry.getAttributeSet();
          Enumeration attrsInSet = entryAttrs.getAttributes();
          while ( attrsInSet.hasMoreElements() ) {
              LDAPAttribute nextAttr = (LDAPAttribute)attrsInSet.nextElement();
              String attrName = nextAttr.getName();
              System.out.print( "\t" + attrName + ": " );
              Enumeration valsInAttr = nextAttr.getStringValues();
              while ( valsInAttr.hasMoreElements() ) {
                  String nextValue = (String)valsInAttr.nextElement();
                  System.out.println( nextValue );
              }
          }
       }
       

      To abandon the search, use the abandon method.

      Parameters:
      toGet - LDAP URL representing the search to perform
      Returns:
      LDAPSearchResults the results of the search as an enumeration.
      Throws:
      LDAPException - Failed to complete the search specified by the LDAP URL.
      See Also:
    • search

      public static LDAPSearchResults search(LDAPUrl toGet, LDAPSearchConstraints cons) throws LDAPException
      Performs the search specified by the LDAP URL. This method also allows you to specify constraints for the search (such as the maximum number of entries to find or the maximum time to wait for search results).

      As part of the search constraints, you can specify whether or not you want the results delivered all at once or in smaller batches. If you specify the results delivered in smaller batches, each iteration blocks until the next batch of results is returned.

      For example, the following section of code retrieves the first 5 matching entries for the search specified by the LDAP URL. The example accomplishes this by creating a new set of search constraints where the maximum number of search results is 5.

       LDAPSearchConstraints mySearchConstraints = myConn.getSearchConstraints();
       mySearchConstraints.setMaxResults( 5 );
       String flatURL = "ldap://alway.mcom.com:3890/ou=Product Development,o=Ace Industry,c=US?mail?sub?objectclass=*";
       LDAPUrl myURL;
       try {
          myURL = new LDAPUrl( flatURL );
       } catch ( java.net.MalformedURLException e ) {
          System.out.println( "Incorrect URL syntax." );
          return;
       }
       LDAPSearchResults myResults = null;
       try {
          myResults = myConn.search( myURL, mySearchConstraints );
       } catch ( LDAPException e ) {
          int errCode = e.getLDAPResultCode();
          System.out.println( "LDAPException: return code:" + errCode );
          return;
       }
       

      To abandon the search, use the abandon method.

      Parameters:
      toGet - LDAP URL representing the search to run
      cons - constraints specific to the search
      Returns:
      LDAPSearchResults the results of the search as an enumeration.
      Throws:
      LDAPException - Failed to complete the search specified by the LDAP URL.
      See Also:
    • search

      public LDAPSearchResults search(String base, int scope, String filter, String[] attrs, boolean attrsOnly) throws LDAPException
      Performs the search specified by the criteria that you enter.

      For example, the following section of code searches for all entries under the ou=Product Development,o=Ace Industry,c=US subtree of a directory. The example gets and prints the mail attribute for each entry found.

       String myBaseDN = "ou=Product Development,o=Ace Industry,c=US";
       String myFilter="(objectclass=*)";
       String[] myAttrs = { "mail" };
      
       LDAPSearchResults myResults = null;
       try {
          myResults = myConn.search( myBaseDN, LDAPv2.SCOPE_SUB, myFilter, myAttrs, false );
       } catch ( LDAPException e ) {
          int errCode = e.getLDAPResultCode();
          System.out.println( "LDAPException: return code:" + errCode );
          return;
       }
      
       while ( myResults.hasMoreElements() ) {
          LDAPEntry myEntry = myResults.next();
          String nextDN = myEntry.getDN();
          System.out.println( nextDN );
          LDAPAttributeSet entryAttrs = myEntry.getAttributeSet();
          Enumeration attrsInSet = entryAttrs.getAttributes();
          while ( attrsInSet.hasMoreElements() ) {
              LDAPAttribute nextAttr = (LDAPAttribute)attrsInSet.nextElement();
              String attrName = nextAttr.getName();
              System.out.println( "\t" + attrName + ":" );
              Enumeration valsInAttr = nextAttr.getStringValues();
              while ( valsInAttr.hasMoreElements() ) {
                  String nextValue = (String)valsInAttr.nextElement();
                  System.out.println( "\t\t" + nextValue );
              }
          }
       }
       

      To abandon the search, use the abandon method.

      Specified by:
      search in interface LDAPv2
      Parameters:
      base - the base distinguished name from which to search
      scope - the scope of the entries to search. You can specify one of the following:

      • LDAPv2.SCOPE_BASE (search only the base DN)

      • LDAPv2.SCOPE_ONE (search only entries under the base DN)

      • LDAPv2.SCOPE_SUB (search the base DN and all entries within its subtree)

      filter - search filter specifying the search criteria
      attrs - list of attributes that you want returned in the search results
      attrsOnly - if true, returns the names but not the values of the attributes found. If false, returns the names and values for attributes found
      Returns:
      LDAPSearchResults the results of the search as an enumeration.
      Throws:
      LDAPException - Failed to complete the specified search.
      See Also:
    • search

      public LDAPSearchResults search(String base, int scope, String filter, String[] attrs, boolean attrsOnly, LDAPSearchConstraints cons) throws LDAPException
      Performs the search specified by the criteria that you enter. This method also allows you to specify constraints for the search (such as the maximum number of entries to find or the maximum time to wait for search results).

      As part of the search constraints, you can specify whether or not you want the results delivered all at once or in smaller batches. If you specify that you want the results delivered in smaller batches, each iteration blocks until the next batch of results is returned.

      For example, the following section of code retrieves the first 5 entries matching the specified search criteria. The example accomplishes this by creating a new set of search constraints where the maximum number of search results is 5.

       String myBaseDN = "ou=Product Development,o=Ace Industry,c=US";
       String myFilter="(objectclass=*)";
       String[] myAttrs = { "mail" };
       LDAPSearchConstraints mySearchConstraints = myConn.getSearchConstraints();
       mySearchConstraints.setMaxResults( 5 );
      
       LDAPSearchResults myResults = null;
       try {
          myResults = myConn.search( myBaseDN, LDAPv2.SCOPE_SUB, myFilter, myAttrs, false, mySearchConstraints );
       } catch ( LDAPException e ) {
          int errCode = e.getLDAPResultCode();
          System.out.println( "LDAPException: return code:" + errCode );
          return;
       }
       

      To abandon the search, use the abandon method.

      Specified by:
      search in interface LDAPv2
      Parameters:
      base - the base distinguished name from which to search
      scope - the scope of the entries to search. You can specify one of the following:

      • LDAPv2.SCOPE_BASE (search only the base DN)

      • LDAPv2.SCOPE_ONE (search only entries under the base DN)

      • LDAPv2.SCOPE_SUB (search the base DN and all entries within its subtree)

      filter - search filter specifying the search criteria
      attrs - list of attributes to return in the search results
      cons - constraints specific to this search (for example, the maximum number of entries to return)
      attrsOnly - if true, returns the names but not the values of the attributes found. If false, returns the names and values for attributes found
      Returns:
      LDAPSearchResults the results of the search as an enumeration.
      Throws:
      LDAPException - Failed to complete the specified search.
      See Also:
    • compare

      public boolean compare(String DN, LDAPAttribute attr) throws LDAPException
      Checks to see if an entry contains an attribute with a specified value. Returns true if the entry has the value. Returns false if the entry does not have the value or the attribute. To represent the value that you want compared, you need to create an LDAPAttribute object.

      Note that only string values can be compared.

      For example, the following section of code checks to see if the entry "cn=Barbara Jensen,ou=Product Development,o=Ace Industry,c=US" contains the attribute "mail" with the value "bjensen@aceindustry.com".

       ...
       LDAPConnection myConn = new LDAPConnection();
       ...
       String myDN = "cn=Barbara Jensen,ou=Product Development,o=Ace Industry,c=US";
       String nameOfAttr = "mail";
       String valOfAttr = "bjensen@aceindustry.com";
       LDAPAttribute cmpThisAttr = new LDAPAttribute( nameOfAttr, valOfAttr );
       boolean hasValue = myConn.compare( myDN, cmpThisAttr );
       if ( hasValue ) {
           System.out.println( "Attribute and value found in entry." );
       } else {
           System.out.println( "Attribute and value not found in entry." );
       }
       ...
      Specified by:
      compare in interface LDAPv2
      Parameters:
      DN - the distinguished name of the entry to use in the comparison
      attr - the attribute to compare against the entry. (The method checks to see if the entry has an attribute with the same name and value as this attribute.)
      Returns:
      true if the entry contains the specified attribute and value.
      Throws:
      LDAPException - Failed to perform the comparison.
      See Also:
    • compare

      public boolean compare(String DN, LDAPAttribute attr, LDAPConstraints cons) throws LDAPException
      Description copied from interface: LDAPv2
      Compares the given entry's attribute value to the specified attribute value.
      Specified by:
      compare in interface LDAPv2
      Parameters:
      DN - distinguished name of the entry that you want compared against the specified attribute value
      attr - attribute name and value to use in the comparison
      cons - the constraints set for the compare operation
      Throws:
      LDAPException - Failed to perform the comparison.
    • compare

      @Deprecated public boolean compare(String DN, LDAPAttribute attr, LDAPSearchConstraints cons) throws LDAPException
      Deprecated.
      Please use the method signature where cons is LDAPConstraints instead of LDAPSearchConstraints
      Throws:
      LDAPException
    • add

      public void add(LDAPEntry entry) throws LDAPException
      Adds an entry to the directory.

      Before using this method, you need to create an LDAPEntry object and use it to specify the distinguished name and attributes of the new entry. Make sure to specify values for all required attributes in the entry. If all required attributes are not specified and the LDAP server checks the entry against the schema, an LDAPException may be thrown (where the LDAP result code is OBJECT_CLASS_VIOLATION).

      For example, the following section of code creates an LDAPEntry object for a new entry and uses the object to add the new entry to the directory. Because the definition of the LDAP inetOrgPerson class specifies that the cn, sn, and objectclass attributes are required, these attributes are specified as part of the new entry. (mail is not required but is shown here as an example of specifying additional attributes.)

       ...
       String myDN = "cn=Barbara Jensen,ou=Product Development,o=Ace Industry,c=US";
      
       LDAPAttribute attr1 = new LDAPAttribute( "cn", "Barbara Jensen" );
       LDAPAttribute attr2 = new LDAPAttribute( "sn", "Jensen" );
       LDAPAttribute attr3 = new LDAPAttribute( "objectclass", "top" );
       LDAPAttribute attr4 = new LDAPAttribute( "objectclass", "person" );
       LDAPAttribute attr5 = new LDAPAttribute( "objectclass", "organizationalPerson" );
       LDAPAttribute attr6 = new LDAPAttribute( "objectclass", "inetOrgPerson" );
       LDAPAttribute attr7 = new LDAPAttribute( "mail", "bjensen@aceindustry.com" );
      
       LDAPAttributeSet myAttrs = new LDAPAttributeSet();
       myAttrs.add( attr1 );
       myAttrs.add( attr2 );
       myAttrs.add( attr3 );
       myAttrs.add( attr4 );
       myAttrs.add( attr5 );
       myAttrs.add( attr6 );
       myAttrs.add( attr7 );
      
       LDAPEntry myEntry = new LDAPEntry( myDN, myAttrs );
      
       myConn.add( myEntry );
       ... 
      Specified by:
      add in interface LDAPv2
      Parameters:
      entry - LDAPEntry object specifying the distinguished name and attributes of the new entry
      Throws:
      LDAPException - Failed to add the specified entry to the directory.
      See Also:
    • add

      public void add(LDAPEntry entry, LDAPConstraints cons) throws LDAPException
      Adds an entry to the directory and allows you to specify preferences for this LDAP add operation by using an LDAPConstraints object. For example, you can specify whether or not to follow referrals. You can also apply LDAP v3 controls to the operation.

      Specified by:
      add in interface LDAPv2
      Parameters:
      entry - LDAPEntry object specifying the distinguished name and attributes of the new entry
      cons - the set of preferences to apply to this operation
      Throws:
      LDAPException - Failed to add the specified entry to the directory.
      See Also:
    • add

      @Deprecated public void add(LDAPEntry entry, LDAPSearchConstraints cons) throws LDAPException
      Deprecated.
      Please use the method signature where cons is LDAPConstraints instead of LDAPSearchConstraints
      Throws:
      LDAPException
    • extendedOperation

      public LDAPExtendedOperation extendedOperation(LDAPExtendedOperation op) throws LDAPException
      Performs an extended operation on the directory. Extended operations are part of version 3 of the LDAP protocol.

      Note that in order for the extended operation to work, the server that you are connecting to must support LDAP v3 and must be configured to process the specified extended operation.

      Specified by:
      extendedOperation in interface LDAPv3
      Parameters:
      op - LDAPExtendedOperation object specifying the OID of the extended operation and the data to use in the operation
      Returns:
      LDAPExtendedOperation object representing the extended response returned by the server.
      Throws:
      LDAPException - Failed to execute the operation
      See Also:
    • extendedOperation

      public LDAPExtendedOperation extendedOperation(LDAPExtendedOperation op, LDAPConstraints cons) throws LDAPException
      Performs an extended operation on the directory. Extended operations are part of version 3 of the LDAP protocol. This method allows the user to set the preferences for the operation.

      Note that in order for the extended operation to work, the server that you are connecting to must support LDAP v3 and must be configured to process the specified extended operation.

      Parameters:
      op - LDAPExtendedOperation object specifying the OID of the extended operation and the data to use in the operation
      cons - preferences for the extended operation
      Returns:
      LDAPExtendedOperation object representing the extended response returned by the server.
      Throws:
      LDAPException - Failed to execute the operation
      See Also:
    • extendedOperation

      Deprecated.
      Please use the method signature where cons is LDAPConstraints instead of LDAPSearchConstraints
      Throws:
      LDAPException
    • modify

      public void modify(String DN, LDAPModification mod) throws LDAPException
      Makes a single change to an existing entry in the directory. For example, changes the value of an attribute, adds a new attribute value, or removes an existing attribute value.

      Use the LDAPModification object to specify the change to make and the LDAPAttribute object to specify the attribute value to change. The LDAPModification object allows you add an attribute value, change an attibute value, or remove an attribute value.

      For example, the following section of code changes Barbara Jensen's email address in the directory to babs@aceindustry.com.

       ...
       String myEntryDN = "cn=Barbara Jensen,ou=Product Development,o=Ace Industry,c=US";
      
       LDAPAttribute attrEmail = new LDAPAttribute( "mail", "babs@aceindustry.com" );
       LDAPModification singleChange = new LDAPModification( LDAPModification.REPLACE, attrEmail );
      
       myConn.modify( myEntryDN, singleChange );
       ... 
      Specified by:
      modify in interface LDAPv2
      Parameters:
      DN - the distinguished name of the entry to modify
      mod - a single change to make to the entry
      Throws:
      LDAPException - Failed to make the specified change to the directory entry.
      See Also:
    • modify

      public void modify(String DN, LDAPModification mod, LDAPConstraints cons) throws LDAPException
      Makes a single change to an existing entry in the directory and allows you to specify preferences for this LDAP modify operation by using an LDAPConstraints object. For example, you can specify whether or not to follow referrals. You can also apply LDAP v3 controls to the operation.

      Specified by:
      modify in interface LDAPv2
      Parameters:
      DN - the distinguished name of the entry to modify
      mod - a single change to make to the entry
      cons - the set of preferences to apply to this operation
      Throws:
      LDAPException - Failed to make the specified change to the directory entry.
      See Also:
    • modify

      @Deprecated public void modify(String DN, LDAPModification mod, LDAPSearchConstraints cons) throws LDAPException
      Deprecated.
      Please use the method signature where cons is LDAPConstraints instead of LDAPSearchConstraints
      Throws:
      LDAPException
    • modify

      public void modify(String DN, LDAPModificationSet mods) throws LDAPException
      Makes a set of changes to an existing entry in the directory. For example, changes attribute values, adds new attribute values, or removes existing attribute values.

      Use the LDAPModificationSet object to specify the set of changes to make. Changes are specified in terms of attribute values. You must specify each attribute value to modify, add, or remove by an LDAPAttribute object.

      For example, the following section of code changes Barbara Jensen's title, adds a telephone number to the entry, and removes the room number from the entry.

       ...
       String myEntryDN = "cn=Barbara Jensen,ou=Product Development,o=Ace Industry,c=US";
      
       LDAPModificationSet manyChanges = new LDAPModificationSet();
       LDAPAttribute attrTelephoneNumber = new LDAPAttribute( "telephoneNumber",
                                                              "555-1212" );
       manyChanges.add( LDAPModification.ADD, attrTelephoneNumber );
       LDAPAttribute attrRoomNumber = new LDAPAttribute( "roomnumber", "222" );
       manyChanges.add( LDAPModification.DELETE, attrRoomNumber );
       LDAPAttribute attrTitle = new LDAPAttribute( "title",
                                             "Manager of Product Development" );
       manyChanges.add( LDAPModification.REPLACE, attrTitle );
      
       myConn.modify( myEntryDN, manyChanges );
       ... 
      Specified by:
      modify in interface LDAPv2
      Parameters:
      DN - the distinguished name of the entry to modify
      mods - a set of changes to make to the entry
      Throws:
      LDAPException - Failed to make the specified changes to the directory entry.
      See Also:
    • modify

      public void modify(String DN, LDAPModificationSet mods, LDAPConstraints cons) throws LDAPException
      Makes a set of changes to an existing entry in the directory and allows you to specify preferences for this LDAP modify operation by using an LDAPConstraints object. For example, you can specify whether or not to follow referrals. You can also apply LDAP v3 controls to the operation.

      Specified by:
      modify in interface LDAPv2
      Parameters:
      DN - the distinguished name of the entry to modify
      mods - a set of changes to make to the entry
      cons - the set of preferences to apply to this operation
      Throws:
      LDAPException - Failed to make the specified changes to the directory entry.
      See Also:
    • modify

      @Deprecated public void modify(String DN, LDAPModificationSet mods, LDAPSearchConstraints cons) throws LDAPException
      Deprecated.
      Please use the method signature where cons is LDAPConstraints instead of LDAPSearchConstraints
      Throws:
      LDAPException
    • modify

      public void modify(String DN, LDAPModification[] mods) throws LDAPException
      Makes a set of changes to an existing entry in the directory. For example, changes attribute values, adds new attribute values, or removes existing attribute values.

      Use an array of LDAPModification objects to specify the changes to make. Each change must be specified by an LDAPModification object, and you must specify each attribute value to modify, add, or remove by an LDAPAttribute object.

      Parameters:
      DN - the distinguished name of the entry to modify
      mods - an array of objects representing the changes to make to the entry
      Throws:
      LDAPException - Failed to make the specified changes to the directory entry.
      See Also:
    • modify

      public void modify(String DN, LDAPModification[] mods, LDAPConstraints cons) throws LDAPException
      Makes a set of changes to an existing entry in the directory and allows you to specify preferences for this LDAP modify operation by using an LDAPConstraints object. For example, you can specify whether or not to follow referrals. You can also apply LDAP v3 controls to the operation.

      Parameters:
      DN - the distinguished name of the entry to modify
      mods - an array of objects representing the changes to make to the entry
      cons - the set of preferences to apply to this operation
      Throws:
      LDAPException - Failed to make the specified changes to the directory entry.
      See Also:
    • modify

      @Deprecated public void modify(String DN, LDAPModification[] mods, LDAPSearchConstraints cons) throws LDAPException
      Deprecated.
      Please use the method signature where cons is LDAPConstraints instead of LDAPSearchConstraints
      Throws:
      LDAPException
    • delete

      public void delete(String DN) throws LDAPException
      Deletes the entry for the specified DN from the directory.

      For example, the following section of code deletes the entry for Barbara Jensen from the directory.

       ...
       String myEntryDN = "cn=Barbara Jensen,ou=Product Development,o=Ace Industry,c=US";
       myConn.delete( myEntryDN );
       ... 
      Specified by:
      delete in interface LDAPv2
      Parameters:
      DN - distinguished name identifying the entry to remove from the directory
      Throws:
      LDAPException - Failed to delete the specified entry from the directory.
    • delete

      public void delete(String DN, LDAPConstraints cons) throws LDAPException
      Deletes the entry for the specified DN from the directory and allows you to specify preferences for this LDAP delete operation by using an LDAPConstraints object. For example, you can specify whether or not to follow referrals. You can also apply LDAP v3 controls to the operation.

      Specified by:
      delete in interface LDAPv2
      Parameters:
      DN - distinguished name identifying the entry to remove from the directory
      cons - the set of preferences to apply to this operation
      Throws:
      LDAPException - Failed to delete the specified entry from the directory.
      See Also:
    • delete

      @Deprecated public void delete(String DN, LDAPSearchConstraints cons) throws LDAPException
      Deprecated.
      Please use the method signature where cons is LDAPConstraints instead of LDAPSearchConstraints
      Throws:
      LDAPException
    • rename

      public void rename(String DN, String newRDN, boolean deleteOldRDN) throws LDAPException
      Renames an existing entry in the directory.

      You can specify whether or not the original name of the entry is retained as a value in the entry. For example, suppose you rename the entry "cn=Barbara" to "cn=Babs". You can keep "cn=Barbara" as a value in the entry so that the cn attribute has two values:

             cn=Barbara
             cn=Babs
       
      The following example renames an entry. The old name of the entry is kept as a value in the entry.

       ...
       String myEntryDN = "cn=Barbara Jensen,ou=Product Development,o=Ace Industry,c=US";
       String newRDN = "cn=Babs Jensen";
       myConn.rename( myEntryDN, newRDN, false );
       ... 
      Specified by:
      rename in interface LDAPv2
      Parameters:
      DN - current distinguished name of the entry
      newRDN - new relative distinguished name for the entry (for example, "cn=newName")
      deleteOldRDN - if true, the old name is not retained as an attribute value (for example, the attribute value "cn=oldName" is removed). If false, the old name is retained as an attribute value (for example, the entry might now have two values for the cn attribute: "cn=oldName" and "cn=newName").
      Throws:
      LDAPException - Failed to rename the specified entry.
    • rename

      public void rename(String DN, String newRDN, boolean deleteOldRDN, LDAPConstraints cons) throws LDAPException
      Renames an existing entry in the directory.

      You can specify whether or not the original name of the entry is retained as a value in the entry. For example, suppose you rename the entry "cn=Barbara" to "cn=Babs". You can keep "cn=Barbara" as a value in the entry so that the cn attribute has two values:

             cn=Barbara
             cn=Babs
       
      The following example renames an entry. The old name of the entry is kept as a value in the entry.

       ...
       String myEntryDN = "cn=Barbara Jensen,ou=Product Development,o=Ace Industry,c=US";
       String newRDN = "cn=Babs Jensen";
       myConn.rename( myEntryDN, newRDN, false );
       ... 
      Specified by:
      rename in interface LDAPv2
      Parameters:
      DN - current distinguished name of the entry
      newRDN - new relative distinguished name for the entry (for example, "cn=newName")
      deleteOldRDN - if true, the old name is not retained as an attribute value (for example, the attribute value "cn=oldName" is removed). If false, the old name is retained as an attribute value (for example, the entry might now have two values for the cn attribute: "cn=oldName" and "cn=newName").
      cons - the set of preferences to apply to this operation
      Throws:
      LDAPException - Failed to rename the specified entry.
    • rename

      @Deprecated public void rename(String DN, String newRDN, boolean deleteOldRDN, LDAPSearchConstraints cons) throws LDAPException
      Deprecated.
      Please use the method signature where cons is LDAPConstraints instead of LDAPSearchConstraints
      Throws:
      LDAPException
    • rename

      public void rename(String dn, String newRDN, String newParentDN, boolean deleteOldRDN) throws LDAPException
      Renames an existing entry in the directory and (optionally) changes the location of the entry in the directory tree.

      NOTE: Netscape Directory Server 3.0 does not support the capability to move an entry to a different location in the directory tree. If you specify a value for the newParentDN argument, an LDAPException will be thrown.

      Specified by:
      rename in interface LDAPv3
      Parameters:
      dn - current distinguished name of the entry
      newRDN - new relative distinguished name for the entry (for example, "cn=newName")
      newParentDN - if not null, the distinguished name for the entry under which the entry should be moved (for example, to move an entry under the Accounting subtree, specify this argument as "ou=Accounting, o=Ace Industry, c=US")
      deleteOldRDN - if true, the old name is not retained as an attribute value (for example, the attribute value "cn=oldName" is removed). If false, the old name is retained as an attribute value (for example, the entry might now have two values for the cn attribute: "cn=oldName" and "cn=newName").
      Throws:
      LDAPException - Failed to rename the specified entry.
    • rename

      public void rename(String DN, String newRDN, String newParentDN, boolean deleteOldRDN, LDAPConstraints cons) throws LDAPException
      Renames an existing entry in the directory and (optionally) changes the location of the entry in the directory tree. Also allows you to specify preferences for this LDAP modify DN operation by using an LDAPConstraints object. For example, you can specify whether or not to follow referrals. You can also apply LDAP v3 controls to the operation.

      NOTE: Netscape Directory Server 3.0 does not support the capability to move an entry to a different location in the directory tree. If you specify a value for the newParentDN argument, an LDAPException will be thrown.

      Specified by:
      rename in interface LDAPv3
      Parameters:
      DN - current distinguished name of the entry
      newRDN - new relative distinguished name for the entry (for example, "cn=newName")
      newParentDN - if not null, the distinguished name for the entry under which the entry should be moved (for example, to move an entry under the Accounting subtree, specify this argument as "ou=Accounting, o=Ace Industry, c=US")
      deleteOldRDN - if true, the old name is not retained as an attribute value (for example, the attribute value "cn=oldName" is removed). If false, the old name is retained as an attribute value (for example, the entry might now have two values for the cn attribute: "cn=oldName" and "cn=newName").
      cons - the set of preferences to apply to this operation
      Throws:
      LDAPException - Failed to rename the specified entry.
      See Also:
    • rename

      @Deprecated public void rename(String DN, String newRDN, String newParentDN, boolean deleteOldRDN, LDAPSearchConstraints cons) throws LDAPException
      Deprecated.
      Please use the method signature where cons is LDAPConstraints instead of LDAPSearchConstraints
      Throws:
      LDAPException
    • add

      public LDAPResponseListener add(LDAPEntry entry, LDAPResponseListener listener) throws LDAPException
      Adds an entry to the directory.
      Specified by:
      add in interface LDAPAsynchronousConnection
      Parameters:
      entry - LDAPEntry object specifying the distinguished name and attributes of the new entry
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      Returns:
      LDAPResponseListener handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • add

      Adds an entry to the directory and allows you to specify constraints for this LDAP add operation by using an LDAPConstraints object. For example, you can specify whether or not to follow referrals. You can also apply LDAP v3 controls to the operation.

      Specified by:
      add in interface LDAPAsynchronousConnection
      Parameters:
      entry - LDAPEntry object specifying the distinguished name and attributes of the new entry
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      cons - constraints specific to the operation
      Returns:
      LDAPResponseListener handler for messages returned from a server in response to this request
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • bind

      public LDAPResponseListener bind(int version, String dn, String passwd, LDAPResponseListener listener) throws LDAPException
      Authenticates to the LDAP server (to which the object is currently connected) using the specified name and password. If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object had already authenticated, the old authentication is discarded.
      Parameters:
      version - required LDAP protocol version
      dn - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name
      passwd - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name and passwd as password
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      Returns:
      LDAPResponseListener handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • bind

      public LDAPResponseListener bind(String dn, String passwd, LDAPResponseListener listener) throws LDAPException
      Authenticates to the LDAP server (to which the object is currently connected) using the specified name and password. If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object had already authenticated, the old authentication is discarded.
      Specified by:
      bind in interface LDAPAsynchronousConnection
      Parameters:
      dn - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name
      passwd - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name and passwd as password
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      Returns:
      LDAPResponseListener handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • bind

      public LDAPResponseListener bind(String dn, String passwd, LDAPResponseListener listener, LDAPConstraints cons) throws LDAPException
      Authenticates to the LDAP server (to which the object is currently connected) using the specified name and password and allows you to specify constraints for this LDAP add operation by using an LDAPConstraints object. If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object had already authenticated, the old authentication is discarded.
      Specified by:
      bind in interface LDAPAsynchronousConnection
      Parameters:
      dn - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name
      passwd - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name and passwd as password
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      cons - constraints specific to the operation
      Returns:
      LDAPResponseListener handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • bind

      public LDAPResponseListener bind(int version, String dn, String passwd, LDAPResponseListener listener, LDAPConstraints cons) throws LDAPException
      Authenticates to the LDAP server (to which the object is currently connected) using the specified name and password and allows you to specify constraints for this LDAP add operation by using an LDAPConstraints object. If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object had already authenticated, the old authentication is discarded.
      Parameters:
      version - required LDAP protocol version
      dn - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name
      passwd - if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished name and passwd as password
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      cons - constraints specific to the operation
      Returns:
      LDAPResponseListener handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • delete

      public LDAPResponseListener delete(String dn, LDAPResponseListener listener) throws LDAPException
      Deletes the entry for the specified DN from the directory.
      Specified by:
      delete in interface LDAPAsynchronousConnection
      Parameters:
      dn - distinguished name of the entry to delete
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      Returns:
      LDAPResponseListener handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • delete

      public LDAPResponseListener delete(String dn, LDAPResponseListener listener, LDAPConstraints cons) throws LDAPException
      Deletes the entry for the specified DN from the directory.
      Specified by:
      delete in interface LDAPAsynchronousConnection
      Parameters:
      dn - distinguished name of the entry to delete
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      cons - constraints specific to the operation
      Returns:
      LDAPResponseListener handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • modify

      Makes a single change to an existing entry in the directory. For example, changes the value of an attribute, adds a new attribute value, or removes an existing attribute value.
      The LDAPModification object specifies both the change to make and the LDAPAttribute value to be changed.
      Specified by:
      modify in interface LDAPAsynchronousConnection
      Parameters:
      dn - distinguished name of the entry to modify
      mod - a single change to make to an entry
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      Returns:
      LDAPResponseListener handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • modify

      Makes a single change to an existing entry in the directory. For example, changes the value of an attribute, adds a new attribute value, or removes an existing attribute value.
      The LDAPModification object specifies both the change to make and the LDAPAttribute value to be changed.
      Specified by:
      modify in interface LDAPAsynchronousConnection
      Parameters:
      dn - distinguished name of the entry to modify
      mod - a single change to make to an entry
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      cons - constraints specific to the operation
      Returns:
      LDAPResponseListener handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • modify

      Makes a set of changes to an existing entry in the directory. For example, changes attribute values, adds new attribute values, or removes existing attribute values.

      Specified by:
      modify in interface LDAPAsynchronousConnection
      Parameters:
      dn - distinguished name of the entry to modify
      mods - a set of changes to make to the entry
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      Returns:
      LDAPResponseListener handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • modify

      Makes a set of changes to an existing entry in the directory. For example, changes attribute values, adds new attribute values, or removes existing attribute values).
      Specified by:
      modify in interface LDAPAsynchronousConnection
      Parameters:
      dn - distinguished name of the entry to modify
      mods - a set of changes to make to the entry
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      cons - Constraints specific to the operation
      Returns:
      LDAPResponseListener handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • rename

      public LDAPResponseListener rename(String dn, String newRdn, boolean deleteOldRdn, LDAPResponseListener listener) throws LDAPException
      Renames an existing entry in the directory.
      Specified by:
      rename in interface LDAPAsynchronousConnection
      Parameters:
      dn - current distinguished name of the entry
      newRdn - new relative distinguished name for the entry
      deleteOldRdn - if true, the old name is not retained as an attribute value
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      Returns:
      LDAPResponseListener handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • rename

      public LDAPResponseListener rename(String dn, String newRdn, boolean deleteOldRdn, LDAPResponseListener listener, LDAPConstraints cons) throws LDAPException
      Renames an existing entry in the directory.
      Specified by:
      rename in interface LDAPAsynchronousConnection
      Parameters:
      dn - current distinguished name of the entry
      newRdn - new relative distinguished name for the entry
      deleteOldRdn - if true, the old name is not retained as an attribute value
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      cons - constraints specific to the operation
      Returns:
      LDAPResponseListener handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • search

      public LDAPSearchListener search(String base, int scope, String filter, String[] attrs, boolean typesOnly, LDAPSearchListener listener) throws LDAPException
      Performs the search specified by the criteria that you enter.

      To abandon the search, use the abandon method.

      Specified by:
      search in interface LDAPAsynchronousConnection
      Parameters:
      base - the base distinguished name from which to search
      scope - the scope of the entries to search. You can specify one of the following:

      • LDAPv2.SCOPE_BASE (search only the base DN)

      • LDAPv2.SCOPE_ONE (search only entries under the base DN)

      • LDAPv2.SCOPE_SUB (search the base DN and all entries within its subtree)

      filter - search filter specifying the search criteria
      attrs - list of attributes that you want returned in the search results
      typesOnly - if true, returns the names but not the values of the attributes found. If false, returns the names and values for attributes found
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      Returns:
      LDAPSearchListener handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • search

      public LDAPSearchListener search(String base, int scope, String filter, String[] attrs, boolean typesOnly, LDAPSearchListener listener, LDAPSearchConstraints cons) throws LDAPException
      Performs the search specified by the criteria that you enter. This method also allows you to specify constraints for the search (such as the maximum number of entries to find or the maximum time to wait for search results).

      To abandon the search, use the abandon method.

      Specified by:
      search in interface LDAPAsynchronousConnection
      Parameters:
      base - the base distinguished name from which to search
      scope - the scope of the entries to search. You can specify one of the following:

      • LDAPv2.SCOPE_BASE (search only the base DN)

      • LDAPv2.SCOPE_ONE (search only entries under the base DN)

      • LDAPv2.SCOPE_SUB (search the base DN and all entries within its subtree)

      filter - search filter specifying the search criteria
      attrs - list of attributes that you want returned in the search results
      typesOnly - if true, returns the names but not the values of the attributes found. If false, returns the names and values for attributes found.
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      cons - constraints specific to this search (for example, the maximum number of entries to return)
      Returns:
      LDAPSearchListener handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
      See Also:
    • compare

      public LDAPResponseListener compare(String dn, LDAPAttribute attr, LDAPResponseListener listener) throws LDAPException
      Compare an attribute value with one in the directory. The result can be obtained by calling getResultCode on the LDAPResponse from the LDAPResponseListener. The code will be LDAPException.COMPARE_TRUE or LDAPException.COMPARE_FALSE.
      Specified by:
      compare in interface LDAPAsynchronousConnection
      Parameters:
      dn - distinguished name of the entry to compare
      attr - attribute with a value to compare
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      Returns:
      LDAPResponseListener handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
    • compare

      public LDAPResponseListener compare(String dn, LDAPAttribute attr, LDAPResponseListener listener, LDAPConstraints cons) throws LDAPException
      Compare an attribute value with one in the directory. The result can be obtained by calling getResultCode on the LDAPResponse from the LDAPResponseListener. The code will be LDAPException.COMPARE_TRUE or LDAPException.COMPARE_FALSE.
      Specified by:
      compare in interface LDAPAsynchronousConnection
      Parameters:
      dn - distinguished name of the entry to compare
      attr - attribute with a value to compare
      listener - handler for messages returned from a server in response to this request. If it is null, a listener object is created internally.
      cons - constraints specific to this operation
      Returns:
      LDAPResponseListener handler for messages returned from a server in response to this request.
      Throws:
      LDAPException - Failed to send request.
    • abandon

      public void abandon(int id) throws LDAPException
      Cancels the ldap request with the specified id and discards any results already received.
      Specified by:
      abandon in interface LDAPAsynchronousConnection
      Parameters:
      id - an LDAP request id
      Throws:
      LDAPException - Failed to send request.
    • abandon

      public void abandon(LDAPSearchListener searchlistener) throws LDAPException
      Cancels all outstanding search requests associated with this LDAPSearchListener object and discards any results already received.
      Specified by:
      abandon in interface LDAPAsynchronousConnection
      Parameters:
      searchlistener - a search listener returned from a search
      Throws:
      LDAPException - Failed to send request.
    • getOption

      public Object getOption(int option) throws LDAPException
      Returns the value of the specified option for this LDAPConnection object.

      These options represent the constraints for the current connection. To get all constraints for the current connection, call the getSearchConstraints method.

      By default, the constraints apply to all operations performed through the current connection. You can change these constraints:

      • If you want to set a constraint only for a particular operation, create an LDAPConstraints object (or a LDAPSearchConstraints object for a search or find operation) with your new constraints and pass it to the LDAPConnection method that performs the operation.

      • If you want to override these constraints for all operations performed under the current connection, call the setOption method to change the constraint.

      For example, the following section of code gets and prints the maximum number of search results that are returned for searches performed through this connection. (This applies to all searches unless a different set of search constraints is specified in an LDAPSearchConstraints object.)

       LDAPConnection ld = new LDAPConnection();
       int sizeLimit = ( (Integer)ld.getOption( LDAPv2.SIZELIMIT ) ).intValue();
       System.out.println( "Maximum number of results: " + sizeLimit );
       
      Specified by:
      getOption in interface LDAPv2
      Parameters:
      option - you can specify one of the following options:
      OptionData TypeDescription
      LDAPv2.PROTOCOL_VERSION Integer Specifies the version of the LDAP protocol used by the client.

      By default, the value of this option is 2.

      LDAPv2.DEREF Integer Specifies when your client dereferences aliases.
       Legal values for this option are:
      
       DEREF_NEVER       Aliases are never dereferenced.
      
       DEREF_FINDING     Aliases are dereferenced when find-
                         ing the starting point for the
                         search (but not when searching
                         under that starting entry).
      
       DEREF_SEARCHING   Aliases are dereferenced when
                         searching the entries beneath the
                         starting point of the search (but
                         not when finding the starting
                         entry).
      
       DEREF_ALWAYS      Aliases are always dereferenced.
      

      By default, the value of this option is DEREF_NEVER.

      LDAPv2.SIZELIMIT Integer Specifies the maximum number of search results to return. If this option is set to 0, there is no maximum limit.

      By default, the value of this option is 1000.

      LDAPv2.TIMELIMIT Integer Specifies the maximum number of milliseconds to wait for results before timing out. If this option is set to 0, there is no maximum time limit.

      By default, the value of this option is 0.

      LDAPv2.REFERRALS Boolean Specifies whether or not your client follows referrals automatically. If true, your client follows referrals automatically. If false, an LDAPReferralException is raised when referral is detected.

      By default, the value of this option is false.

      LDAPv2.REFERRALS_REBIND_PROC LDAPRebind Specifies an object with a class that implements the LDAPRebind interface. You must define this class and the getRebindAuthentication method that will be used to get the distinguished name and password to use for authentication. Modifying this option sets the LDAPv2.BIND option to null.

      By default, the value of this option is null.

      LDAPv2.BIND LDAPBind Specifies an object with a class that implements the LDAPBind interface. You must define this class and the bind method that will be used to authenticate to the server on referrals. Modifying this option sets the LDAPv2.REFERRALS_REBIND_PROC to null.

      By default, the value of this option is null.

      LDAPv2.REFERRALS_HOP_LIMIT Integer Specifies the maximum number of referrals in a sequence that your client will follow. (For example, if REFERRALS_HOP_LIMIT is 5, your client will follow no more than 5 referrals in a row when resolving a single LDAP request.)

      By default, the value of this option is 10.

      LDAPv2.BATCHSIZE Integer Specifies the number of search results to return at a time. (For example, if BATCHSIZE is 1, results are returned one at a time.)

      By default, the value of this option is 1.

      LDAPv3.CLIENTCONTROLS LDAPControl[] Specifies the client controls that may affect the handling of LDAP operations in the LDAP classes. These controls are used by the client and are not passed to the LDAP server. At this time, no client controls are defined for clients built with the Netscape LDAP classes.
      LDAPv3.SERVERCONTROLS LDAPControl[] Specifies the server controls that are passed to the LDAP server on each LDAP operation. Not all servers support server controls; a particular server may or may not support a given server control.
      MAXBACKLOG Integer Specifies the maximum number of search results to accumulate in an LDAPSearchResults before suspending the reading of input from the server.

      By default, the value of this option is 100. The value 0 means there is no limit.

      Returns:
      the value for the option wrapped in an object. (You need to cast the returned value as its appropriate type. For example, when getting the SIZELIMIT option, cast the returned value as an Integer.)
      Throws:
      LDAPException - Failed to get the specified option.
      See Also:
    • setOption

      public void setOption(int option, Object value) throws LDAPException
      Sets the value of the specified option for this LDAPConnection object.

      These options represent the constraints for the current connection. To get all constraints for the current connection, call the getSearchConstraints method.

      By default, the option that you set applies to all subsequent operations performed through the current connection. If you want to set a constraint only for a particular operation, create an LDAPConstraints object (or a LDAPSearchConstraints object for a search or find operation) with your new constraints and pass it to the LDAPConnection method that performs the operation.

      For example, the following section of code changes the constraint for the maximum number of search results that are returned for searches performed through this connection. (This applies to all searches unless a different set of search constraints is specified in an LDAPSearchConstraints object.)

       LDAPConnection ld = new LDAPConnection();
       Integer newLimit = new Integer( 20 );
       ld.setOption( LDAPv2.SIZELIMIT, newLimit );
       System.out.println( "Changed the maximum number of results to " + newLimit.intValue() );
       
      Specified by:
      setOption in interface LDAPv2
      Parameters:
      option - you can specify one of the following options:
      OptionData TypeDescription
      LDAPv2.PROTOCOL_VERSION Integer Specifies the version of the LDAP protocol used by the client.

      By default, the value of this option is 2. If you want to use LDAP v3 features (such as extended operations or controls), you need to set this value to 3.

      LDAPv2.DEREF Integer Specifies when your client dereferences aliases.
       Legal values for this option are:
      
       DEREF_NEVER       Aliases are never dereferenced.
      
       DEREF_FINDING     Aliases are dereferenced when find-
                         ing the starting point for the
                         search (but not when searching
                         under that starting entry).
      
       DEREF_SEARCHING   Aliases are dereferenced when
                         searching the entries beneath the
                         starting point of the search (but
                         not when finding the starting
                         entry).
      
       DEREF_ALWAYS      Aliases are always dereferenced.
      

      By default, the value of this option is DEREF_NEVER.

      LDAPv2.SIZELIMIT Integer Specifies the maximum number of search results to return. If this option is set to 0, there is no maximum limit.

      By default, the value of this option is 1000.

      LDAPv2.TIMELIMIT Integer Specifies the maximum number of milliseconds to wait for results before timing out. If this option is set to 0, there is no maximum time limit.

      By default, the value of this option is 0.

      LDAPv2.REFERRALS Boolean Specifies whether or not your client follows referrals automatically. If true, your client follows referrals automatically. If false, an LDAPReferralException is raised when a referral is detected.

      By default, the value of this option is false.

      LDAPv2.REFERRALS_REBIND_PROC LDAPRebind Specifies an object with a class that implements the LDAPRebind interface. You must define this class and the getRebindAuthentication method that will be used to get the distinguished name and password to use for authentication. Modifying this option sets the LDAPv2.BIND option to null.

      By default, the value of this option is null.

      LDAPv2.BIND LDAPBind Specifies an object with a class that implements the LDAPBind interface. You must define this class and the bind method that will be used to autheniticate to the server on referrals. Modifying this option sets the LDAPv2.REFERRALS_REBIND_PROC to null.

      By default, the value of this option is null.

      LDAPv2.REFERRALS_HOP_LIMIT Integer Specifies the maximum number of referrals in a sequence that your client will follow. (For example, if REFERRALS_HOP_LIMIT is 5, your client will follow no more than 5 referrals in a row when resolving a single LDAP request.)

      By default, the value of this option is 10.

      LDAPv2.BATCHSIZE Integer Specifies the number of search results to return at a time. (For example, if BATCHSIZE is 1, results are returned one at a time.)

      By default, the value of this option is 1.

      LDAPv3.CLIENTCONTROLS LDAPControl[] Specifies the client controls that may affect handling of LDAP operations in the LDAP classes. These controls are used by the client and are not passed to the server. At this time, no client controls are defined for clients built with the Netscape LDAP classes.
      LDAPv3.SERVERCONTROLS LDAPControl[] Specifies the server controls that are passed to the LDAP server on each LDAP operation. Not all servers support server controls; a particular server may or may not support a particular control.
      MAXBACKLOG Integer Specifies the maximum number of search results to accumulate in an LDAPSearchResults before suspending the reading of input from the server.

      By default, the value of this option is 100. The value 0 means there is no limit.

      value - the value to assign to the option. The value must be the java.lang object wrapper for the appropriate parameter (e.g. boolean->Boolean, integer->Integer)
      Throws:
      LDAPException - Failed to set the specified option.
      See Also:
    • getResponseControls

      public LDAPControl[] getResponseControls()
      Returns an array of the latest controls (if any) from server.

      To retrieve the controls from a search result, call the getResponseControls method from the LDAPSearchResults object returned with the result.

      Specified by:
      getResponseControls in interface LDAPv3
      Returns:
      an array of the controls returned by an operation, or null if none.
      See Also:
    • getConstraints

      public LDAPConstraints getConstraints()
      Returns the set of constraints that apply to all operations performed through this connection (unless you specify a different set of constraints when calling a method).

      Note that if you want to get individual constraints (rather than getting the entire set of constraints), call the getOption method.

      Typically, you might call the getConstraints method to create a slightly different set of constraints for a particular operation.

      For example, the following section of code changes the timeout to 3000 milliseconds for a specific rename. Rather than construct a new set of constraints from scratch, the example gets the current settings for the connections and just changes the setting for the timeout.

      Note that this change only applies to the searches performed with this custom set of constraints. All other searches performed through this connection use the original set of search constraints.

       ...
       LDAPConstraints myOptions = ld.getConstraints();
       myOptions.setTimeout( 3000 );
       ld.search( "cn=William Jensen, ou=Accounting, o=Ace Industry,c=US",
                  "cn=Will Jensen",
                  null,
                  false,
                  myOptions );
       ...
       
      Returns:
      a copy of the LDAPConstraints object representing the set of constraints that apply (by default) to all operations performed through this connection.
      See Also:
    • getSearchConstraints

      public LDAPSearchConstraints getSearchConstraints()
      Returns the set of search constraints that apply to all searches performed through this connection (unless you specify a different set of search constraints when calling the search method).

      Note that if you want to get individual constraints (rather than getting the entire set of constraints), call the getOption method.

      Typically, you might call the getSearchConstraints method to create a slightly different set of search constraints to apply to a particular search.

      For example, the following section of code changes the maximum number of results to 10 for a specific search. Rather than construct a new set of search constraints from scratch, the example gets the current settings for the connections and just changes the setting for the maximum results.

      Note that this change only applies to the searches performed with this custom set of constraints. All other searches performed through this connection use the original set of search constraints.

       ...
       LDAPSearchConstraints myOptions = ld.getSearchConstraints();
       myOptions.setMaxResults( 10 );
       String[] myAttrs = { "objectclass" };
       LDAPSearchResults myResults = ld.search( "o=Ace Industry,c=US",
                                                LDAPv2.SCOPE_SUB,
                                                "(objectclass=*)",
                                                myAttrs,
                                                false,
                                                myOptions );
       ...
       
      Returns:
      a copy of the LDAPSearchConstraints object representing the set of search constraints that apply (by default) to all searches performed through this connection.
      See Also:
    • setConstraints

      public void setConstraints(LDAPConstraints cons)
      Set the default constraint set for all operations.
      Parameters:
      cons - LDAPConstraints object to use as the default constraint set
      See Also:
    • setSearchConstraints

      public void setSearchConstraints(LDAPSearchConstraints cons)
      Set the default constraint set for all search operations.
      Parameters:
      cons - LDAPSearchConstraints object to use as the default constraint set
      See Also:
    • getInputStream

      public InputStream getInputStream()
      Gets the stream for reading from the listener socket
      Returns:
      the stream for reading from the listener socket, or null if there is none
    • setInputStream

      public void setInputStream(InputStream is)
      Sets the stream for reading from the listener socket if there is one
      Parameters:
      is - the stream for reading from the listener socket
    • getOutputStream

      public OutputStream getOutputStream()
      Gets the stream for writing to the socket
      Returns:
      the stream for writing to the socket, or null if there is none
    • setOutputStream

      public void setOutputStream(OutputStream os)
      Sets the stream for writing to the socket
      Parameters:
      os - the stream for writing to the socket, if there is one
    • clone

      public Object clone()
      Returns a new LDAPConnection object that shares the physical connection to the LDAP server but has its own state. The returned LDAPConnection object contains the same state as the current connection, including:
      • the default search constraints
      • host name and port number of the LDAP server
      • the DN and password used to authenticate to the LDAP server
      • the cache

      Overrides:
      clone in class Object
      Returns:
      the LDAPconnection object representing the new object.
    • isNetscape

      public static boolean isNetscape()
      Reports if the class is running in a Netscape browser.
      Returns:
      true if the class is running in a Netscape browser.
    • toString

      public String toString()
      Returns the string representation for this LDAPConnection.

      For example:

      LDAPConnection {ldap://dilly:389 (2) ldapVersion:3 bindDN:"uid=admin,o=iplanet.com"}
      For cloned connections, the number of LDAPConnection instances sharing the same physical connection is shown in parenthesis following the ldap url. If a LDAPConnection is not cloned, this number is omitted from the string representation.
      Overrides:
      toString in class Object
      Returns:
      string representation of the connection.
      See Also:
    • main

      public static void main(String[] args)
      Prints out the LDAP Java SDK version and the highest LDAP protocol version supported by the SDK. To view this information, open a terminal window, and enter:
      java netscape.ldap.LDAPConnection
       
      Parameters:
      args - not currently used