com.novell.ldap
Class LDAPConnection

java.lang.Object
  com.novell.ldap.LDAPConnection

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

DsmlConnection, SPMLConnection

public class LDAPConnection

extends java.lang.Object

implements java.lang.Cloneable

The central class that encapsulates the connection to a directory server through the LDAP protocol. LDAPConnection objects are used to perform common LDAP operations such as search, modify and add.

In addition, LDAPConnection objects allow you to bind to an LDAP server, set connection and search constraints, and perform several other tasks.

An LDAPConnection object is not connected on construction and can only be connected to one server at one port. Multiple threads may share this single connection, typically by cloning the connection object, one for each thread. An application may have more than one LDAPConnection object, connected to the same or different directory servers.

Sample Code: Search.java

Field Summary

static java.lang.String	ALL_USER_ATTRS Used with search instead of an attribute list to indicate that all attributes are to be returned.
static int	DEFAULT_PORT The default port number for LDAP servers.
static int	DEFAULT_SSL_PORT The default SSL port number for LDAP servers.
static java.lang.String	LDAP_PROPERTY_PROTOCOL A string that can be passed in to the getProperty method.
static java.lang.String	LDAP_PROPERTY_SDK A string that can be passed in to the getProperty method.
static java.lang.String	LDAP_PROPERTY_SECURITY A string that can be passed in to the getProperty method.
static int	LDAP_V3 Specifies the LDAPv3 protocol version when performing a bind operation.
static java.lang.String	NO_ATTRS Used with search instead of an attribute list to indicate that no attributes are to be returned.
static int	SCOPE_BASE Used with search to specify that the scope of entrys to search is to search only the base obect.
static int	SCOPE_ONE Used with search to specify that the scope of entrys to search is to search only the immediate subordinates of the base obect.
static int	SCOPE_SUB Used with search to specify that the scope of entrys to search is to search the base object and all entries within its subtree.
static int	SCOPE_SUBORDINATESUBTREE Used with search to specify that the scope of entries to search is to search the subordinate subtree object and all entries within it.
static java.lang.String	SERVER_SHUTDOWN_OID A string that corresponds to the server shutdown notification OID.

Constructor Summary

LDAPConnection()
Constructs a new LDAPConnection object, which represents a connection to an LDAP server.

LDAPConnection(int timeout)
Constructs a new LDAPConnection object, which will use the supplied timeout value(in MILLISECONDS) to construct a socket connection during LDAPConnection.connect method with the specified socket connect timeout value.

LDAPConnection(LDAPSocketFactory factory)
Constructs a new LDAPConnection object, which will use the supplied class factory to construct a socket connection during LDAPConnection.connect method.

Method Summary

void	abandon(int id) Abandons an asynchronous operation.
void	abandon(int id, LDAPConstraints cons) Abandons an asynchronous operation, using the specified constraints.
void	abandon(LDAPMessageQueue queue) Abandons all outstanding operations managed by the queue.
void	abandon(LDAPMessageQueue queue, LDAPConstraints cons) Abandons all outstanding operations managed by the queue.
void	abandon(LDAPSearchResults results) Notifies the server not to send additional results associated with this LDAPSearchResults object, and discards any results already received.
void	abandon(LDAPSearchResults results, LDAPConstraints cons) Notifies the server not to send additional results associated with this LDAPSearchResults object, and discards any results already received.
void	add(LDAPEntry entry) Synchronously adds an entry to the directory.
void	add(LDAPEntry entry, LDAPConstraints cons) Synchronously adds an entry to the directory, using the specified constraints.
LDAPResponseQueue	add(LDAPEntry entry, LDAPResponseQueue queue) Asynchronously adds an entry to the directory.
LDAPResponseQueue	add(LDAPEntry entry, LDAPResponseQueue queue, LDAPConstraints cons) Asynchronously adds an entry to the directory, using the specified constraints.
void	addUnsolicitedNotificationListener(LDAPUnsolicitedNotificationListener listener) Registers an object to be notified on arrival of an unsolicited message from a server.
void	bind(int version, java.lang.String dn, byte[] passwd) Synchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name, password, and LDAP version.
void	bind(int version, java.lang.String dn, byte[] passwd, LDAPConstraints cons) Synchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name, password, LDAP version, and constraints.
LDAPResponseQueue	bind(int version, java.lang.String dn, byte[] passwd, LDAPResponseQueue queue) Asynchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name, password, LDAP version, and queue.
LDAPResponseQueue	bind(int version, java.lang.String dn, byte[] passwd, LDAPResponseQueue queue, LDAPConstraints cons) Asynchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name, password, LDAP version, queue, and constraints.
void	bind(int version, java.lang.String dn, java.lang.String passwd) Deprecated. replaced by bind(int, String, byte[])
void	bind(int version, java.lang.String dn, java.lang.String passwd, LDAPConstraints cons) Deprecated. replaced by bind(int, String, byte[], LDAPConstraints)
void	bind(java.lang.String dn, java.lang.String passwd) Deprecated. replaced by bind(int, String, byte[])
void	bind(java.lang.String dn, java.lang.String passwd, LDAPConstraints cons) Deprecated. replaced by bind(int, String, byte[], LDAPConstraints)
void	bind(java.lang.String dn, java.lang.String authzId, java.util.Map props, java.lang.Object cbh) Synchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name and the specified set of mechanisms.
void	bind(java.lang.String dn, java.lang.String authzId, java.util.Map props, java.lang.Object cbh, LDAPConstraints cons) Synchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name and the specified set of mechanisms.
void	bind(java.lang.String dn, java.lang.String authzId, java.lang.String[] mechanisms, java.util.Map props, java.lang.Object cbh) Synchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name and the specified set of mechanisms.
void	bind(java.lang.String dn, java.lang.String authzId, java.lang.String[] mechanisms, java.util.Map props, java.lang.Object cbh, LDAPConstraints cons) Synchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name and the specified set of mechanisms.
java.lang.Object	clone() Returns a copy of the object with a private context, but sharing the network connection if there is one.
boolean	compare(java.lang.String dn, LDAPAttribute attr) Synchronously checks to see if an entry contains an attribute with a specified value.
boolean	compare(java.lang.String dn, LDAPAttribute attr, LDAPConstraints cons) Synchronously checks to see if an entry contains an attribute with a specified value, using the specified constraints.
LDAPResponseQueue	compare(java.lang.String dn, LDAPAttribute attr, LDAPResponseQueue queue) Asynchronously compares an attribute value with one in the directory, using the specified queue.
LDAPResponseQueue	compare(java.lang.String dn, LDAPAttribute attr, LDAPResponseQueue queue, LDAPConstraints cons) Asynchronously compares an attribute value with one in the directory, using the specified queue and contraints.
void	connect(java.lang.String host, int port) Connects to the specified host and port.
void	delete(java.lang.String dn) Synchronously deletes the entry with the specified distinguished name from the directory.
void	delete(java.lang.String dn, LDAPConstraints cons) Synchronously deletes the entry with the specified distinguished name from the directory, using the specified constraints.
LDAPResponseQueue	delete(java.lang.String dn, LDAPResponseQueue queue) Asynchronously deletes the entry with the specified distinguished name from the directory and returns the results to the specified queue.
LDAPResponseQueue	delete(java.lang.String dn, LDAPResponseQueue queue, LDAPConstraints cons) Asynchronously deletes the entry with the specified distinguished name from the directory, using the specified contraints and queue.
void	disconnect() Synchronously disconnects from the LDAP server.
void	disconnect(LDAPConstraints cons) Synchronously disconnects from the LDAP server.
LDAPExtendedResponse	extendedOperation(LDAPExtendedOperation op) Provides a synchronous means to access extended, non-mandatory operations offered by a particular LDAPv3 compliant server.
LDAPExtendedResponse	extendedOperation(LDAPExtendedOperation op, LDAPConstraints cons) Provides a synchronous means to access extended, non-mandatory operations offered by a particular LDAPv3 compliant server.
LDAPResponseQueue	extendedOperation(LDAPExtendedOperation op, LDAPConstraints cons, LDAPResponseQueue queue) Provides an asynchronous means to access extended, non-mandatory operations offered by a particular LDAPv3 compliant server.
LDAPResponseQueue	extendedOperation(LDAPExtendedOperation op, LDAPResponseQueue queue) Provides an asynchronous means to access extended, non-mandatory operations offered by a particular LDAPv3 compliant server.
LDAPSchema	fetchSchema(java.lang.String schemaDN) Retrieves the schema associated with a particular schema DN in the directory server.
protected void	finalize() Closes the connection, if open, and releases any other resources held by the object.
java.lang.String	getAuthenticationDN() Returns the distinguished name (DN) used for as the bind name during the last successful bind operation.
java.lang.String	getAuthenticationMethod() Returns the method used to authenticate the connection.
LDAPConstraints	getConstraints() Returns a copy of the set of constraints associated with this connection.
java.lang.String	getHost() Returns the host name of the LDAP server to which the object is or was last connected, in the format originally specified.
int	getPort() Returns the port number of the LDAP server to which the object is or was last connected.
java.lang.Object	getProperty(java.lang.String name) Returns a property of a connection object.
int	getProtocolVersion() Returns the protocol version uses to authenticate.
LDAPControl[]	getResponseControls() Returns the Server Controls associated with the most recent response to a synchronous request on this connection object, or null if the latest response contained no Server Controls.
java.lang.Object	getSaslBindCallbackHandler() Returns the call back handler if any specified on binding with a SASL mechanism.
java.util.Map	getSaslBindProperties() Returns the properties if any specified on binding with a SASL mechanism.
java.lang.String	getSchemaDN() Retrieves the Distiguished Name (DN) for the schema advertised in the root DSE of the Directory Server.
java.lang.String	getSchemaDN(java.lang.String dn) Retrieves the Distiguished Name (DN) of the schema associated with a entry in the Directory.
LDAPSearchConstraints	getSearchConstraints() Returns a copy of the set of search constraints associated with this connection.
LDAPSocketFactory	getSocketFactory() Returns the LDAPSocketFactory used to establish this server connection.
int	getSocketTimeOut() Returns the SocketTimeOut value set in milliseconds.
boolean	isBound() Indicates whether the object has authenticated to the connected LDAP server.
boolean	isConnected() Indicates whether the connection represented by this object is open at this time.
boolean	isConnectionAlive() Checks whether the connection represented by this object is still alive or not.
boolean	isTLS() Indicatates if the connection is protected by TLS.
protected LDAPMessage	makeExtendedOperation(LDAPExtendedOperation op, LDAPConstraints cons) Formulates the extended operation, constraints into an LDAPMessage and returns the LDAPMessage.
void	modify(java.lang.String dn, LDAPModification mod) Synchronously makes a single change to an existing entry in the directory.
void	modify(java.lang.String dn, LDAPModification[] mods) Synchronously makes a set of changes to an existing entry in the directory.
void	modify(java.lang.String dn, LDAPModification[] mods, LDAPConstraints cons) Synchronously makes a set of changes to an existing entry in the directory, using the specified constraints.
LDAPResponseQueue	modify(java.lang.String dn, LDAPModification[] mods, LDAPResponseQueue queue) Asynchronously makes a set of changes to an existing entry in the directory.
LDAPResponseQueue	modify(java.lang.String dn, LDAPModification[] mods, LDAPResponseQueue queue, LDAPConstraints cons) Asynchronously makes a set of changes to an existing entry in the directory, using the specified constraints and queue.
void	modify(java.lang.String dn, LDAPModification mod, LDAPConstraints cons) Synchronously makes a single change to an existing entry in the directory, using the specified constraints.
LDAPResponseQueue	modify(java.lang.String dn, LDAPModification mod, LDAPResponseQueue queue) Asynchronously makes a single change to an existing entry in the directory.
LDAPResponseQueue	modify(java.lang.String dn, LDAPModification mod, LDAPResponseQueue queue, LDAPConstraints cons) Asynchronously makes a single change to an existing entry in the directory, using the specified constraints and queue.
static LDAPEntry	read(LDAPUrl toGet) Synchronously reads the entry specified by the LDAP URL.
static LDAPEntry	read(LDAPUrl toGet, LDAPSearchConstraints cons) Synchronously reads the entry specified by the LDAP URL, using the specified constraints.
LDAPEntry	read(java.lang.String dn) Synchronously reads the entry for the specified distiguished name (DN) and retrieves all attributes for the entry.
LDAPEntry	read(java.lang.String dn, LDAPSearchConstraints cons) Synchronously reads the entry for the specified distiguished name (DN), using the specified constraints, and retrieves all attributes for the entry.
LDAPEntry	read(java.lang.String dn, java.lang.String[] attrs) Synchronously reads the entry for the specified distinguished name (DN) and retrieves only the specified attributes from the entry.
LDAPEntry	read(java.lang.String dn, java.lang.String[] attrs, LDAPSearchConstraints cons) Synchronously reads the entry for the specified distinguished name (DN), using the specified constraints, and retrieves only the specified attributes from the entry.
void	removeUnsolicitedNotificationListener(LDAPUnsolicitedNotificationListener listener) Deregisters an object so that it will no longer be notified on arrival of an unsolicited message from a server.
void	rename(java.lang.String dn, java.lang.String newRdn, boolean deleteOldRdn) Synchronously renames an existing entry in the directory.
void	rename(java.lang.String dn, java.lang.String newRdn, boolean deleteOldRdn, LDAPConstraints cons) Synchronously renames an existing entry in the directory, using the specified constraints.
LDAPResponseQueue	rename(java.lang.String dn, java.lang.String newRdn, boolean deleteOldRdn, LDAPResponseQueue queue) Asynchronously renames an existing entry in the directory.
LDAPResponseQueue	rename(java.lang.String dn, java.lang.String newRdn, boolean deleteOldRdn, LDAPResponseQueue queue, LDAPConstraints cons) Asynchronously renames an existing entry in the directory, using the specified constraints.
void	rename(java.lang.String dn, java.lang.String newRdn, java.lang.String newParentdn, boolean deleteOldRdn) Synchronously renames an existing entry in the directory, possibly repositioning the entry in the directory tree.
void	rename(java.lang.String dn, java.lang.String newRdn, java.lang.String newParentdn, boolean deleteOldRdn, LDAPConstraints cons) Synchronously renames an existing entry in the directory, using the specified constraints and possibly repositioning the entry in the directory tree.
LDAPResponseQueue	rename(java.lang.String dn, java.lang.String newRdn, java.lang.String newParentdn, boolean deleteOldRdn, LDAPResponseQueue queue) Asynchronously renames an existing entry in the directory, possibly repositioning the entry in the directory.
LDAPResponseQueue	rename(java.lang.String dn, java.lang.String newRdn, java.lang.String newParentdn, boolean deleteOldRdn, LDAPResponseQueue queue, LDAPConstraints cons) Asynchronously renames an existing entry in the directory, using the specified constraints and possibily repositioning the entry in the directory.
static LDAPSearchResults	search(LDAPUrl toGet) Synchronously performs the search specified by the LDAP URL, returning an enumerable LDAPSearchResults object.
static LDAPSearchResults	search(LDAPUrl toGet, LDAPSearchConstraints cons) Synchronously perfoms the search specified by the LDAP URL, using the specified search constraints (such as the maximum number of entries to find or the maximum time to wait for search results).
LDAPSearchResults	search(java.lang.String base, int scope, java.lang.String filter, java.lang.String[] attrs, boolean typesOnly) Synchronously performs the search specified by the parameters.
LDAPSearchResults	search(java.lang.String base, int scope, java.lang.String filter, java.lang.String[] attrs, boolean typesOnly, LDAPSearchConstraints cons) Synchronously performs the search specified by the parameters, using the specified search constraints (such as the maximum number of entries to find or the maximum time to wait for search results).
LDAPSearchQueue	search(java.lang.String base, int scope, java.lang.String filter, java.lang.String[] attrs, boolean typesOnly, LDAPSearchQueue queue) Asynchronously performs the search specified by the parameters.
LDAPSearchQueue	search(java.lang.String base, int scope, java.lang.String filter, java.lang.String[] attrs, boolean typesOnly, LDAPSearchQueue queue, LDAPSearchConstraints cons) Asynchronously performs the search specified by the parameters, also allowing specification of constraints for the search (such as the maximum number of entries to find or the maximum time to wait for search results).
LDAPMessageQueue	sendRequest(LDAPMessage request, LDAPMessageQueue queue) Sends an LDAP request to a directory server.
LDAPMessageQueue	sendRequest(LDAPMessage request, LDAPMessageQueue queue, LDAPConstraints cons) Sends an LDAP request to a directory server.
void	setConstraints(LDAPConstraints cons) Sets the constraints that apply to all operations performed through this connection (unless a different set of constraints is specified when calling an operation method).
static void	setSocketFactory(LDAPSocketFactory factory) Establishes the default LDAPSocketFactory used when LDAPConnection objects are constructed unless an LDAPSocketFactory is specified in the LDAPConnection object constructor.
void	setSocketTimeOut(int timeout) Sets the SocketTimeOut value in milliseconds.
void	startTLS() Starts Transport Layer Security (TLS) protocol on this connection to enable session privacy.
void	stopTLS() Stops Transport Layer Security(TLS) on the LDAPConnection and reverts back to an anonymous state.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SCOPE_BASE

public static final int SCOPE_BASE

Used with search to specify that the scope of entrys to search is to search only the base obect.

SCOPE_BASE = 0

See Also:

Constant Field Values

SCOPE_ONE

public static final int SCOPE_ONE

Used with search to specify that the scope of entrys to search is to search only the immediate subordinates of the base obect.

SCOPE_ONE = 1

See Also:

Constant Field Values

SCOPE_SUB

public static final int SCOPE_SUB

Used with search to specify that the scope of entrys to search is to search the base object and all entries within its subtree.

SCOPE_ONE = 2

See Also:

Constant Field Values

SCOPE_SUBORDINATESUBTREE

public static final int SCOPE_SUBORDINATESUBTREE

Used with search to specify that the scope of entries to search is to search the subordinate subtree object and all entries within it.

SCOPE_SUBORDINATESUBTREE = 4

See Also:

Constant Field Values

NO_ATTRS

public static final java.lang.String NO_ATTRS

Used with search instead of an attribute list to indicate that no attributes are to be returned.

NO_ATTRS = "1.1"

See Also:

Constant Field Values

ALL_USER_ATTRS

public static final java.lang.String ALL_USER_ATTRS

Used with search instead of an attribute list to indicate that all attributes are to be returned.

ALL_USER_ATTRS = "*"

See Also:

Constant Field Values

LDAP_V3

public static final int LDAP_V3

Specifies the LDAPv3 protocol version when performing a bind operation.

Specifies LDAP version V3 of the protocol, and is specified when performing bind operations.

You can use this identifier in the version parameter of the bind method to specify an LDAPv3 bind. LDAP_V3 is the default protocol version

LDAP_V3 = 3

See Also:

bind(int, String, byte[]), bind(int, String, byte[], LDAPConstraints), bind(int, String, byte[], LDAPResponseQueue), bind(int, String, byte[], LDAPResponseQueue, LDAPConstraints), Constant Field Values

DEFAULT_PORT

public static final int DEFAULT_PORT

The default port number for LDAP servers.

You can use this identifier to specify the port when establishing a clear text connection to a server. This the default port.

DEFAULT_PORT = 389

See Also:

connect(String, int), Constant Field Values

DEFAULT_SSL_PORT

public static final int DEFAULT_SSL_PORT

The default SSL port number for LDAP servers.

DEFAULT_SSL_PORT = 636

You can use this identifier to specify the port when establishing a an SSL connection to a server.

.

See Also:

Constant Field Values

LDAP_PROPERTY_SDK

public static final java.lang.String LDAP_PROPERTY_SDK

A string that can be passed in to the getProperty method.

LDAP_PROPERTY_SDK = "version.sdk"

You can use this string to request the version of the SDK

.

See Also:

Constant Field Values

LDAP_PROPERTY_PROTOCOL

public static final java.lang.String LDAP_PROPERTY_PROTOCOL

A string that can be passed in to the getProperty method.

LDAP_PROPERTY_PROTOCOL = "version.protocol"

You can use this string to request the version of the LDAP protocol

.

See Also:

Constant Field Values

LDAP_PROPERTY_SECURITY

public static final java.lang.String LDAP_PROPERTY_SECURITY

A string that can be passed in to the getProperty method.

LDAP_PROPERTY_SECURITY = "version.security"

You can use this string to request the type of security being used

.

See Also:

Constant Field Values

SERVER_SHUTDOWN_OID

public static final java.lang.String SERVER_SHUTDOWN_OID

A string that corresponds to the server shutdown notification OID. This notification may be used by the server to advise the client that the server is about to close the connection due to an error condition.

SERVER_SHUTDOWN_OID = "1.3.6.1.4.1.1466.20036"

See Also:

Constant Field Values

Constructor Detail

LDAPConnection

public LDAPConnection()

Constructs a new LDAPConnection 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 the connect method.

See Also:

connect(String, int)

LDAPConnection

public LDAPConnection(LDAPSocketFactory factory)

Constructs a new LDAPConnection object, which will use the supplied class factory to construct a socket connection during LDAPConnection.connect method.

Parameters:

factory - An object capable of producing a Socket.

See Also:

connect(String, int), getSocketFactory(), setSocketFactory( LDAPSocketFactory)

LDAPConnection

public LDAPConnection(int timeout)

Constructs a new LDAPConnection object, which will use the supplied timeout value (in MILLI SECONDS)to construct a socket connection during LDAPConnection.connect method with the specified socket connect timeout value.

Parameters:

timeout - An object capable of producing a Socket with the specified Socket Connect timeout value.

See Also:

getSocketTimeOut(), setSocketTimeOut(int)

Method Detail

clone

public java.lang.Object clone()

Returns a copy of the object with a private context, but sharing the network connection if there is one.

The network connection remains open until all clones have disconnected or gone out of scope. Any connection opened after cloning is private to the object making the connection.

The clone can issue requests and freely modify options and search constraints, and , without affecting the source object or other clones. If the clone disconnects or reconnects, it is completely dissociated from the source object and other clones. Reauthenticating in a clone, however, is a global operation which will affect the source object and all associated clones, because it applies to the single shared physical connection. Any request by an associated object after one has reauthenticated will carry the new identity.

Returns:

A of the object.

finalize

protected void finalize()
                 throws LDAPException

Closes the connection, if open, and releases any other resources held by the object.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

See Also:

disconnect()

getProtocolVersion

public int getProtocolVersion()

Returns the protocol version uses to authenticate.

0 is returned if no authentication has been performed.

Returns:

The protol version used for authentication or 0 not authenticated.

See Also:

bind( int, String, String)

getAuthenticationDN

public java.lang.String getAuthenticationDN()

Returns the distinguished name (DN) used for as the bind name during the last successful bind operation. null is returned if no authentication has been performed or if the bind resulted in an aonymous connection.

Returns:

The distinguished name if authenticated; otherwise, null.

See Also:

bind( String, String), isBound()

getAuthenticationMethod

public java.lang.String getAuthenticationMethod()

Returns the method used to authenticate the connection. The return value is one of the following:

• "none" indicates the connection is not authenticated.
• "simple" indicates simple authentication was used or that a null or empty authentication DN was specified.
• "sasl" indicates that a SASL mechanism was used to authenticate

Returns:

The method used to authenticate the connection.

getSaslBindProperties

public java.util.Map getSaslBindProperties()

Returns the properties if any specified on binding with a SASL mechanism.

Null is returned if no authentication has been performed or no authentication Map is present.

Returns:

The bind properties Map Object used for SASL bind or null if the connection is not present or not authenticated.

See Also:

bind( String, String, String[], Map, Object )

getSaslBindCallbackHandler

public java.lang.Object getSaslBindCallbackHandler()

Returns the call back handler if any specified on binding with a SASL mechanism.

Null is returned if no authentication has been performed or no authentication call back handler is present.

Returns:

The call back handler used for SASL bind or null if the object is not present or not authenticated.

See Also:

bind( String, String, String[], Map, Object )

getConstraints

public LDAPConstraints getConstraints()

Returns a copy of the set of constraints associated with this connection. These constraints apply to all operations performed through this connection (unless a different set of constraints is specified when calling an operation method).

Returns:

The set of default contraints that apply to this connection.

See Also:

setConstraints(LDAPConstraints)

getHost

public java.lang.String getHost()

Returns the host name of the LDAP server to which the object is or was last connected, in the format originally specified.

Returns:

The host name of the LDAP server to which the object last connected or null if the object has never connected.

See Also:

connect( String, int)

getPort

public int getPort()

Returns the port number of the LDAP server to which the object is or was last connected.

Returns:

The port number of the LDAP server to which the object last connected or -1 if the object has never connected.

See Also:

connect( String, int)

getProperty

public java.lang.Object getProperty(java.lang.String name)

Returns a property of a connection object.

Parameters:

name - Name of the property to be returned.

The following read-only properties are available for any given connection:

• LDAP_PROPERTY_SDK returns the version of this SDK, as a Float data type.
• LDAP_PROPERTY_PROTOCOL returns the highest supported version of the LDAP protocol, as a Float data type.
• LDAP_PROPERTY_SECURITY returns a comma-separated list of the types of authentication supported, as a string.

A deep copy of the property is provided where applicable; a client does not need to clone the object received.

Returns:

The object associated with the requested property, or null if the property is not defined.

See Also:

LDAPConstraints.getProperty(String), LDAPConstraints.setProperty(String, Object)

getSearchConstraints

public LDAPSearchConstraints getSearchConstraints()

Returns a copy of the set of search constraints associated with this connection. These constraints apply to search operations performed through this connection (unless a different set of constraints is specified when calling the search operation method).

Returns:

The set of default search contraints that apply to this connection.

See Also:

setConstraints(com.novell.ldap.LDAPConstraints), search( String, int, String, String[], boolean, LDAPSearchConstraints)

getSocketFactory

public LDAPSocketFactory getSocketFactory()

Returns the LDAPSocketFactory used to establish this server connection.

Returns:

The LDAPSocketFactory used to establish a connection.

See Also:

LDAPConnection( LDAPSocketFactory), setSocketFactory( LDAPSocketFactory)

isBound

public boolean isBound()

Indicates whether the object has authenticated to the connected LDAP server.

Returns:

True if the object has authenticated; false if it has not authenticated.

See Also:

bind( String, String)

isConnected

public boolean isConnected()

Indicates whether the connection represented by this object is open at this time.

Returns:

True if connection is open; false if the connection is closed.

isConnectionAlive

public boolean isConnectionAlive()

Checks whether the connection represented by this object is still alive or not.

Returns:

True if connection is alive; false if the connection is closed.

isTLS

public boolean isTLS()

Indicatates if the connection is protected by TLS.

Returns:

If startTLS has completed this method returns true. If stopTLS has completed or start tls failed, this method returns false.

See Also:

startTLS(), stopTLS()

getSocketTimeOut

public int getSocketTimeOut()

Returns the SocketTimeOut value set in milliseconds.

Returns:

Returns the SocketTimeOut value if set, else 0

See Also:

setSocketTimeOut(int)

setSocketTimeOut

public void setSocketTimeOut(int timeout)

Sets the SocketTimeOut value in milliseconds.

See Also:

getSocketTimeOut()

setConstraints

public void setConstraints(LDAPConstraints cons)

Sets the constraints that apply to all operations performed through this connection (unless a different set of constraints is specified when calling an operation method). An LDAPSearchConstraints object which is passed to this method sets all constraints, while an LDAPConstraints object passed to this method sets only base constraints.

Parameters:

cons - An LDAPConstraints or LDAPSearchConstraints Object containing the contstraint values to set.

See Also:

getConstraints(), getSearchConstraints()

setSocketFactory

public static void setSocketFactory(LDAPSocketFactory factory)

Establishes the default LDAPSocketFactory used when LDAPConnection objects are constructed unless an LDAPSocketFactory is specified in the LDAPConnection object constructor.

This method sets the default LDAPSocketFactory used for all subsequent LDAPConnection objects constructed. If called after LDAPConnection objects are created, those already created are not affected even if they disconnect and establish a new connection. It affects LDAPConnection objects only as they are constructed.

The following code snippet provides a typical usage example:

   if (usingTLS) {
       LDAPConnection.setSocketFactory(myTLSFactory);
   }
   ...
   LDAPConnection conn = new LDAPConnection();
   conn.connect(myHost, myPort);
 

In this example, connections are constructed with the default LDAPSocketFactory. At application start-up time, the default may be set to use a particular provided TLS socket factory.

Parameters:

factory - A factory object which can construct socket connections for an LDAPConnection.

See Also:

LDAPConnection( LDAPSocketFactory)

addUnsolicitedNotificationListener

public void addUnsolicitedNotificationListener(LDAPUnsolicitedNotificationListener listener)

Registers an object to be notified on arrival of an unsolicited message from a server.

An unsolicited message has the ID 0. A new thread is created and the method "messageReceived" in each registered object is called in turn.

Parameters:

listener - An object to be notified on arrival of an unsolicited message from a server. This object must implement the LDAPUnsolicitedNotificationListener interface.

removeUnsolicitedNotificationListener

public void removeUnsolicitedNotificationListener(LDAPUnsolicitedNotificationListener listener)

Deregisters an object so that it will no longer be notified on arrival of an unsolicited message from a server. If the object is null or was not previously registered for unsolicited notifications, the method does nothing.

Parameters:

listener - An object to no longer be notified on arrival of an unsolicited message from a server.

startTLS

public void startTLS()
              throws LDAPException

Starts Transport Layer Security (TLS) protocol on this connection to enable session privacy.

This affects the LDAPConnection object and all cloned objects. A socket factory that implements LDAPTLSSocketFactory must be set on the connection.

Throws:

LDAPException - Thrown if TLS cannot be started. If a SocketFactory has been specified that does not implement LDAPTLSSocketFactory an LDAPException is thrown.

See Also:

isTLS(), stopTLS(), setSocketFactory(com.novell.ldap.LDAPSocketFactory)

stopTLS

public void stopTLS()
             throws LDAPException

Stops Transport Layer Security(TLS) on the LDAPConnection and reverts back to an anonymous state.

Throws:

LDAPException - This can occur for the following reasons:

• StartTLS has not been called before stopTLS
• There exists outstanding messages that have not received all responses
• The sever was not able to support the operation

Note: The Sun and IBM implementions of JSSE do not currently allow stopping TLS on an open Socket. In order to produce the same results this method currently disconnects the socket and reconnects, giving the application an anonymous connection to the server, as required by StopTLS.

See Also:

startTLS(), isTLS()

abandon

public void abandon(LDAPSearchResults results)
             throws LDAPException

Notifies the server not to send additional results associated with this LDAPSearchResults object, and discards any results already received.

Parameters:

results - An object returned from a search.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

abandon

public void abandon(LDAPSearchResults results,
                    LDAPConstraints cons)
             throws LDAPException

Notifies the server not to send additional results associated with this LDAPSearchResults object, and discards any results already received.

Parameters:

results - An object returned from a search.

cons - The contraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

abandon

public void abandon(int id)
             throws LDAPException

Abandons an asynchronous operation.

Parameters:

id - The ID of the asynchronous operation to abandon. The ID can be obtained from the response queue for the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

abandon

public void abandon(int id,
                    LDAPConstraints cons)
             throws LDAPException

Abandons an asynchronous operation, using the specified constraints.

Parameters:

id - The ID of the asynchronous operation to abandon. The ID can be obtained from the search queue for the operation.

cons - The contraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

abandon

public void abandon(LDAPMessageQueue queue)
             throws LDAPException

Abandons all outstanding operations managed by the queue.

All operations in progress, which are managed by the specified queue, are abandoned.

Parameters:

queue - The queue returned from an asynchronous request. All outstanding operations managed by the queue are abandoned, and the queue is emptied.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

abandon

public void abandon(LDAPMessageQueue queue,
                    LDAPConstraints cons)
             throws LDAPException

Abandons all outstanding operations managed by the queue.

All operations in progress, which are managed by the specified queue, are abandoned.

Parameters:

queue - The queue returned from an asynchronous request. All outstanding operations managed by the queue are abandoned, and the queue is emptied.

cons - The contraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

add

public void add(LDAPEntry entry)
         throws LDAPException

Synchronously adds an entry to the directory.

Parameters:

entry - LDAPEntry object specifying the distinguished name and attributes of the new entry.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

add

public void add(LDAPEntry entry,
                LDAPConstraints cons)
         throws LDAPException

Synchronously adds an entry to the directory, using the specified constraints.

Parameters:

entry - LDAPEntry object specifying the distinguished name and attributes of the new entry.

cons - Constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

add

public LDAPResponseQueue add(LDAPEntry entry,
                             LDAPResponseQueue queue)
                      throws LDAPException

Asynchronously adds an entry to the directory.

Parameters:

entry - LDAPEntry object specifying the distinguished name and attributes of the new entry.

queue - Handler for messages returned from a server in response to this request. If it is null, a queue object is created internally.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

add

public LDAPResponseQueue add(LDAPEntry entry,
                             LDAPResponseQueue queue,
                             LDAPConstraints cons)
                      throws LDAPException

Asynchronously adds an entry to the directory, using the specified constraints.

Parameters:

entry - LDAPEntry object specifying the distinguished name and attributes of the new entry.

queue - Handler for messages returned from a server in response to this request. If it is null, a queue object is created internally.

cons - Constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

bind

public void bind(java.lang.String dn,
                 java.lang.String passwd)
          throws LDAPException

Deprecated. replaced by bind(int, String, byte[])

Synchronously authenticates to the LDAP server (that the object is currently connected to) as an LDAPv3 bind, 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 has 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 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.

Note: the application should use care in the use of String password objects. These are long lived objects, and may expose a security risk, especially in objects that are serialized. The LDAPConnection keeps no long lived instances of these objects.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

bind

public void bind(int version,
                 java.lang.String dn,
                 java.lang.String passwd)
          throws LDAPException

Deprecated. replaced by bind(int, String, byte[])

Synchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name, password, and LDAP version.

If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object has already authenticated, the old authentication is discarded.

Parameters:

version - The LDAP protocol version, use LDAP_V3. LDAP_V2 is not supported.

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.

Note: the application should use care in the use of String password objects. These are long lived objects, and may expose a security risk, especially in objects that are serialized. The LDAPConnection keeps no long lived instances of these objects.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

bind

public void bind(java.lang.String dn,
                 java.lang.String passwd,
                 LDAPConstraints cons)
          throws LDAPException

Deprecated. replaced by bind(int, String, byte[], LDAPConstraints)

Synchronously authenticates to the LDAP server (that the object is currently connected to) as an LDAPv3 bind, using the specified name, password, and constraints.

If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object has 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 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. Note: the application should use care in the use of String password objects. These are long lived objects, and may expose a security risk, especially in objects that are serialized. The LDAPConnection keeps no long lived instances of these objects.

cons - Constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

bind

public void bind(int version,
                 java.lang.String dn,
                 java.lang.String passwd,
                 LDAPConstraints cons)
          throws LDAPException

Deprecated. replaced by bind(int, String, byte[], LDAPConstraints)

Synchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name, password, LDAP version, and constraints.

If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object has already authenticated, the old authentication is discarded.

Parameters:

version - The LDAP protocol version, use LDAP_V3. LDAP_V2 is not supported.

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.

Note: the application should use care in the use of String password objects. These are long lived objects, and may expose a security risk, especially in objects that are serialized. The LDAPConnection keeps no long lived instances of these objects.

cons - The constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

bind

public void bind(int version,
                 java.lang.String dn,
                 byte[] passwd)
          throws LDAPException

Synchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name, password, and LDAP version.

If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object has already authenticated, the old authentication is discarded.

Parameters:

version - The version of the LDAP protocol to use in the bind, use LDAP_V3. LDAP_V2 is not supported.

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.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

bind

public void bind(int version,
                 java.lang.String dn,
                 byte[] passwd,
                 LDAPConstraints cons)
          throws LDAPException

Synchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name, password, LDAP version, and constraints.

If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object has already authenticated, the old authentication is discarded.

Parameters:

version - The LDAP protocol version, use LDAP_V3. LDAP_V2 is not supported.

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.

cons - The constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

bind

public LDAPResponseQueue bind(int version,
                              java.lang.String dn,
                              byte[] passwd,
                              LDAPResponseQueue queue)
                       throws LDAPException

Asynchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name, password, LDAP version, and queue.

If the object has been disconnected from an LDAP server, this method attempts to reconnect to the server. If the object has already authenticated, the old authentication is discarded.

Parameters:

version - The LDAP protocol version, use LDAP_V3. LDAP_V2 is not supported.

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.

queue - Handler for messages returned from a server in response to this request. If it is null, a queue object is created internally.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

bind

public LDAPResponseQueue bind(int version,
                              java.lang.String dn,
                              byte[] passwd,
                              LDAPResponseQueue queue,
                              LDAPConstraints cons)
                       throws LDAPException

Asynchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name, password, LDAP version, queue, and constraints.

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 - The LDAP protocol version, use LDAP_V3. LDAP_V2 is not supported.

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.

queue - Handler for messages returned from a server in response to this request. If it is null, a queue object is created internally.

cons - Constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

bind

public void bind(java.lang.String dn,
                 java.lang.String authzId,
                 java.util.Map props,
                 java.lang.Object cbh)
          throws LDAPException

Synchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name and the specified set of mechanisms.

If none of the requested SASL mechanisms is 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 has already authenticated, the old authentication is discarded. If mechanisms is null, or if the first version of the method is called, the LDAP server will be interrogated for its supportedSaslMechanisms attribute of its root DSE. See RFC 2251 for a discussion of the SASL classes.

Parameters:

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.

authzId - If not null and not empty, specifies an LDAP authzId to pass to the SASL layer. If null or empty, the authzId will be treated as an empty string and processed as per RFC 2222.

props - The optional qualifiers for the authentication session.

cbh - A class which may be called by the SASL client implementation to obtain additional information required, such as additional credentials. If cbh is not of type javax.security.auth.callback.CallbackHandler, a RuntimeException will be thrown.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

bind

public void bind(java.lang.String dn,
                 java.lang.String authzId,
                 java.util.Map props,
                 java.lang.Object cbh,
                 LDAPConstraints cons)
          throws LDAPException

Synchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name and the specified set of mechanisms.

If none of the requested SASL mechanisms is 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 has already authenticated, the old authentication is discarded. If mechanisms is null, or if the first version of the method is called, the LDAP server will be interrogated for its supportedSaslMechanisms attribute of its root DSE. See RFC 2251 for a discussion of the SASL classes.

Parameters:

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.

authzId - If not null and not empty, specifies an LDAP authzId to pass to the SASL layer. If null or empty, the authzId will be treated as an empty string and processed as per RFC 2222.

props - The optional qualifiers for the authentication session.

cbh - A class which may be called by the SASL client implementation to obtain additional information required, such as additional credentials. If cbh is not of type javax.security.auth.callback.CallbackHandler, a RuntimeException will be thrown.

cons - Constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

bind

public void bind(java.lang.String dn,
                 java.lang.String authzId,
                 java.lang.String[] mechanisms,
                 java.util.Map props,
                 java.lang.Object cbh)
          throws LDAPException

Synchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name and the specified set of mechanisms.

If none of the requested SASL mechanisms is 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 has already authenticated, the old authentication is discarded. If mechanisms is null, or if the first version of the method is called, the LDAP server will be interrogated for its supportedSaslMechanisms attribute of its root DSE. See RFC 2251 for a discussion of the SASL classes.

Parameters:

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.

authzId - If not null and not empty, specifies an LDAP authzId to pass to the SASL layer. If null or empty, the authzId will be treated as an empty string and processed as per RFC 2222.

mechanisms - An array of IANA-registered SASL mechanisms which the client is willing to use for authentication.

props - The optional qualifiers for the authentication session.

cbh - A class which may be called by the SASL client implementation to obtain additional information required, such as additional credentials. If cbh is not of type javax.security.auth.callback.CallbackHandler, a RuntimeException will be thrown.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

bind

public void bind(java.lang.String dn,
                 java.lang.String authzId,
                 java.lang.String[] mechanisms,
                 java.util.Map props,
                 java.lang.Object cbh,
                 LDAPConstraints cons)
          throws LDAPException

Synchronously authenticates to the LDAP server (that the object is currently connected to) using the specified name and the specified set of mechanisms.

If none of the requested SASL mechanisms is 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 has already authenticated, the old authentication is discarded. If mechanisms is null, or if the first version of the method is called, the LDAP server will be interrogated for its supportedSaslMechanisms attribute of its root DSE. See RFC 2251 for a discussion of the SASL classes.

Parameters:

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.

authzId - If not null and not empty, specifies an LDAP authzId to pass to the SASL layer. If null or empty, the authzId will be treated as an empty string and processed as per RFC 2222.

mechanisms - An array of IANA-registered SASL mechanisms which the client is willing to use for authentication.

props - The optional qualifiers for the authentication session.

cbh - A class which may be called by the SASL client implementation to obtain additional information required, such as additional credentials. If cbh is not of type javax.security.auth.callback.CallbackHandler, a RuntimeException will be thrown.

cons - Constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

compare

public boolean compare(java.lang.String dn,
                       LDAPAttribute attr)
                throws LDAPException

Synchronously checks to see if an entry contains an attribute with a specified value.

Parameters:

dn - The distinguished name of the entry to use in the comparison.

attr - The attribute to compare against the entry. The method checks to see if the entry has an attribute with the same name and value as this attribute.

Returns:

True if the entry has the value, and false if the entry does not have the value or the attribute.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

compare

public boolean compare(java.lang.String dn,
                       LDAPAttribute attr,
                       LDAPConstraints cons)
                throws LDAPException

Synchronously checks to see if an entry contains an attribute with a specified value, using the specified constraints.

Parameters:

dn - The distinguished name of the entry to use in the comparison.

attr - The attribute to compare against the entry. The method checks to see if the entry has an attribute with the same name and value as this attribute.

cons - Constraints specific to the operation.

Returns:

True if the entry has the value, and false if the entry does not have the value or the attribute.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

compare

public LDAPResponseQueue compare(java.lang.String dn,
                                 LDAPAttribute attr,
                                 LDAPResponseQueue queue)
                          throws LDAPException

Asynchronously compares an attribute value with one in the directory, using the specified queue.

Please note that a successful completion of this command results in one of two status codes: LDAPException.COMPARE_TRUE if the entry has the value, and LDAPException.COMPARE_FALSE if the entry does not have the value or the attribute.

Parameters:

dn - The distinguished name of the entry containing an attribute to compare.

attr - An attribute to compare.

queue - The queue for messages returned from a server in response to this request. If it is null, a queue object is created internally.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

See Also:

LDAPException.COMPARE_TRUE, LDAPException.COMPARE_FALSE

compare

public LDAPResponseQueue compare(java.lang.String dn,
                                 LDAPAttribute attr,
                                 LDAPResponseQueue queue,
                                 LDAPConstraints cons)
                          throws LDAPException

Asynchronously compares an attribute value with one in the directory, using the specified queue and contraints.

Please note that a successful completion of this command results in one of two status codes: LDAPException.COMPARE_TRUE if the entry has the value, and LDAPException.COMPARE_FALSE if the entry does not have the value or the attribute.

Parameters:

dn - The distinguished name of the entry containing an attribute to compare.

attr - An attribute to compare.

queue - Handler for messages returned from a server in response to this request. If it is null, a queue object is created internally.

cons - Constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

See Also:

LDAPException.COMPARE_TRUE, LDAPException.COMPARE_FALSE

connect

public void connect(java.lang.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. At this point, there is no authentication, and any operations are conducted as an anonymous client.

When more than one host name is specified, each host is contacted in turn until a connection can be established.

Parameters:

host - A host name or a dotted string representing the IP address of a host running an LDAP server. It may also contain a list of host names, space-delimited. Each host name can include a trailing colon and port number.

port - The TCP or UDP port number to connect to or contact. The default LDAP port is 389. The port parameter is ignored for any host hame which includes a colon and port number.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

delete

public void delete(java.lang.String dn)
            throws LDAPException

Synchronously deletes the entry with the specified distinguished name from the directory.

Note: A Delete operation will not remove an entry that contains subordinate entries, nor will it dereference alias entries.

Parameters:

dn - The distinguished name of the entry to delete.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

delete

public void delete(java.lang.String dn,
                   LDAPConstraints cons)
            throws LDAPException

Synchronously deletes the entry with the specified distinguished name from the directory, using the specified constraints.

Note: A Delete operation will not remove an entry that contains subordinate entries, nor will it dereference alias entries.

Parameters:

dn - The distinguished name of the entry to delete.

cons - Constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

delete

public LDAPResponseQueue delete(java.lang.String dn,
                                LDAPResponseQueue queue)
                         throws LDAPException

Asynchronously deletes the entry with the specified distinguished name from the directory and returns the results to the specified queue.

Note: A Delete operation will not remove an entry that contains subordinate entries, nor will it dereference alias entries.

Parameters:

dn - The distinguished name of the entry to modify.

queue - The queue for messages returned from a server in response to this request. If it is null, a queue object is created internally.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

delete

public LDAPResponseQueue delete(java.lang.String dn,
                                LDAPResponseQueue queue,
                                LDAPConstraints cons)
                         throws LDAPException

Asynchronously deletes the entry with the specified distinguished name from the directory, using the specified contraints and queue.

Note: A Delete operation will not remove an entry that contains subordinate entries, nor will it dereference alias entries.

Parameters:

dn - The distinguished name of the entry to delete.

queue - The queue for messages returned from a server in response to this request. If it is null, a queue object is created internally.

cons - The constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

disconnect

public void disconnect()
                throws LDAPException

Synchronously disconnects from the LDAP server.

Before the object can perform LDAP operations again, it must reconnect to the server by calling connect.

The disconnect method abandons any outstanding requests, issues an unbind request to the server, and then closes the socket.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

disconnect

public void disconnect(LDAPConstraints cons)
                throws LDAPException

Synchronously disconnects from the LDAP server.

Before the object can perform LDAP operations again, it must reconnect to the server by calling connect.

The disconnect method abandons any outstanding requests, issues an unbind request to the server, and then closes the socket.

Parameters:

cons - LDPConstraints to be set with the unbind request

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

extendedOperation

public LDAPExtendedResponse extendedOperation(LDAPExtendedOperation op)
                                       throws LDAPException

Provides a synchronous means to access extended, non-mandatory operations offered by a particular LDAPv3 compliant server.

Parameters:

op - The object which contains (1) an identifier of an extended operation which should be recognized by the particular LDAP server this client is connected to and (2) an operation-specific sequence of octet strings or BER-encoded values.

Returns:

An operation-specific object, containing an ID and either an octet string or BER-encoded values.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

extendedOperation

public LDAPExtendedResponse extendedOperation(LDAPExtendedOperation op,
                                              LDAPConstraints cons)
                                       throws LDAPException

Provides a synchronous means to access extended, non-mandatory operations offered by a particular LDAPv3 compliant server.

Parameters:

op - The object which contains (1) an identifier of an extended operation which should be recognized by the particular LDAP server this client is connected to and (2) an operation-specific sequence of octet strings or BER-encoded values.

cons - The constraints specific to the operation.

Returns:

An operation-specific object, containing an ID and either an octet string or BER-encoded values.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

extendedOperation

public LDAPResponseQueue extendedOperation(LDAPExtendedOperation op,
                                           LDAPResponseQueue queue)
                                    throws LDAPException

Provides an asynchronous means to access extended, non-mandatory operations offered by a particular LDAPv3 compliant server.

Parameters:

op - The object which contains (1) an identifier of an extended operation which should be recognized by the particular LDAP server this client is connected to and (2) an operation-specific sequence of octet strings or BER-encoded values.

queue - The queue for messages returned from a server in response to this request. If it is null, a queue object is created internally.

Returns:

An operation-specific object, containing an ID and either an octet string or BER-encoded values.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

extendedOperation

public LDAPResponseQueue extendedOperation(LDAPExtendedOperation op,
                                           LDAPConstraints cons,
                                           LDAPResponseQueue queue)
                                    throws LDAPException

Provides an asynchronous means to access extended, non-mandatory operations offered by a particular LDAPv3 compliant server.

Parameters:

op - The object which contains (1) an identifier of an extended operation which should be recognized by the particular LDAP server this client is connected to and (2) an operation- specific sequence of octet strings or BER-encoded values.

queue - The queue for messages returned from a server in response to this request. If it is null, a queue object is created internally.

cons - The constraints specific to this operation.

Returns:

An operation-specific object, containing an ID and either an octet string or BER-encoded values.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

makeExtendedOperation

protected LDAPMessage makeExtendedOperation(LDAPExtendedOperation op,
                                            LDAPConstraints cons)
                                     throws LDAPException

Formulates the extended operation, constraints into an LDAPMessage and returns the LDAPMessage. This is used by extendedOperation and startTLS which needs the LDAPMessage to get the MessageID.

Throws:

LDAPException

getResponseControls

public LDAPControl[] getResponseControls()

Returns the Server Controls associated with the most recent response to a synchronous request on this connection object, or null if the latest response contained no Server Controls. The method always returns null for asynchronous requests. For asynchronous requests, the response controls are available in LDAPMessage.

Returns:

The server controls associated with the most recent response to a synchronous request or null if the response contains no server controls.

See Also:

LDAPMessage.getControls()

modify

public void modify(java.lang.String dn,
                   LDAPModification mod)
            throws LDAPException

Synchronously makes a single change to an existing entry in the directory.

For example, this modify method 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 be made and the LDAPAttribute value to be changed.

If the request fails with LDAPException.CONNECT_ERROR, it is indeterminate whether or not the server made the modification.

Parameters:

dn - The distinguished name of the entry to modify.

mod - A single change to be made to the entry.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

modify

public void modify(java.lang.String dn,
                   LDAPModification mod,
                   LDAPConstraints cons)
            throws LDAPException

Synchronously makes a single change to an existing entry in the directory, using the specified constraints.

For example, this modify method 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 be made and the LDAPAttribute value to be changed.

If the request fails with LDAPException.CONNECT_ERROR, it is indeterminate whether or not the server made the modification.

Parameters:

dn - The distinguished name of the entry to modify.

mod - A single change to be made to the entry.

cons - The constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

modify

public void modify(java.lang.String dn,
                   LDAPModification[] mods)
            throws LDAPException

Synchronously makes a set of changes to an existing entry in the directory.

For example, this modify method changes attribute values, adds new attribute values, or removes existing attribute values.

Because the server applies all changes in an LDAPModification array atomically, the application can expect that no changes have been performed if an error is returned. If the request fails with LDAPException.CONNECT_ERROR, it is indeterminate whether or not the server made the modifications.

Parameters:

dn - Distinguished name of the entry to modify.

mods - The changes to be made to the entry.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

modify

public void modify(java.lang.String dn,
                   LDAPModification[] mods,
                   LDAPConstraints cons)
            throws LDAPException

Synchronously makes a set of changes to an existing entry in the directory, using the specified constraints.

For example, this modify method changes attribute values, adds new attribute values, or removes existing attribute values.

Because the server applies all changes in an LDAPModification array atomically, the application can expect that no changes have been performed if an error is returned. If the request fails with LDAPException.CONNECT_ERROR, it is indeterminate whether or not the server made the modifications.

Parameters:

dn - The distinguished name of the entry to modify.

mods - The changes to be made to the entry.

cons - The constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

modify

public LDAPResponseQueue modify(java.lang.String dn,
                                LDAPModification mod,
                                LDAPResponseQueue queue)
                         throws LDAPException

Asynchronously makes a single change to an existing entry in the directory.

For example, this modify method can change the value of an attribute, add a new attribute value, or remove an existing attribute value.

The LDAPModification object specifies both the change to be made and the LDAPAttribute value to be changed.

If the request fails with LDAPException.CONNECT_ERROR, it is indeterminate whether or not the server made the modification.

Parameters:

dn - Distinguished name of the entry to modify.

mod - A single change to be made to the entry.

queue - Handler for messages returned from a server in response to this request. If it is null, a queue object is created internally.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

modify

public LDAPResponseQueue modify(java.lang.String dn,
                                LDAPModification mod,
                                LDAPResponseQueue queue,
                                LDAPConstraints cons)
                         throws LDAPException

Asynchronously makes a single change to an existing entry in the directory, using the specified constraints and queue.

For example, this modify method can change the value of an attribute, add a new attribute value, or remove an existing attribute value.

The LDAPModification object specifies both the change to be made and the LDAPAttribute value to be changed.

If the request fails with LDAPException.CONNECT_ERROR, it is indeterminate whether or not the server made the modification.

Parameters:

dn - Distinguished name of the entry to modify.

mod - A single change to be made to the entry.

queue - Handler for messages returned from a server in response to this request. If it is null, a queue object is created internally.

cons - Constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

modify

public LDAPResponseQueue modify(java.lang.String dn,
                                LDAPModification[] mods,
                                LDAPResponseQueue queue)
                         throws LDAPException

Asynchronously makes a set of changes to an existing entry in the directory.

For example, this modify method can change attribute values, add new attribute values, or remove existing attribute values.

Because the server applies all changes in an LDAPModification array atomically, the application can expect that no changes have been performed if an error is returned. If the request fails with LDAPException.CONNECT_ERROR, it is indeterminate whether or not the server made the modifications.

Parameters:

dn - The distinguished name of the entry to modify.

mods - The changes to be made to the entry.

queue - The queue for messages returned from a server in response to this request. If it is null, a queue object is created internally.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

modify

public LDAPResponseQueue modify(java.lang.String dn,
                                LDAPModification[] mods,
                                LDAPResponseQueue queue,
                                LDAPConstraints cons)
                         throws LDAPException

Asynchronously makes a set of changes to an existing entry in the directory, using the specified constraints and queue.

For example, this modify method can change attribute values, add new attribute values, or remove existing attribute values.

Because the server applies all changes in an LDAPModification array atomically, the application can expect that no changes have been performed if an error is returned. If the request fails with LDAPException.CONNECT_ERROR, it is indeterminate whether or not the server made the modifications.

Parameters:

dn - The distinguished name of the entry to modify.

mods - The changes to be made to the entry.

queue - The queue for messages returned from a server in response to this request. If it is null, a queue object is created internally.

cons - Constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

read

public LDAPEntry read(java.lang.String dn)
               throws LDAPException

Synchronously reads the entry for the specified distiguished name (DN) and retrieves all attributes for the entry.

Parameters:

dn - The distinguished name of the entry to retrieve.

Returns:

the LDAPEntry read from the server.

Throws:

LDAPException - if the object was not found

read

public LDAPEntry read(java.lang.String dn,
                      LDAPSearchConstraints cons)
               throws LDAPException

Synchronously reads the entry for the specified distiguished name (DN), using the specified constraints, and retrieves all attributes for the entry.

Parameters:

dn - The distinguished name of the entry to retrieve.

cons - The constraints specific to the operation.

Returns:

the LDAPEntry read from the server

Throws:

LDAPException - if the object was not found

read

public LDAPEntry read(java.lang.String dn,
                      java.lang.String[] attrs)
               throws LDAPException

Synchronously reads the entry for the specified distinguished name (DN) and retrieves only the specified attributes from the entry.

Parameters:

dn - The distinguished name of the entry to retrieve.

attrs - The names of the attributes to retrieve.

Returns:

the LDAPEntry read from the server

Throws:

LDAPException - if the object was not found

read

public LDAPEntry read(java.lang.String dn,
                      java.lang.String[] attrs,
                      LDAPSearchConstraints cons)
               throws LDAPException

Synchronously reads the entry for the specified distinguished name (DN), using the specified constraints, and retrieves only the specified attributes from the entry.

Parameters:

dn - The distinguished name of the entry to retrieve.

attrs - The names of the attributes to retrieve.

cons - The constraints specific to the operation.

Returns:

the LDAPEntry read from the server

Throws:

LDAPException - if the object was not found

read

public static LDAPEntry read(LDAPUrl toGet)
                      throws LDAPException

Synchronously reads the entry specified by the LDAP URL.

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

If the URL specifies a filter and scope, they 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.

Parameters:

toGet - LDAP URL specifying the entry to read.

Returns:

The entry specified by the base DN.

Throws:

LDAPException - if the object was not found

read

public static LDAPEntry read(LDAPUrl toGet,
                             LDAPSearchConstraints cons)
                      throws LDAPException

Synchronously reads the entry specified by the LDAP URL, using the specified constraints.

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

If the URL specifies a filter and scope, they 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.

Parameters:

toGet - LDAP URL specifying the entry to read.

cons - Constraints specific to the operation.

Returns:

The entry specified by the base DN.

Throws:

LDAPException - if the object was not found

rename

public void rename(java.lang.String dn,
                   java.lang.String newRdn,
                   boolean deleteOldRdn)
            throws LDAPException

Synchronously renames an existing entry in the directory.

Parameters:

dn - The current distinguished name of the entry.

newRdn - The new relative distinguished name for the entry.

deleteOldRdn - If true, the old name is not retained as an attribute value. If false, the old name is retained as an attribute value.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

rename

public void rename(java.lang.String dn,
                   java.lang.String newRdn,
                   boolean deleteOldRdn,
                   LDAPConstraints cons)
            throws LDAPException

Synchronously renames an existing entry in the directory, using the specified constraints.

Parameters:

dn - The current distinguished name of the entry.

newRdn - The new relative distinguished name for the entry.

deleteOldRdn - If true, the old name is not retained as an attribute value. If false, the old name is retained as an attribute value.

cons - The constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

rename

public void rename(java.lang.String dn,
                   java.lang.String newRdn,
                   java.lang.String newParentdn,
                   boolean deleteOldRdn)
            throws LDAPException

Synchronously renames an existing entry in the directory, possibly repositioning the entry in the directory tree.

Parameters:

dn - The current distinguished name of the entry.

newRdn - The new relative distinguished name for the entry.

newParentdn - The distinguished name of an existing entry which is to be the new parent of the entry.

deleteOldRdn - If true, the old name is not retained as an attribute value. If false, the old name is retained as an attribute value.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

rename

public void rename(java.lang.String dn,
                   java.lang.String newRdn,
                   java.lang.String newParentdn,
                   boolean deleteOldRdn,
                   LDAPConstraints cons)
            throws LDAPException

Synchronously renames an existing entry in the directory, using the specified constraints and possibly repositioning the entry in the directory tree.

Parameters:

dn - The current distinguished name of the entry.

newRdn - The new relative distinguished name for the entry.

newParentdn - The distinguished name of an existing entry which is to be the new parent of the entry.

deleteOldRdn - If true, the old name is not retained as an attribute value. If false, the old name is retained as an attribute value.

cons - The constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

rename

public LDAPResponseQueue rename(java.lang.String dn,
                                java.lang.String newRdn,
                                boolean deleteOldRdn,
                                LDAPResponseQueue queue)
                         throws LDAPException

Asynchronously renames an existing entry in the directory.

Parameters:

dn - The current distinguished name of the entry.

newRdn - The new relative distinguished name for the entry.

deleteOldRdn - If true, the old name is not retained as an attribute value. If false, the old name is retained as an attribute value.

queue - The queue for messages returned from a server in response to this request. If it is null, a queue object is created internally.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

rename

public LDAPResponseQueue rename(java.lang.String dn,
                                java.lang.String newRdn,
                                boolean deleteOldRdn,
                                LDAPResponseQueue queue,
                                LDAPConstraints cons)
                         throws LDAPException

Asynchronously renames an existing entry in the directory, using the specified constraints.

Parameters:

dn - The current distinguished name of the entry.

newRdn - The new relative distinguished name for the entry.

deleteOldRdn - If true, the old name is not retained as an attribute value. If false, the old name is retained as an attribute value.

queue - The queue for messages returned from a server in response to this request. If it is null, a queue object is created internally.

cons - The constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

rename

public LDAPResponseQueue rename(java.lang.String dn,
                                java.lang.String newRdn,
                                java.lang.String newParentdn,
                                boolean deleteOldRdn,
                                LDAPResponseQueue queue)
                         throws LDAPException

Asynchronously renames an existing entry in the directory, possibly repositioning the entry in the directory.

Parameters:

dn - The current distinguished name of the entry.

newRdn - The new relative distinguished name for the entry.

newParentdn - The distinguished name of an existing entry which is to be the new parent of the entry.

deleteOldRdn - If true, the old name is not retained as an attribute value. If false, the old name is retained as an attribute value.

queue - The queue for messages returned from a server in response to this request. If it is null, a queue object is created internally.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

rename

public LDAPResponseQueue rename(java.lang.String dn,
                                java.lang.String newRdn,
                                java.lang.String newParentdn,
                                boolean deleteOldRdn,
                                LDAPResponseQueue queue,
                                LDAPConstraints cons)
                         throws LDAPException

Asynchronously renames an existing entry in the directory, using the specified constraints and possibily repositioning the entry in the directory.

Parameters:

dn - The current distinguished name of the entry.

newRdn - The new relative distinguished name for the entry.

newParentdn - The distinguished name of an existing entry which is to be the new parent of the entry.

deleteOldRdn - If true, the old name is not retained as an attribute value. If false, the old name is retained as an attribute value.

queue - The queue for messages returned from a server in response to this request. If it is null, a queue object is created internally.

cons - The constraints specific to the operation.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

search

public LDAPSearchResults search(java.lang.String base,
                                int scope,
                                java.lang.String filter,
                                java.lang.String[] attrs,
                                boolean typesOnly)
                         throws LDAPException

Synchronously performs the search specified by the parameters.

Parameters:

base - The base distinguished name to search from.

scope - The scope of the entries to search. The following are the valid options:

• SCOPE_BASE - searches only the base DN
• SCOPE_ONE - searches only entries under the base DN
• SCOPE_SUB - searches the base DN and all entries within its subtree

filter - Search filter specifying the search criteria.

attrs - Names of attributes to retrieve.

typesOnly - If true, returns the names but not the values of the attributes found. If false, returns the names and values for attributes found.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

search

public LDAPSearchResults search(java.lang.String base,
                                int scope,
                                java.lang.String filter,
                                java.lang.String[] attrs,
                                boolean typesOnly,
                                LDAPSearchConstraints cons)
                         throws LDAPException

Synchronously performs the search specified by the parameters, using the specified search constraints (such as the maximum number of entries to find or the maximum time to wait for search results).

As part of the search constraints, the method allows specifying whether or not the results are to be delivered all at once or in smaller batches. If specified that the results are to be delivered in smaller batches, each iteration blocks only until the next batch of results is returned.

Parameters:

base - The base distinguished name to search from.

scope - The scope of the entries to search. The following are the valid options:

• SCOPE_BASE - searches only the base DN
• SCOPE_ONE - searches only entries under the base DN
• SCOPE_SUB - searches the base DN and all entries within its subtree

filter - The search filter specifying the search criteria.

attrs - The names of attributes to retrieve.

typesOnly - If true, returns the names but not the values of the attributes found. If false, returns the names and values for attributes found.

cons - The constraints specific to the search.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

search

public LDAPSearchQueue search(java.lang.String base,
                              int scope,
                              java.lang.String filter,
                              java.lang.String[] attrs,
                              boolean typesOnly,
                              LDAPSearchQueue queue)
                       throws LDAPException

Asynchronously performs the search specified by the parameters.

Parameters:

base - The base distinguished name to search from.

scope - The scope of the entries to search. The following are the valid options:

• SCOPE_BASE - searches only the base DN
• SCOPE_ONE - searches only entries under the base DN
• SCOPE_SUB - searches the base DN and all entries within its subtree

filter - Search filter specifying the search criteria.

attrs - Names of attributes to retrieve.

typesOnly - If true, returns the names but not the values of the attributes found. If false, returns the names and values for attributes found.

queue - Handler for messages returned from a server in response to this request. If it is null, a queue object is created internally.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

search

public LDAPSearchQueue search(java.lang.String base,
                              int scope,
                              java.lang.String filter,
                              java.lang.String[] attrs,
                              boolean typesOnly,
                              LDAPSearchQueue queue,
                              LDAPSearchConstraints cons)
                       throws LDAPException

Asynchronously performs the search specified by the parameters, also allowing specification of constraints for the search (such as the maximum number of entries to find or the maximum time to wait for search results).

Parameters:

base - The base distinguished name to search from.

scope - The scope of the entries to search. The following are the valid options:

• SCOPE_BASE - searches only the base DN
• SCOPE_ONE - searches only entries under the base DN
• SCOPE_SUB - searches the base DN and all entries within its subtree

filter - The search filter specifying the search criteria.

attrs - The names of attributes to retrieve.

typesOnly - If true, returns the names but not the values of the attributes found. If false, returns the names and values for attributes found.

queue - The queue for messages returned from a server in response to this request. If it is null, a queue object is created internally.

cons - The constraints specific to the search.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

search

public static LDAPSearchResults search(LDAPUrl toGet)
                                throws LDAPException

Synchronously performs the search specified by the LDAP URL, returning an enumerable LDAPSearchResults object.

Parameters:

toGet - The LDAP URL specifying the entry to read.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

search

public static LDAPSearchResults search(LDAPUrl toGet,
                                       LDAPSearchConstraints cons)
                                throws LDAPException

Synchronously perfoms the search specified by the LDAP URL, using the specified search constraints (such as the maximum number of entries to find or the maximum time to wait for search results).

When this method is called, a new connection is created automatically, using the host and port specified in the URL. After all search results have been received from the server, the method closes the connection (in other words, it disconnects from the LDAP server).

As part of the search constraints, a choice can be made as to whether to have the results delivered all at once or in smaller batches. If the results are to be delivered in smaller batches, each iteration blocks only until the next batch of results is returned.

Parameters:

toGet - LDAP URL specifying the entry to read.

cons - The constraints specific to the search.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

sendRequest

public LDAPMessageQueue sendRequest(LDAPMessage request,
                                    LDAPMessageQueue queue)
                             throws LDAPException

Sends an LDAP request to a directory server.

The specified the LDAP request is sent to the directory server associated with this connection using default constraints. An LDAP request object is a subclass LDAPMessage with the operation type set to one of the request types. You can build a request by using the request classes found in this package

You should note that, since LDAP requests sent to the server using sendRequest are asynchronous, automatic referral following does not apply to these requests.

Parameters:

request - The LDAP request to send to the directory server.

queue - The queue for messages returned from a server in response to this request. If it is null, a queue object is created internally.

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

See Also:

LDAPMessage.getType(), LDAPMessage.isRequest()

sendRequest

public LDAPMessageQueue sendRequest(LDAPMessage request,
                                    LDAPMessageQueue queue,
                                    LDAPConstraints cons)
                             throws LDAPException

Sends an LDAP request to a directory server.

The specified the LDAP request is sent to the directory server associated with this connection. An LDAP request object is an LDAPMessage with the operation type set to one of the request types. You can build a request by using the request classes found in this package

You should note that, since LDAP requests sent to the server using sendRequest are asynchronous, automatic referral following does not apply to these requests.

Parameters:

request - The LDAP request to send to the directory server.

queue - The queue for messages returned from a server in response to this request. If it is null, a queue object is created internally.

cons - The constraints that apply to this request

Throws:

LDAPException - A general exception which includes an error message and an LDAP error code.

See Also:

LDAPMessage.getType(), LDAPMessage.isRequest()

fetchSchema

public LDAPSchema fetchSchema(java.lang.String schemaDN)
                       throws LDAPException

Retrieves the schema associated with a particular schema DN in the directory server.

The schema DN for a particular entry is obtained by calling the getSchemaDN method of LDAPConnection

Parameters:

schemaDN - The schema DN used to fetch the schema.

Returns:

An LDAPSchema entry containing schema attributes. If the entry contains no schema attributes then the returned LDAPSchema object will be empty.

Throws:

LDAPException - This exception occurs if the schema entry cannot be retrieved with this connection.

See Also:

getSchemaDN(), getSchemaDN(String)

getSchemaDN

public java.lang.String getSchemaDN()
                             throws LDAPException

Retrieves the Distiguished Name (DN) for the schema advertised in the root DSE of the Directory Server.

The DN can be used with the methods fetchSchema and modify to retreive and extend schema definitions. The schema entry is located by reading subschemaSubentry attribute of the root DSE. This is equivalent to calling getSchemaDN(String) with the DN parameter as an empty string: getSchemaDN("").

Returns:

Distinguished Name of a schema entry in effect for the Directory.

Throws:

LDAPException - This exception occurs if the schema DN cannot be retrieved, or if the subschemaSubentry attribute associated with the root DSE contains multiple values.

See Also:

fetchSchema(java.lang.String), modify(java.lang.String, com.novell.ldap.LDAPModification)

getSchemaDN

public java.lang.String getSchemaDN(java.lang.String dn)
                             throws LDAPException

Retrieves the Distiguished Name (DN) of the schema associated with a entry in the Directory.

The DN can be used with the methods fetchSchema and modify to retreive and extend schema definitions. Reads the subschemaSubentry of the entry specified.

Parameters:

dn - Distinguished Name of any entry. The subschemaSubentry attribute is queried from this entry.

Returns:

Distinguished Name of a schema entry in effect for the entry identified by dn.

Throws:

LDAPException - This exception occurs if a null or empty value is passed as dn, if the subschemasubentry attribute cannot be retrieved, or the subschemasubentry contains multiple values.

See Also:

fetchSchema(java.lang.String), modify(java.lang.String, com.novell.ldap.LDAPModification)