public class

InitialLdapContext

extends InitialDirContext
implements LdapContext

java.lang.Object
↳	javax.naming.InitialContext
	↳	javax.naming.directory.InitialDirContext
		↳	javax.naming.ldap.InitialLdapContext

Class Overview

This class is the starting context for performing LDAPv3-style extended operations and controls.

See javax.naming.InitialContext and javax.naming.InitialDirContext for details on synchronization, and the policy for how an initial context is created.

Request Controls

When you create an initial context (InitialLdapContext), you can specify a list of request controls. These controls will be used as the request controls for any implicit LDAP "bind" operation performed by the context or contexts derived from the context. These are called connection request controls. Use getConnectControls() to get a context's connection request controls.

The request controls supplied to the initial context constructor are not used as the context request controls for subsequent context operations such as searches and lookups. Context request controls are set and updated by using setRequestControls().

As shown, there can be two different sets of request controls associated with a context: connection request controls and context request controls. This is required for those applications needing to send critical controls that might not be applicable to both the context operation and any implicit LDAP "bind" operation. A typical user program would do the following:

 InitialLdapContext lctx = new InitialLdapContext(env, critConnCtls);
 lctx.setRequestControls(critModCtls);
 lctx.modifyAttributes(name, mods);
 Controls[] respCtls =  lctx.getResponseControls();

It specifies first the critical controls for creating the initial context (critConnCtls), and then sets the context's request controls (critModCtls) for the context operation. If for some reason lctx needs to reconnect to the server, it will use critConnCtls. See the LdapContext interface for more discussion about request controls.

Service provider implementors should read the "Service Provider" section in the LdapContext class description for implementation details.

Summary

[Expand]

Inherited Constants

From interface javax.naming.Context

String	APPLET	Constant that holds the name of the environment property for specifying an applet for the initial context constructor to use when searching for other properties.
String	AUTHORITATIVE	Constant that holds the name of the environment property for specifying the authoritativeness of the service requested.
String	BATCHSIZE	Constant that holds the name of the environment property for specifying the batch size to use when returning data via the service's protocol.
String	DNS_URL	Constant that holds the name of the environment property for specifying the DNS host and domain names to use for the JNDI URL context (for example, "dns://somehost/wiz.com").
String	INITIAL_CONTEXT_FACTORY	Constant that holds the name of the environment property for specifying the initial context factory to use.
String	LANGUAGE	Constant that holds the name of the environment property for specifying the preferred language to use with the service.
String	OBJECT_FACTORIES	Constant that holds the name of the environment property for specifying the list of object factories to use.
String	PROVIDER_URL	Constant that holds the name of the environment property for specifying configuration information for the service provider to use.
String	REFERRAL	Constant that holds the name of the environment property for specifying how referrals encountered by the service provider are to be processed.
String	SECURITY_AUTHENTICATION	Constant that holds the name of the environment property for specifying the security level to use.
String	SECURITY_CREDENTIALS	Constant that holds the name of the environment property for specifying the credentials of the principal for authenticating the caller to the service.
String	SECURITY_PRINCIPAL	Constant that holds the name of the environment property for specifying the identity of the principal for authenticating the caller to the service.
String	SECURITY_PROTOCOL	Constant that holds the name of the environment property for specifying the security protocol to use.
String	STATE_FACTORIES	Constant that holds the name of the environment property for specifying the list of state factories to use.
String	URL_PKG_PREFIXES	Constant that holds the name of the environment property for specifying the list of package prefixes to use when loading in URL context factories.

From interface javax.naming.directory.DirContext

From interface javax.naming.ldap.LdapContext

[Expand]

Inherited Fields

From class javax.naming.InitialContext

Public Constructors
	InitialLdapContext() Constructs an initial context using no environment properties or connection request controls.
	InitialLdapContext(Hashtable<?, ?> environment, Control[] connCtls) Constructs an initial context using environment properties and connection request controls.

Public Methods
ExtendedResponse	extendedOperation(ExtendedRequest request) Performs an extended operation.
Control[]	getConnectControls() Retrieves the connection request controls in effect for this context.
Control[]	getRequestControls() Retrieves the request controls in effect for this context.
Control[]	getResponseControls() Retrieves the response controls produced as a result of the last method invoked on this context.
LdapContext	newInstance(Control[] reqCtls) Creates a new instance of this context initialized using request controls.
void	reconnect(Control[] connCtls) Reconnects to the LDAP server using the supplied controls and this context's environment.
void	setRequestControls(Control[] requestControls) Sets the request controls for methods subsequently invoked on this context.

[Expand]

Inherited Methods

From class javax.naming.directory.InitialDirContext

From class javax.naming.InitialContext

Object	addToEnvironment(String propName, Object propVal) Adds a new environment property to the environment of this context.
void	bind(Name name, Object obj) Binds a name to an object.
void	bind(String name, Object obj) Binds a name to an object.
void	close() Closes this context.
String	composeName(String name, String prefix) Composes the name of this context with a name relative to this context.
Name	composeName(Name name, Name prefix) Composes the name of this context with a name relative to this context.
Context	createSubcontext(Name name) Creates and binds a new context.
Context	createSubcontext(String name) Creates and binds a new context.
void	destroySubcontext(Name name) Destroys the named context and removes it from the namespace.
void	destroySubcontext(String name) Destroys the named context and removes it from the namespace.
static <T> T	doLookup(Name name) A static method to retrieve the named object.
static <T> T	doLookup(String name) A static method to retrieve the named object.
Context	getDefaultInitCtx() Retrieves the initial context by calling `NamingManager.getInitialContext()` and cache it in defaultInitCtx.
Hashtable<?, ?>	getEnvironment() Retrieves the environment in effect for this context.
String	getNameInNamespace() Retrieves the full name of this context within its own namespace.
NameParser	getNameParser(Name name) Retrieves the parser associated with the named context.
NameParser	getNameParser(String name) Retrieves the parser associated with the named context.
Context	getURLOrDefaultInitCtx(String name) Retrieves a context for resolving the string name `name`.
Context	getURLOrDefaultInitCtx(Name name) Retrieves a context for resolving `name`.
void	init(Hashtable<?, ?> environment) Initializes the initial context using the supplied environment.
NamingEnumeration<NameClassPair>	list(String name) Enumerates the names bound in the named context, along with the class names of objects bound to them.
NamingEnumeration<NameClassPair>	list(Name name) Enumerates the names bound in the named context, along with the class names of objects bound to them.
NamingEnumeration<Binding>	listBindings(Name name) Enumerates the names bound in the named context, along with the objects bound to them.
NamingEnumeration<Binding>	listBindings(String name) Enumerates the names bound in the named context, along with the objects bound to them.
Object	lookup(String name) Retrieves the named object.
Object	lookup(Name name) Retrieves the named object.
Object	lookupLink(String name) Retrieves the named object, following links except for the terminal atomic component of the name.
Object	lookupLink(Name name) Retrieves the named object, following links except for the terminal atomic component of the name.
void	rebind(String name, Object obj) Binds a name to an object, overwriting any existing binding.
void	rebind(Name name, Object obj) Binds a name to an object, overwriting any existing binding.
Object	removeFromEnvironment(String propName) Removes an environment property from the environment of this context.
void	rename(String oldName, String newName) Binds a new name to the object bound to an old name, and unbinds the old name.
void	rename(Name oldName, Name newName) Binds a new name to the object bound to an old name, and unbinds the old name.
void	unbind(Name name) Unbinds the named object.
void	unbind(String name) Unbinds the named object.

From class java.lang.Object

Object	clone() Creates and returns a copy of this object.
boolean	equals(Object obj) Indicates whether some other object is "equal to" this one.
void	finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
final Class<?>	getClass() Returns the runtime class of this `Object`.
int	hashCode() Returns a hash code value for the object.
final void	notify() Wakes up a single thread that is waiting on this object's monitor.
final void	notifyAll() Wakes up all threads that are waiting on this object's monitor.
String	toString() Returns a string representation of the object.
final void	wait() Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object.
final void	wait(long timeout, int nanos) Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.
final void	wait(long timeout) Causes the current thread to wait until either another thread invokes the `notify()` method or the `notifyAll()` method for this object, or a specified amount of time has elapsed.

From interface javax.naming.Context

abstract Object	addToEnvironment(String propName, Object propVal) Adds a new environment property to the environment of this context.
abstract void	bind(Name name, Object obj) Binds a name to an object.
abstract void	bind(String name, Object obj) Binds a name to an object.
abstract void	close() Closes this context.
abstract String	composeName(String name, String prefix) Composes the name of this context with a name relative to this context.
abstract Name	composeName(Name name, Name prefix) Composes the name of this context with a name relative to this context.
abstract Context	createSubcontext(Name name) Creates and binds a new context.
abstract Context	createSubcontext(String name) Creates and binds a new context.
abstract void	destroySubcontext(Name name) Destroys the named context and removes it from the namespace.
abstract void	destroySubcontext(String name) Destroys the named context and removes it from the namespace.
abstract Hashtable<?, ?>	getEnvironment() Retrieves the environment in effect for this context.
abstract String	getNameInNamespace() Retrieves the full name of this context within its own namespace.
abstract NameParser	getNameParser(Name name) Retrieves the parser associated with the named context.
abstract NameParser	getNameParser(String name) Retrieves the parser associated with the named context.
abstract NamingEnumeration<NameClassPair>	list(String name) Enumerates the names bound in the named context, along with the class names of objects bound to them.
abstract NamingEnumeration<NameClassPair>	list(Name name) Enumerates the names bound in the named context, along with the class names of objects bound to them.
abstract NamingEnumeration<Binding>	listBindings(Name name) Enumerates the names bound in the named context, along with the objects bound to them.
abstract NamingEnumeration<Binding>	listBindings(String name) Enumerates the names bound in the named context, along with the objects bound to them.
abstract Object	lookup(String name) Retrieves the named object.
abstract Object	lookup(Name name) Retrieves the named object.
abstract Object	lookupLink(String name) Retrieves the named object, following links except for the terminal atomic component of the name.
abstract Object	lookupLink(Name name) Retrieves the named object, following links except for the terminal atomic component of the name.
abstract void	rebind(String name, Object obj) Binds a name to an object, overwriting any existing binding.
abstract void	rebind(Name name, Object obj) Binds a name to an object, overwriting any existing binding.
abstract Object	removeFromEnvironment(String propName) Removes an environment property from the environment of this context.
abstract void	rename(String oldName, String newName) Binds a new name to the object bound to an old name, and unbinds the old name.
abstract void	rename(Name oldName, Name newName) Binds a new name to the object bound to an old name, and unbinds the old name.
abstract void	unbind(Name name) Unbinds the named object.
abstract void	unbind(String name) Unbinds the named object.

From interface javax.naming.directory.DirContext

From interface javax.naming.ldap.LdapContext

Public Constructors

public InitialLdapContext ()

Constructs an initial context using no environment properties or connection request controls. Equivalent to new InitialLdapContext(null, null).

Throws

NamingException	if a naming exception is encountered

public InitialLdapContext (Hashtable<?, ?> environment, Control[] connCtls)

Constructs an initial context using environment properties and connection request controls. See javax.naming.InitialContext for a discussion of environment properties.

This constructor will not modify its parameters or save references to them, but may save a clone or copy.

connCtls is used as the underlying context instance's connection request controls. See the class description for details.

Parameters

environment	environment used to create the initial DirContext. Null indicates an empty environment.
connCtls	connection request controls for the initial context. If null, no connection request controls are used.

Throws

NamingException	if a naming exception is encountered

Public Methods

public ExtendedResponse extendedOperation (ExtendedRequest request)

Performs an extended operation. This method is used to support LDAPv3 extended operations.

Parameters

request	The non-null request to be performed.

Returns

The possibly null response of the operation. null means the operation did not generate any response.

Throws

NamingException

public Control[] getConnectControls ()

Retrieves the connection request controls in effect for this context. The controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

Returns

A possibly-null array of controls. null means no connect controls have been set for this context.

Throws

NamingException

public Control[] getRequestControls ()

Retrieves the request controls in effect for this context. The request controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

Returns

A possibly-null array of controls. null means no request controls have been set for this context.

Throws

NamingException

public Control[] getResponseControls ()

Retrieves the response controls produced as a result of the last method invoked on this context. The response controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

These response controls might have been generated by a successful or failed operation.

When a context method that may return response controls is invoked, response controls from the previous method invocation are cleared. getResponseControls() returns all of the response controls generated by LDAP operations used by the context method in the order received from the LDAP server. Invoking getResponseControls() does not clear the response controls. You can call it many times (and get back the same controls) until the next context method that may return controls is invoked.

Returns

A possibly null array of controls. If null, the previous method invoked on this context did not produce any controls.

Throws

NamingException

public LdapContext newInstance (Control[] reqCtls)

Creates a new instance of this context initialized using request controls. This method is a convenience method for creating a new instance of this context for the purposes of multithreaded access. For example, if multiple threads want to use different context request controls, each thread may use this method to get its own copy of this context and set/get context request controls without having to synchronize with other threads.

The new context has the same environment properties and connection request controls as this context. See the class description for details. Implementations might also allow this context and the new context to share the same network connection or other resources if doing so does not impede the independence of either context.

Parameters

reqCtls	The possibly null request controls to use for the new context. If null, the context is initialized with no request controls.

Returns

A non-null LdapContext instance.

Throws

NamingException

public void reconnect (Control[] connCtls)

Reconnects to the LDAP server using the supplied controls and this context's environment.

This method is a way to explicitly initiate an LDAP "bind" operation. For example, you can use this method to set request controls for the LDAP "bind" operation, or to explicitly connect to the server to get response controls returned by the LDAP "bind" operation.

This method sets this context's connCtls to be its new connection request controls. This context's context request controls are not affected. After this method has been invoked, any subsequent implicit reconnections will be done using connCtls. connCtls are also used as connection request controls for new context instances derived from this context. These connection request controls are not affected by setRequestControls().

Service provider implementors should read the "Service Provider" section in the class description for implementation details.

Parameters

connCtls	The possibly null controls to use. If null, no controls are used.

Throws

NamingException

public void setRequestControls (Control[] requestControls)

Sets the request controls for methods subsequently invoked on this context. The request controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

This removes any previous request controls and adds requestControls for use by subsequent methods invoked on this context. This method does not affect this context's connection request controls.

Note that requestControls will be in effect until the next invocation of setRequestControls(). You need to explicitly invoke setRequestControls() with null or an empty array to clear the controls if you don't want them to affect the context methods any more. To check what request controls are in effect for this context, use getRequestControls().

Parameters

requestControls	The possibly null controls to use. If null, no controls are used.

Throws

NamingException

Interfaces

Classes

Exceptions

InitialLdapContext

Class Overview

Request Controls

See Also

Summary

Public Constructors

public InitialLdapContext ()

Throws

public InitialLdapContext (Hashtable<?, ?> environment, Control[] connCtls)

Parameters

Throws

See Also

Public Methods

public ExtendedResponse extendedOperation (ExtendedRequest request)

Parameters

Returns

Throws

public Control[] getConnectControls ()

Returns

Throws

public Control[] getRequestControls ()

Returns

Throws

public Control[] getResponseControls ()

Returns

Throws

public LdapContext newInstance (Control[] reqCtls)

Parameters

Returns

Throws

public void reconnect (Control[] connCtls)

Parameters

Throws

public void setRequestControls (Control[] requestControls)

Parameters

Throws