Class InitialLdapContext

java.lang.Object

javax.naming.InitialContext

javax.naming.directory.InitialDirContext

javax.naming.ldap.InitialLdapContext

All Implemented Interfaces:

Context, DirContext, LdapContext

public class InitialLdapContext
extends InitialDirContext
implements LdapContext

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.

Since:

1.3

See Also:

• LdapContext
• InitialContext
• InitialDirContext
• NamingManager.setInitialContextFactoryBuilder(InitialContextFactoryBuilder)

Field Summary

Fields declared in class InitialContext

defaultInitCtx, gotDefault, myProps

Modifier and Type	Field	Description
protected Context	defaultInitCtx	Field holding the result of calling NamingManager.getInitialContext().
protected boolean	gotDefault	Field indicating whether the initial context has been obtained by calling NamingManager.getInitialContext().
protected Hashtable<Object,Object>	myProps	The environment associated with this InitialContext.

Fields declared in interface Context

AUTHORITATIVE, BATCHSIZE, DNS_URL, INITIAL_CONTEXT_FACTORY, LANGUAGE, OBJECT_FACTORIES, PROVIDER_URL, REFERRAL, SECURITY_AUTHENTICATION, SECURITY_CREDENTIALS, SECURITY_PRINCIPAL, SECURITY_PROTOCOL, STATE_FACTORIES, URL_PKG_PREFIXES

Modifier and Type	Field	Description
static final String	AUTHORITATIVE	Constant that holds the name of the environment property for specifying the authoritativeness of the service requested.
static final 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.
static final 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").
static final String	INITIAL_CONTEXT_FACTORY	Constant that holds the name of the environment property for specifying the initial context factory to use.
static final String	LANGUAGE	Constant that holds the name of the environment property for specifying the preferred language to use with the service.
static final String	OBJECT_FACTORIES	Constant that holds the name of the environment property for specifying the list of object factories to use.
static final String	PROVIDER_URL	Constant that holds the name of the environment property for specifying configuration information for the service provider to use.
static final String	REFERRAL	Constant that holds the name of the environment property for specifying how referrals encountered by the service provider are to be processed.
static final String	SECURITY_AUTHENTICATION	Constant that holds the name of the environment property for specifying the security level to use.
static final 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.
static final 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.
static final String	SECURITY_PROTOCOL	Constant that holds the name of the environment property for specifying the security protocol to use.
static final String	STATE_FACTORIES	Constant that holds the name of the environment property for specifying the list of state factories to use.
static final 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.

Fields declared in interface DirContext

ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE

Modifier and Type	Field	Description
static final int	ADD_ATTRIBUTE	This constant specifies to add an attribute with the specified values.
static final int	REMOVE_ATTRIBUTE	This constant specifies to delete the specified attribute values from the attribute.
static final int	REPLACE_ATTRIBUTE	This constant specifies to replace an attribute with specified values.

Fields declared in interface LdapContext

CONTROL_FACTORIES

Modifier and Type	Field	Description
static final String	CONTROL_FACTORIES	Constant that holds the name of the environment property for specifying the list of control factories to use.

Constructor Summary

Constructors

Constructor	Description
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.

Method Summary

Modifier and Type	Method	Description
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.

Methods declared in class InitialDirContext

bind, bind, createSubcontext, createSubcontext, getAttributes, getAttributes, getAttributes, getAttributes, getSchema, getSchema, getSchemaClassDefinition, getSchemaClassDefinition, modifyAttributes, modifyAttributes, modifyAttributes, modifyAttributes, rebind, rebind, search, search, search, search, search, search, search, search

Modifier and Type	Method	Description
void	bind(String name, Object obj, Attributes attrs)	Binds a name to an object, along with associated attributes.
void	bind(Name name, Object obj, Attributes attrs)	Binds a name to an object, along with associated attributes.
DirContext	createSubcontext(String name, Attributes attrs)	Creates and binds a new context, along with associated attributes.
DirContext	createSubcontext(Name name, Attributes attrs)	Creates and binds a new context, along with associated attributes.
Attributes	getAttributes(String name)	Retrieves all of the attributes associated with a named object.
Attributes	getAttributes(String name, String[] attrIds)	Retrieves selected attributes associated with a named object.
Attributes	getAttributes(Name name)	Retrieves all of the attributes associated with a named object.
Attributes	getAttributes(Name name, String[] attrIds)	Retrieves selected attributes associated with a named object.
DirContext	getSchema(String name)	Retrieves the schema associated with the named object.
DirContext	getSchema(Name name)	Retrieves the schema associated with the named object.
DirContext	getSchemaClassDefinition(String name)	Retrieves a context containing the schema objects of the named object's class definitions.
DirContext	getSchemaClassDefinition(Name name)	Retrieves a context containing the schema objects of the named object's class definitions.
void	modifyAttributes(String name, int mod_op, Attributes attrs)	Modifies the attributes associated with a named object.
void	modifyAttributes(String name, ModificationItem[] mods)	Modifies the attributes associated with a named object using an ordered list of modifications.
void	modifyAttributes(Name name, int mod_op, Attributes attrs)	Modifies the attributes associated with a named object.
void	modifyAttributes(Name name, ModificationItem[] mods)	Modifies the attributes associated with a named object using an ordered list of modifications.
void	rebind(String name, Object obj, Attributes attrs)	Binds a name to an object, along with associated attributes, overwriting any existing binding.
void	rebind(Name name, Object obj, Attributes attrs)	Binds a name to an object, along with associated attributes, overwriting any existing binding.
NamingEnumeration<SearchResult>	search(String name, String filterExpr, Object[] filterArgs, SearchControls cons)	Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult>	search(String name, String filter, SearchControls cons)	Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult>	search(String name, Attributes matchingAttributes)	Searches in a single context for objects that contain a specified set of attributes.
NamingEnumeration<SearchResult>	search(String name, Attributes matchingAttributes, String[] attributesToReturn)	Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes.
NamingEnumeration<SearchResult>	search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons)	Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult>	search(Name name, String filter, SearchControls cons)	Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult>	search(Name name, Attributes matchingAttributes)	Searches in a single context for objects that contain a specified set of attributes.
NamingEnumeration<SearchResult>	search(Name name, Attributes matchingAttributes, String[] attributesToReturn)	Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes.

Methods declared in class InitialContext

addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, doLookup, doLookup, getDefaultInitCtx, getEnvironment, getNameInNamespace, getNameParser, getNameParser, getURLOrDefaultInitCtx, getURLOrDefaultInitCtx, init, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind

Modifier and Type	Method	Description
Object	addToEnvironment(String propName, Object propVal)	Adds a new environment property to the environment of this context.
void	bind(String name, Object obj)	Binds a name to an object.
void	bind(Name 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(String name)	Creates and binds a new context.
Context	createSubcontext(Name name)	Creates and binds a new context.
void	destroySubcontext(String name)	Destroys the named context and removes it from the namespace.
void	destroySubcontext(Name name)	Destroys the named context and removes it from the namespace.
static <T> T	doLookup(String name)	A static method to retrieve the named object.
static <T> T	doLookup(Name name)	A static method to retrieve the named object.
protected 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(String name)	Retrieves the parser associated with the named context.
NameParser	getNameParser(Name name)	Retrieves the parser associated with the named context.
protected Context	getURLOrDefaultInitCtx(String name)	Retrieves a context for resolving the string name name.
protected Context	getURLOrDefaultInitCtx(Name name)	Retrieves a context for resolving name.
protected 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(String name)	Enumerates the names bound in the named context, along with the objects bound to them.
NamingEnumeration<Binding>	listBindings(Name 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(String name)	Unbinds the named object.
void	unbind(Name name)	Unbinds the named object.

Methods declared in class Object

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

Modifier and Type	Method	Description
protected Object	clone()	Creates and returns a copy of this object.
boolean	equals(Object obj)	Indicates whether some other object is "equal to" this one.
protected void	finalize()	Deprecated, for removal: This API element is subject to removal in a future version. Finalization is deprecated and subject to removal in a future release.
final Class<?>	getClass()	Returns the runtime class of this Object.
int	hashCode()	Returns a hash code value for this 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 it is awakened, typically by being notified or interrupted.
final void	wait(long timeoutMillis)	Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
final void	wait(long timeoutMillis, int nanos)	Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

Constructor Details

InitialLdapContext

public InitialLdapContext()
                   throws NamingException

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

InitialLdapContext

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

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. Caller should not modify mutable keys and values in environment after it has been passed to the constructor.

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

See Also:

• reconnect(Control[])
• LdapContext.reconnect(Control[])

Method Details

extendedOperation

public ExtendedResponse extendedOperation(ExtendedRequest request)
                                   throws NamingException

Description copied from interface: LdapContext

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

Specified by:

extendedOperation in interface LdapContext

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 - If an error occurred while performing the extended operation.

newInstance

public LdapContext newInstance(Control[] reqCtls)
                        throws NamingException

Description copied from interface: LdapContext

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.

Specified by:

newInstance in interface LdapContext

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 - If an error occurred while creating the new instance.

See Also:

• InitialLdapContext

reconnect

public void reconnect(Control[] connCtls)
               throws NamingException

Description copied from interface: LdapContext

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.

Specified by:

reconnect in interface LdapContext

Parameters:

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

Throws:

NamingException - If an error occurred while reconnecting.

See Also:

• LdapContext.getConnectControls()
• LdapContext.newInstance(Control[])

getConnectControls

public Control[] getConnectControls()
                             throws NamingException

Description copied from interface: LdapContext

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.

Specified by:

getConnectControls in interface LdapContext

Returns:

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

Throws:

NamingException - If an error occurred while getting the request controls.

setRequestControls

public void setRequestControls(Control[] requestControls)
                        throws NamingException

Description copied from interface: LdapContext

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().

Specified by:

setRequestControls in interface LdapContext

Parameters:

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

Throws:

NamingException - If an error occurred while setting the request controls.

See Also:

• LdapContext.getRequestControls()

getRequestControls

public Control[] getRequestControls()
                             throws NamingException

Description copied from interface: LdapContext

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.

Specified by:

getRequestControls in interface LdapContext

Returns:

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

Throws:

NamingException - If an error occurred while getting the request controls.

See Also:

• LdapContext.setRequestControls(Control[])

getResponseControls

public Control[] getResponseControls()
                              throws NamingException

Description copied from interface: LdapContext

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.

Specified by:

getResponseControls in interface LdapContext

Returns:

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

Throws:

NamingException - If an error occurred while getting the response controls.