Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
java.lang.Object
netscape.ldap.LDAPConnection
public class LDAPConnection
extends java.lang.Object
implements LDAPv3, LDAPAsynchronousConnection, Cloneable, Serializable
LDAPConnection
object.
connect
method to connect to the
LDAP server.
authenticate
method to authenticate
to server.
disconnect
method to disconnect from
the server when done.
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.
Field Summary | |
static String |
|
static String |
|
static String |
|
static int |
|
static int |
|
static int |
|
static int |
|
static String |
|
Fields inherited from interface netscape.ldap.LDAPv2 | |
BATCHSIZE , BIND , DEFAULT_PORT , DEREF , DEREF_ALWAYS , DEREF_FINDING , DEREF_NEVER , DEREF_SEARCHING , PROTOCOL_VERSION , REFERRALS , REFERRALS_HOP_LIMIT , REFERRALS_REBIND_PROC , SCOPE_BASE , SCOPE_ONE , SCOPE_SUB , SERVER_TIMELIMIT , SIZELIMIT , TIMELIMIT |
Fields inherited from interface netscape.ldap.LDAPv3 | |
ALL_USER_ATTRS , CLIENTCONTROLS , NO_ATTRS , SERVERCONTROLS |
Constructor Summary | |
| |
|
Method Summary | |
void |
|
void |
|
void |
|
void | |
void |
|
LDAPResponseListener |
|
LDAPResponseListener |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
LDAPResponseListener |
|
LDAPResponseListener |
|
void |
|
void |
|
void |
|
void |
|
LDAPResponseListener |
|
LDAPResponseListener |
|
void |
|
void |
|
void |
|
LDAPResponseListener |
|
LDAPResponseListener |
|
Object |
|
boolean |
|
boolean |
|
LDAPResponseListener |
|
LDAPResponseListener |
|
boolean |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
LDAPResponseListener |
|
LDAPResponseListener |
|
void |
|
void |
|
LDAPExtendedOperation |
|
LDAPExtendedOperation |
|
LDAPExtendedOperation |
|
void |
|
String |
|
String |
|
String |
|
LDAPCache |
|
int |
|
int |
|
LDAPConstraints |
|
String |
|
InputStream |
|
Object |
|
OutputStream |
|
int |
|
Object |
|
LDAPControl[] |
|
LDAPSearchConstraints |
|
LDAPSocketFactory |
|
boolean |
|
boolean |
|
static boolean |
|
boolean |
|
static void |
|
void |
|
void |
|
LDAPResponseListener |
|
LDAPResponseListener |
|
void |
|
void |
|
void |
|
LDAPResponseListener |
|
LDAPResponseListener |
|
void |
|
void |
|
void |
|
void |
|
LDAPEntry |
|
LDAPEntry |
|
LDAPEntry |
|
LDAPEntry |
|
static LDAPEntry | |
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
LDAPResponseListener |
|
LDAPResponseListener |
|
void |
|
LDAPSearchResults |
|
LDAPSearchResults |
|
LDAPSearchListener |
|
LDAPSearchListener |
|
static LDAPSearchResults | |
static LDAPSearchResults |
|
void | |
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
String |
|
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 thegetProperty
method. The LDAP protocol version number is of the typeFloat
. For example:... Float LDAPVersion = ( Float )myConn.getProperty( myConn.LDAP_PROPERTY_PROTOCOL ); System.out.println( "Highest supported LDAP protocol version: " + LDAPVersion ); ...
- See Also:
netscape.ldap.LDAPConnection.getProperty(java.lang.String)
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 thegetProperty
method. The SDK version number is of the typeFloat
. For example:... Float sdkVersion = ( Float )myConn.getProperty( myConn.LDAP_PROPERTY_SDK ); System.out.println( "SDK version: " + sdkVersion ); ...
- See Also:
netscape.ldap.LDAPConnection.getProperty(java.lang.String)
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 thegetProperty
method. The value of this property is of the typeString
. For example:... String authTypes = ( String )myConn.getProperty( myConn.LDAP_PROPERTY_SECURITY ); System.out.println( "Supported authentication types: " + authTypes ); ...
- See Also:
netscape.ldap.LDAPConnection.getProperty(java.lang.String)
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 theauthenticate(int version, String dn, String passwd)
method. For example:ld.authenticate( 3, myDN, myPW );
- Field Value:
- 2
- See Also:
netscape.ldap.LDAPConnection.authenticate(int, java.lang.String, java.lang.String)
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.
- Field Value:
- 30
- See Also:
getOption(int)
,setOption(int,Object)
public static final int NODELAY_PARALLEL
Specifies the parallel connection setup policy with no delay when a list of hosts is passed to theconnect
method. For each host in the list, a separate thread is created to attempt to connect to the host. All threads are started simultaneously.
- Field Value:
- 0
- See Also:
setConnSetupDelay(int)
public static final int NODELAY_SERIAL
Specifies the serial connection setup policy when a list of hosts is passed to theconnect
method.
- Field Value:
- -1
- See Also:
setConnSetupDelay(int)
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 thesetProperty
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 thegetProperty
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:
netscape.ldap.LDAPConnection.setProperty(java.lang.String, java.lang.Object)
public LDAPConnection()
Constructs a newLDAPConnection
object, which represents a connection to an LDAP server. Calling the constructor does not actually establish the connection. To connect to the LDAP server, use theconnect
method.
- See Also:
netscape.ldap.LDAPConnection.connect(java.lang.String, int)
,netscape.ldap.LDAPConnection.authenticate(java.lang.String, java.lang.String)
public LDAPConnection(LDAPSocketFactory factory)
Constructs a newLDAPConnection
object that will use the specified socket factory class to create socket connections. The socket factory class must implement theLDAPSocketFactory
interface.
(For example, theLDAPSSLSocketFactory
class implements this interface.) Note that calling theLDAPConnection
constructor does not actually establish a connection to an LDAP server. To connect to an LDAP server, use theconnect
method. The socket connection will be constructed when this method is called.
- See Also:
LDAPSocketFactory
,LDAPSSLSocketFactory
,netscape.ldap.LDAPConnection.connect(java.lang.String, int)
,netscape.ldap.LDAPConnection.authenticate(java.lang.String, java.lang.String)
,getSocketFactory()
,setSocketFactory(LDAPSocketFactory)
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.
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.
public void abandon(LDAPSearchResults searchResults) throws LDAPException
Abandons a current search operation, notifying the server not to send additional search results.
- Parameters:
searchResults
- the search results returned when the search was started
- Throws:
LDAPException
- Failed to notify the LDAP server.
- See Also:
netscape.ldap.LDAPConnection.search(java.lang.String, int, java.lang.String, java.lang.String[], boolean, netscape.ldap.LDAPSearchConstraints)
,LDAPSearchResults
public void add(LDAPEntry entry) throws LDAPException
Adds an entry to the directory. Before using this method, you need to create anLDAPEntry
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, anLDAPException
may be thrown (where the LDAP result code isOBJECT_CLASS_VIOLATION
). For example, the following section of code creates anLDAPEntry
object for a new entry and uses the object to add the new entry to the directory. Because the definition of the LDAPinetOrgPerson
class specifies that thecn
,sn
, andobjectclass
attributes are required, these attributes are specified as part of the new entry. (... 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 ); ...
- 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:
LDAPEntry
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 anLDAPConstraints
object. For example, you can specify whether or not to follow referrals. You can also apply LDAP v3 controls to the operation.
- Parameters:
entry
- LDAPEntry object specifying the distinguished name and attributes of the new entrycons
- the set of preferences to apply to this operation
- Throws:
LDAPException
- Failed to add the specified entry to the directory.
- See Also:
LDAPEntry
,LDAPConstraints
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 entrylistener
- 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:
LDAPEntry
,LDAPResponseListener
public LDAPResponseListener add(LDAPEntry entry, LDAPResponseListener listener, LDAPConstraints cons) throws LDAPException
Adds an entry to the directory and allows you to specify constraints for this LDAP add operation by using anLDAPConstraints
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 entrylistener
- 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:
LDAPEntry
,LDAPResponseListener
,LDAPConstraints
public void add(LDAPEntry entry, LDAPSearchConstraints cons) throws LDAPException
Deprecated. Please use the method signature where
cons
isLDAPConstraints
instead ofLDAPSearchConstraints
public void authenticate(String dn, Hashtable 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 namecbh
- a class which the SASL framework can call to obtain additional required information
- Throws:
LDAPException
- Failed to authenticate to the LDAP server.
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 authenticationpasswd
- password used for authentication
- Throws:
LDAPException
- Failed to authenticate to the LDAP server.
public void authenticate(String dn, String mechanism, String packageName, Hashtable 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 namemechanism
- 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.
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 authenticationpasswd
- password used for authenticationcons
- preferences for the bind operation
- Throws:
LDAPException
- Failed to authenticate to the LDAP server.
public void authenticate(String dn, String passwd, LDAPSearchConstraints cons) throws LDAPException
Deprecated. Please use the method signature where
cons
isLDAPConstraints
instead ofLDAPSearchConstraints
public void authenticate(String dn, String[] mechanisms, Hashtable 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 namemechanisms
- 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:
netscape.ldap.LDAPConnection.authenticate(java.lang.String, java.util.Hashtable, java.lang.Object)
public void authenticate(String dn, String[] mechanisms, String packageName, Hashtable 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 namemechanisms
- 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.
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 versiondn
- distinguished name used for authenticationpasswd
- password used for authentication
- Throws:
LDAPException
- Failed to authenticate to the LDAP server.
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 versiondn
- distinguished name used for authenticationpasswd
- password used for authenticationcons
- preferences for the bind operation
- Throws:
LDAPException
- Failed to authenticate to the LDAP server.
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 anLDAPConstraints
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:
LDAPResponseListener
,LDAPConstraints
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 anLDAPConstraints
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:
LDAPResponseListener
,LDAPConstraints
public void authenticate(int version, String dn, String passwd, LDAPSearchConstraints cons) throws LDAPException
Deprecated. Please use the method signature where
cons
isLDAPConstraints
instead ofLDAPSearchConstraints
public void bind(String dn, Hashtable 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 namecbh
- a class which the SASL framework can call to obtain additional required information
- Throws:
LDAPException
- Failed to authenticate to the LDAP server.
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 );
- Parameters:
dn
- distinguished name used for authenticationpasswd
- password used for authentication
- Throws:
LDAPException
- Failed to authenticate to the LDAP server.
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 authenticationpasswd
- password used for authenticationcons
- preferences for the bind operation
- Throws:
LDAPException
- Failed to authenticate to the LDAP server.
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 namepasswd
- 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 passwordlistener
- 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:
LDAPResponseListener
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 anLDAPConstraints
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 namepasswd
- 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 passwordlistener
- 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:
LDAPResponseListener
,LDAPConstraints
public void bind(String dn, String[] mechanisms, Hashtable 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 namemechanisms
- 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:
netscape.ldap.LDAPConnection.bind(java.lang.String, java.util.Hashtable, java.lang.Object)
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.
- Parameters:
version
- required LDAP protocol versiondn
- distinguished name used for authenticationpasswd
- password used for authentication
- Throws:
LDAPException
- Failed to authenticate to the LDAP server.
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 versiondn
- distinguished name used for authenticationpasswd
- password used for authenticationcons
- preferences for the bind operation
- Throws:
LDAPException
- Failed to authenticate to the LDAP server.
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 versiondn
- if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished namepasswd
- 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 passwordlistener
- 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:
LDAPResponseListener
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 anLDAPConstraints
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 versiondn
- if non-null and non-empty, specifies that the connection and all operations through it should authenticate with dn as the distinguished namepasswd
- 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 passwordlistener
- 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:
LDAPResponseListener
,LDAPConstraints
public Object clone()
Returns a newLDAPConnection
object that shares the physical connection to the LDAP server but has its own state. The returnedLDAPConnection
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
- Returns:
- the
LDAPconnection
object representing the new object.
public boolean compare(String DN, LDAPAttribute attr) throws LDAPException
Checks to see if an entry contains an attribute with a specified value. Returnstrue
if the entry has the value. Returnsfalse
if the entry does not have the value or the attribute. To represent the value that you want compared, you need to create anLDAPAttribute
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." ); } ...
- Parameters:
DN
- the distinguished name of the entry to use in the comparisonattr
- 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:
LDAPAttribute
public boolean compare(String DN, LDAPAttribute attr, LDAPConstraints cons) throws LDAPException
Compares the given entry's attribute value to the specified attribute value.
- Parameters:
DN
- distinguished name of the entry that you want compared against the specified attribute valueattr
- attribute name and value to use in the comparisoncons
- the constraints set for the compare operation
- Throws:
LDAPException
- Failed to perform the comparison.
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 callinggetResultCode
on theLDAPResponse
from theLDAPResponseListener
. The code will beLDAPException.COMPARE_TRUE
orLDAPException.COMPARE_FALSE
.
- Specified by:
- compare in interface LDAPAsynchronousConnection
- Parameters:
dn
- distinguished name of the entry to compareattr
- attribute with a value to comparelistener
- 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.
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 callinggetResultCode
on theLDAPResponse
from theLDAPResponseListener
. The code will beLDAPException.COMPARE_TRUE
orLDAPException.COMPARE_FALSE
.
- Specified by:
- compare in interface LDAPAsynchronousConnection
- Parameters:
dn
- distinguished name of the entry to compareattr
- attribute with a value to comparelistener
- 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.
public boolean compare(String DN, LDAPAttribute attr, LDAPSearchConstraints cons) throws LDAPException
Deprecated. Please use the method signature where
cons
isLDAPConstraints
instead ofLDAPSearchConstraints
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 callingsetConnectTimeout
beforeconnect
.
- 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 thehost
argument:
myhost myhost hishost:389 herhost:5000 whathost myhost:686 myhost:389 hishost:5000 whathost:1024If multiple servers are specified in thehost
list, the connection setup policy specified with theConnSetupDelay
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 thehost
parameter which includes a colon and port number.
- Throws:
LDAPException
- The connection failed.
- See Also:
setConnSetupDelay(int)
,setConnectTimeout(int)
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 callingsetConnectTimeout
beforeconnect
.
- 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 thehost
argument:
myhost myhost hishost:389 herhost:5000 whathost myhost:686 myhost:389 hishost:5000 whathost:1024If multiple servers are specified in thehost
list, the connection setup policy specified with theConnSetupDelay
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 thehost
parameter which includes a colon and port number.dn
- distinguished name used for authenticationpasswd
- password used for authentication
- Throws:
LDAPException
- The connection or authentication failed.
- See Also:
setConnSetupDelay(int)
,setConnectTimeout(int)
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 callingsetConnectTimeout
beforeconnect
.
- 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 thehost
argument:
myhost myhost hishost:389 herhost:5000 whathost myhost:686 myhost:389 hishost:5000 whathost:1024If multiple servers are specified in thehost
list, the connection setup policy specified with theConnSetupDelay
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 thehost
parameter which includes a colon and port number.dn
- distinguished name used for authenticationpasswd
- password used for authenticationcons
- preferences for the bind operation
- Throws:
LDAPException
- The connection or authentication failed.
- See Also:
setConnSetupDelay(int)
,setConnectTimeout(int)
public void connect(String host, int port, String dn, String passwd, LDAPSearchConstraints cons) throws LDAPException
Deprecated. Please use the method signature where
cons
isLDAPConstraints
instead ofLDAPSearchConstraints
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 toconnect(host, port)
followed byauthenticate(version, dn, passwd)
.
- Parameters:
version
- requested version of LDAP: currently 2 or 3host
- 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 theConnSetupDelay
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 namepasswd
- 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:
setConnSetupDelay(int)
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 toconnect(host, port)
followed byauthenticate(version, dn, passwd)
.
- Parameters:
version
- requested version of LDAP: currently 2 or 3host
- 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 theConnSetupDelay
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 namepasswd
- 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 passwordcons
- preferences for the bind operation
- Throws:
LDAPException
- The connection or authentication failed.
- See Also:
setConnSetupDelay(int)
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
isLDAPConstraints
instead ofLDAPSearchConstraints
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 ); ...
- Parameters:
DN
- distinguished name identifying the entry to remove from the directory
- Throws:
LDAPException
- Failed to delete the specified entry from the directory.
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 anLDAPConstraints
object. For example, you can specify whether or not to follow referrals. You can also apply LDAP v3 controls to the operation.
- Parameters:
DN
- distinguished name identifying the entry to remove from the directorycons
- the set of preferences to apply to this operation
- Throws:
LDAPException
- Failed to delete the specified entry from the directory.
- See Also:
LDAPConstraints
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 deletelistener
- 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:
LDAPResponseListener
,LDAPConstraints
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 deletelistener
- 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:
LDAPResponseListener
,LDAPConstraints
public void delete(String DN, LDAPSearchConstraints cons) throws LDAPException
Deprecated. Please use the method signature where
cons
isLDAPConstraints
instead ofLDAPSearchConstraints
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 callingconnect
.
- Specified by:
- disconnect in interface LDAPv2
- Throws:
LDAPException
- Failed to disconnect from the LDAP server.
- See Also:
netscape.ldap.LDAPConnection.connect(java.lang.String, int)
,netscape.ldap.LDAPConnection.connect(java.lang.String, int, java.lang.String, java.lang.String)
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:
LDAPExtendedOperation
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 operationcons
- 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:
LDAPExtendedOperation
public LDAPExtendedOperation extendedOperation(LDAPExtendedOperation op, LDAPSearchConstraints cons) throws LDAPException
Deprecated. Please use the method signature where
cons
isLDAPConstraints
instead ofLDAPSearchConstraints
public void finalize() throws LDAPException
Finalize method, which disconnects from the LDAP server.
- Throws:
LDAPException
- Thrown when the connection cannot be disconnected.
public String getAuthenticationDN()
Returns the distinguished name (DN) used for authentication over this connection.
- Returns:
- distinguished name used for authentication over this connection.
public String getAuthenticationMethod()
Gets the authentication method used to bind:
"none", "simple", or "sasl"
- Returns:
- the authentication method, or "none"
public String getAuthenticationPassword()
Returns the password used for authentication over this connection.
- Returns:
- password used for authentication over this connection.
public LDAPCache getCache()
Gets theLDAPCache
object associated with the currentLDAPConnection
object.
- Returns:
- the
LDAPCache
object representing the cache that the current connection should use
- See Also:
LDAPCache
,setCache(LDAPCache)
public int getConnSetupDelay()
Returns the delay in seconds when making concurrent connection attempts to multiple servers.
- Returns:
- the delay in seconds between connection attempts:
NODELAY_SERIAL
The serial connection setup policy is enabled (no concurrency).
NODELAY_PARALLEL
The parallel connection setup policy with no delay is enabled.
delay > 0
The parallel connection setup policy with the delay ofdelay
seconds is enabled.
- See Also:
setConnSetupDelay(int)
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(int)
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 thegetOption
method. Typically, you might call thegetConstraints
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:
LDAPConstraints
,getOption(int)
public String getHost()
Returns the host name of the LDAP server to which you are connected.
- Returns:
- host name of the LDAP server.
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
public Object getOption(int option) throws LDAPException
Returns the value of the specified option for thisLDAPConnection
object. These options represent the constraints for the current connection. To get all constraints for the current connection, call thegetSearchConstraints
method. By default, the constraints apply to all operations performed through the current connection. You can change these constraints: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
- If you want to set a constraint only for a particular operation, create an
LDAPConstraints
object (or aLDAPSearchConstraints
object for a search or find operation) with your new constraints and pass it to theLDAPConnection
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.LDAPSearchConstraints
object.)LDAPConnection ld = new LDAPConnection(); int sizeLimit = ( (Integer)ld.getOption( LDAPv2.SIZELIMIT ) ).intValue(); System.out.println( "Maximum number of results: " + sizeLimit );
- Parameters:
option
- you can specify one of the following options:
Option Data Type Description 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 isDEREF_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. Iffalse
, anLDAPReferralException
is raised when referral is detected. By default, the value of this option isfalse
.LDAPv2.REFERRALS_REBIND_PROC
LDAPRebind
Specifies an object with a class that implements the LDAPRebind
interface. You must define this class and thegetRebindAuthentication
method that will be used to get the distinguished name and password to use for authentication. Modifying this option sets theLDAPv2.BIND
option to null. By default, the value of this option isnull
.LDAPv2.BIND
LDAPBind
Specifies an object with a class that implements the LDAPBind
interface. You must define this class and thebind
method that will be used to authenticate to the server on referrals. Modifying this option sets theLDAPv2.REFERRALS_REBIND_PROC
to null. By default, the value of this option isnull
.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:
LDAPRebind
,LDAPConstraints
,LDAPSearchConstraints
,LDAPReferralException
,LDAPControl
,getSearchConstraints()
,netscape.ldap.LDAPConnection.search(java.lang.String, int, java.lang.String, java.lang.String[], boolean, netscape.ldap.LDAPSearchConstraints)
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
public int getPort()
Returns the port number of the LDAP server to which you are connected.
- Returns:
- port number of the LDAP server.
public Object getProperty(String name) throws LDAPException
Gets a property of a connection. You can get the following properties for a given connection:For example, the following section of code gets the version of the SDK.
LDAP_PROPERTY_SDK
To get the version of this SDK, get this property. The value of this property is of the typeFloat
.LDAP_PROPERTY_PROTOCOL
To get the highest supported version of the LDAP protocol, get this property. The value of this property is of the typeFloat
.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 typeString
.... 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 aFloat
.) If you pass this method an unknown property name, the method returns null.
- Throws:
LDAPException
- Unable to get the value of the specified property.
public LDAPControl[] getResponseControls()
Returns an array of the latest controls (if any) from server. To retrieve the controls from a search result, call thegetResponseControls
method from theLDAPSearchResults
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.
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 thesearch
method). Note that if you want to get individual constraints (rather than getting the entire set of constraints), call thegetOption
method. Typically, you might call thegetSearchConstraints
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:
LDAPSearchConstraints
,getOption(int)
,netscape.ldap.LDAPConnection.search(java.lang.String, int, java.lang.String, java.lang.String[], boolean, netscape.ldap.LDAPSearchConstraints)
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.
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), returnsfalse
.
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, returnsfalse
.
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.
public boolean isTLS()
Indicates if the session is currently protected by TLS.
- Returns:
true
if TLS was activated.
- Since:
- LDAPJDK 4.17
- See Also:
startTLS()
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
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 theLDAPModification
object to specify the change to make and theLDAPAttribute
object to specify the attribute value to change. TheLDAPModification
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 ); ...
- Parameters:
DN
- the distinguished name of the entry to modifymod
- a single change to make to the entry
- Throws:
LDAPException
- Failed to make the specified change to the directory entry.
- See Also:
LDAPModification
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 anLDAPConstraints
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 modifymod
- a single change to make to the entrycons
- the set of preferences to apply to this operation
- Throws:
LDAPException
- Failed to make the specified change to the directory entry.
- See Also:
LDAPModification
,LDAPConstraints
public LDAPResponseListener modify(String dn, LDAPModification mod, LDAPResponseListener listener) 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.
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 modifymod
- a single change to make to an entrylistener
- 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:
LDAPModification
,LDAPResponseListener
public LDAPResponseListener modify(String dn, LDAPModification mod, LDAPResponseListener listener, LDAPConstraints cons) 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.
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 modifymod
- a single change to make to an entrylistener
- 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:
LDAPModification
,LDAPResponseListener
,LDAPConstraints
public void modify(String DN, LDAPModification mod, LDAPSearchConstraints cons) throws LDAPException
Deprecated. Please use the method signature where
cons
isLDAPConstraints
instead ofLDAPSearchConstraints
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 theLDAPModificationSet
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 anLDAPAttribute
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 ); ...
- Parameters:
DN
- the distinguished name of the entry to modifymods
- a set of changes to make to the entry
- Throws:
LDAPException
- Failed to make the specified changes to the directory entry.
- See Also:
LDAPModificationSet
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 anLDAPConstraints
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 modifymods
- a set of changes to make to the entrycons
- the set of preferences to apply to this operation
- Throws:
LDAPException
- Failed to make the specified changes to the directory entry.
- See Also:
LDAPModificationSet
,LDAPConstraints
public LDAPResponseListener modify(String dn, LDAPModificationSet mods, LDAPResponseListener listener) 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.
- Specified by:
- modify in interface LDAPAsynchronousConnection
- Parameters:
dn
- distinguished name of the entry to modifymods
- a set of changes to make to the entrylistener
- 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:
LDAPModificationSet
,LDAPResponseListener
public LDAPResponseListener modify(String dn, LDAPModificationSet mods, LDAPResponseListener listener, LDAPConstraints cons) 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).
- Specified by:
- modify in interface LDAPAsynchronousConnection
- Parameters:
dn
- distinguished name of the entry to modifymods
- a set of changes to make to the entrylistener
- 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.
public void modify(String DN, LDAPModificationSet mods, LDAPSearchConstraints cons) throws LDAPException
Deprecated. Please use the method signature where
cons
isLDAPConstraints
instead ofLDAPSearchConstraints
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 ofLDAPModification
objects to specify the changes to make. Each change must be specified by anLDAPModification
object, and you must specify each attribute value to modify, add, or remove by anLDAPAttribute
object.
- Parameters:
DN
- the distinguished name of the entry to modifymods
- 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:
LDAPModification
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 anLDAPConstraints
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 modifymods
- an array of objects representing the changes to make to the entrycons
- the set of preferences to apply to this operation
- Throws:
LDAPException
- Failed to make the specified changes to the directory entry.
- See Also:
LDAPModification
,LDAPConstraints
public void modify(String DN, LDAPModification[] mods, LDAPSearchConstraints cons) throws LDAPException
Deprecated. Please use the method signature where
cons
isLDAPConstraints
instead ofLDAPSearchConstraints
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." );
- 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.
public LDAPEntry read(String DN, 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 thecn
andsn
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 ); } }
- 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 read the specified entry from the directory.
public LDAPEntry read(String DN, attrs[] , LDAPSearchConstraints cons) throws LDAPException
Read the entry corresponding to the specified distinguished name (DN), and retrieve only the specified attributes.
- Parameters:
DN
- distinguished name of the entry to retrievecons
- the constraints set for the read operation
- Throws:
LDAPException
- Failed to retrieve the specified entry.
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 retrievecons
- 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.
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 thesearch( 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:
LDAPUrl
,search(LDAPUrl)
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
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 thenewParentDN
argument, anLDAPException
will be thrown.
- Parameters:
dn
- current distinguished name of the entrynewRDN
- 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
- iftrue
, the old name is not retained as an attribute value (for example, the attribute value "cn=oldName" is removed). Iffalse
, 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.
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 anLDAPConstraints
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 thenewParentDN
argument, anLDAPException
will be thrown.
- Parameters:
DN
- current distinguished name of the entrynewRDN
- 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
- iftrue
, the old name is not retained as an attribute value (for example, the attribute value "cn=oldName" is removed). Iffalse
, 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:
LDAPConstraints
public void rename(String DN, String newRDN, String newParentDN, boolean deleteOldRDN, LDAPSearchConstraints cons) throws LDAPException
Deprecated. Please use the method signature where
cons
isLDAPConstraints
instead ofLDAPSearchConstraints
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=BabsThe 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 ); ...
- Parameters:
DN
- current distinguished name of the entrynewRDN
- new relative distinguished name for the entry (for example, "cn=newName")deleteOldRDN
- iftrue
, the old name is not retained as an attribute value (for example, the attribute value "cn=oldName" is removed). Iffalse
, 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.
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=BabsThe 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 ); ...
- Parameters:
DN
- current distinguished name of the entrynewRDN
- new relative distinguished name for the entry (for example, "cn=newName")deleteOldRDN
- iftrue
, the old name is not retained as an attribute value (for example, the attribute value "cn=oldName" is removed). Iffalse
, 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.
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 entrynewRdn
- new relative distinguished name for the entrydeleteOldRdn
- if true, the old name is not retained as an attribute valuelistener
- 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:
LDAPResponseListener
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 entrynewRdn
- new relative distinguished name for the entrydeleteOldRdn
- if true, the old name is not retained as an attribute valuelistener
- 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:
LDAPResponseListener
,LDAPConstraints
public void rename(String DN, String newRDN, boolean deleteOldRDN, LDAPSearchConstraints cons) throws LDAPException
Deprecated. Please use the method signature where
cons
isLDAPConstraints
instead ofLDAPSearchConstraints
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 theou=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 theabandon
method.
- Parameters:
base
- the base distinguished name from which to searchscope
- 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 criteriaattrs
- list of attributes that you want returned in the search resultsattrsOnly
- 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:
abandon(LDAPSearchResults)
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 theabandon
method.
- Parameters:
base
- the base distinguished name from which to searchscope
- 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 criteriaattrs
- list of attributes to return in the search resultsattrsOnly
- if true, returns the names but not the values of the attributes found. If false, returns the names and values for attributes foundcons
- constraints specific to this search (for example, the maximum number of entries to return)
- Returns:
- LDAPSearchResults the results of the search as an enumeration.
- Throws:
LDAPException
- Failed to complete the specified search.
- See Also:
abandon(LDAPSearchResults)
public LDAPSearchListener search(String base, int scope, String filter, attrs[] , boolean typesOnly, LDAPSearchListener listener) throws LDAPException
Performs the search specified by the criteria that you enter. To abandon the search, use theabandon
method.
- Specified by:
- search in interface LDAPAsynchronousConnection
- Parameters:
base
- the base distinguished name from which to searchscope
- 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 criteriatypesOnly
- if true, returns the names but not the values of the attributes found. If false, returns the names and values for attributes foundlistener
- 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:
abandon(LDAPSearchListener)
public LDAPSearchListener search(String base, int scope, String filter, 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 theabandon
method.
- Specified by:
- search in interface LDAPAsynchronousConnection
- Parameters:
base
- the base distinguished name from which to searchscope
- 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 criteriatypesOnly
- 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:
abandon(LDAPSearchListener)
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 theou=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 theabandon
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:
LDAPUrl
,LDAPSearchResults
,abandon(LDAPSearchResults)
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 theabandon
method.
- Parameters:
toGet
- LDAP URL representing the search to runcons
- 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:
LDAPUrl
,LDAPSearchResults
,abandon(LDAPSearchResults)
public void setCache(LDAPCache cache)
Sets the specifiedLDAPCache
object as the cache for theLDAPConnection
object.
- Parameters:
cache
- theLDAPCache
object representing the cache that the current connection should use
- See Also:
LDAPCache
,getCache()
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 theconnect
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 theConnSetupDelay
before making the call to theconnect
method.
- Parameters:
delay
- the delay in seconds between connection attempts. Possible values are:
NODELAY_SERIAL
Use the serial connection setup policy.
NODELAY_PARALLEL
Use the parallel connection setup policy with no delay. Start all connection setup threads immediately.
delay > 0
Use the parallel connection setup policy with delay. Start another connection setup thread afterdelay
seconds.
- See Also:
NODELAY_SERIAL
,NODELAY_PARALLEL
,netscape.ldap.LDAPConnection.connect(java.lang.String, int)
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)
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:
getConstraints()
,LDAPConstraints
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
public void setOption(int option, Object value) throws LDAPException
Sets the value of the specified option for thisLDAPConnection
object. These options represent the constraints for the current connection. To get all constraints for the current connection, call thegetSearchConstraints
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 anLDAPConstraints
object (or aLDAPSearchConstraints
object for a search or find operation) with your new constraints and pass it to theLDAPConnection
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 anLDAPSearchConstraints
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() );
- Parameters:
option
- you can specify one of the following options:
Option Data Type Description 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 isDEREF_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. Iffalse
, anLDAPReferralException
is raised when a referral is detected. By default, the value of this option isfalse
.LDAPv2.REFERRALS_REBIND_PROC
LDAPRebind
Specifies an object with a class that implements the LDAPRebind
interface. You must define this class and thegetRebindAuthentication
method that will be used to get the distinguished name and password to use for authentication. Modifying this option sets theLDAPv2.BIND
option to null. By default, the value of this option isnull
.LDAPv2.BIND
LDAPBind
Specifies an object with a class that implements the LDAPBind
interface. You must define this class and thebind
method that will be used to autheniticate to the server on referrals. Modifying this option sets theLDAPv2.REFERRALS_REBIND_PROC
to null. By default, the value of this option isnull
.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:
LDAPRebind
,LDAPConstraints
,LDAPSearchConstraints
,LDAPReferralException
,LDAPControl
,getSearchConstraints()
,netscape.ldap.LDAPConnection.search(java.lang.String, int, java.lang.String, java.lang.String[], boolean, netscape.ldap.LDAPSearchConstraints)
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
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 setval
- value to set
- Throws:
LDAPException
- Unable to set the value of the specified property.
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:
getSearchConstraints()
,LDAPSearchConstraints
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 connectionsetSocketFactory()
must be called beforeconnect()
. For the start TLS operationsetSocketFactory()
must be called afterconnect()
.
- 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.
public void startTLS() throws LDAPException
Begin using the Transport Layer Security (TLS) protocol for session privacy. BeforestartTLS()
is called, a socket factory of typeLDAPTLSSocketFactory
must be set for the connection. The factory must be set after theconnect()
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
public String toString()
Returns the string representation for thisLDAPConnection
. 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.
- Returns:
- string representation of the connection.
- See Also:
clone()