Interface LdapContext
- All Superinterfaces:
Context, DirContext
- All Known Implementing Classes:
InitialLdapContext
javax.naming.directory.DirContext
should be used instead.
Usage Details About Controls
This interface provides support for LDAP v3 controls. At a high level, this support allows a user program to set request controls for LDAP operations that are executed in the course of the user program's invocation ofContext
/DirContext
methods, and read response controls resulting from LDAP operations.
At the implementation level, there are some details that developers of
both the user program and service providers need to understand in order
to correctly use request and response controls.
Request Controls
There are two types of request controls:
- Request controls that affect how a connection is created
- Request controls that affect context methods
Unless explicitly qualified, the term "request controls" refers to context request controls.
Context Request Controls
There are two ways in which a context instance gets its request controls:ldapContext.newInstance(reqCtls)
ldapContext.setRequestControls(reqCtls)
ldapContext
is an instance of LdapContext
.
Specifying null
or an empty array for reqCtls
means no request controls.
newInstance()
creates a new instance of a context using
reqCtls
, while setRequestControls()
updates an existing context instance's request controls to reqCtls
.
Unlike environment properties, request controls of a context instance
are not inherited by context instances that are derived from
it. Derived context instances have null
as their context
request controls. You must set the request controls of a derived context
instance explicitly using setRequestControls()
.
A context instance's request controls are retrieved using
the method getRequestControls()
.
Connection Request Controls
There are three ways in which connection request controls are set:new InitialLdapContext(env, connCtls)
refException.getReferralContext(env, connCtls)
ldapContext.reconnect(connCtls);
refException
is an instance of
LdapReferralException
, and ldapContext
is an
instance of LdapContext
.
Specifying null
or an empty array for connCtls
means no connection request controls.
Like environment properties, connection request controls of a context
are inherited by contexts that are derived from it.
Typically, you initialize the connection request controls using the
InitialLdapContext
constructor or
LdapReferralContext.getReferralContext()
. These connection
request controls are inherited by contexts that share the same
connection--that is, contexts derived from the initial or referral
contexts.
Use reconnect()
to change the connection request controls of
a context.
Invoking ldapContext.reconnect()
affects only the
connection used by ldapContext
and any new contexts instances that are
derived form ldapContext
. Contexts that previously shared the
connection with ldapContext
remain unchanged. That is, a context's
connection request controls must be explicitly changed and is not
affected by changes to another context's connection request
controls.
A context instance's connection request controls are retrieved using
the method getConnectControls()
.
Service Provider Requirements
A service provider supports connection and context request controls in the following ways. Context request controls must be associated on a per context instance basis while connection request controls must be associated on a per connection instance basis. The service provider must look for the connection request controls in the environment property "java.naming.ldap.control.connect" and pass this environment property on to context instances that it creates.Response Controls
The methodLdapContext.getResponseControls()
is used to
retrieve the response controls generated by LDAP operations executed
as the result of invoking a Context
/DirContext
operation. The result is all of the responses controls generated
by the underlying LDAP operations, including any implicit reconnection.
To get only the reconnection response controls,
use reconnect()
followed by getResponseControls()
.
Parameters
AControl[]
array
passed as a parameter to any method is owned by the caller.
The service provider will not modify the array or keep a reference to it,
although it may keep references to the individual Control
objects
in the array.
A Control[]
array returned by any method is immutable, and may
not subsequently be modified by either the caller or the service provider.- Since:
- 1.3
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
Constant that holds the name of the environment property for specifying the list of control factories to use.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 TypeFieldDescriptionstatic final String
Constant that holds the name of the environment property for specifying the authoritativeness of the service requested.static final String
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
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
Constant that holds the name of the environment property for specifying the initial context factory to use.static final String
Constant that holds the name of the environment property for specifying the preferred language to use with the service.static final String
Constant that holds the name of the environment property for specifying the list of object factories to use.static final String
Constant that holds the name of the environment property for specifying configuration information for the service provider to use.static final String
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
Constant that holds the name of the environment property for specifying the security level to use.static final String
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
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
Constant that holds the name of the environment property for specifying the security protocol to use.static final String
Constant that holds the name of the environment property for specifying the list of state factories to use.static final String
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 TypeFieldDescriptionstatic final int
This constant specifies to add an attribute with the specified values.static final int
This constant specifies to delete the specified attribute values from the attribute.static final int
This constant specifies to replace an attribute with specified values. -
Method Summary
Modifier and TypeMethodDescriptionextendedOperation
(ExtendedRequest request) Performs an extended operation.Control[]
Retrieves the connection request controls in effect for this context.Control[]
Retrieves the request controls in effect for this context.Control[]
Retrieves the response controls produced as a result of the last method invoked on this context.newInstance
(Control[] requestControls) Creates a new instance of this context initialized using request controls.void
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 interface Context
addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getEnvironment, getNameInNamespace, getNameParser, getNameParser, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind
Modifier and TypeMethodDescriptionaddToEnvironment
(String propName, Object propVal) Adds a new environment property to the environment of this context.void
Binds a name to an object.void
Binds a name to an object.void
close()
Closes this context.composeName
(String name, String prefix) Composes the name of this context with a name relative to this context.composeName
(Name name, Name prefix) Composes the name of this context with a name relative to this context.createSubcontext
(String name) Creates and binds a new 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.Hashtable
<?, ?> Retrieves the environment in effect for this context.Retrieves the full name of this context within its own namespace.getNameParser
(String name) Retrieves the parser associated with the named context.getNameParser
(Name name) Retrieves the parser associated with the named context.Enumerates the names bound in the named context, along with the class names of objects bound to them.Enumerates the names bound in the named context, along with the class names of objects bound to them.listBindings
(String name) Enumerates the names bound in the named context, along with the objects bound to them.listBindings
(Name name) Enumerates the names bound in the named context, along with the objects bound to them.Retrieves the named object.Retrieves the named object.lookupLink
(String name) Retrieves the named object, following links except for the terminal atomic component of the name.lookupLink
(Name name) Retrieves the named object, following links except for the terminal atomic component of the name.void
Binds a name to an object, overwriting any existing binding.void
Binds a name to an object, overwriting any existing binding.removeFromEnvironment
(String propName) Removes an environment property from the environment of this context.void
Binds a new name to the object bound to an old name, and unbinds the old name.void
Binds a new name to the object bound to an old name, and unbinds the old name.void
Unbinds the named object.void
Unbinds the named object.Methods declared in interface DirContext
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 TypeMethodDescriptionvoid
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.createSubcontext
(String name, Attributes attrs) Creates and binds a new context, along with associated attributes.createSubcontext
(Name name, Attributes attrs) Creates and binds a new context, along with associated attributes.getAttributes
(String name) Retrieves all of the attributes associated with a named object.getAttributes
(String name, String[] attrIds) Retrieves selected attributes associated with a named object.getAttributes
(Name name) Retrieves all of the attributes associated with a named object.getAttributes
(Name name, String[] attrIds) Retrieves selected attributes associated with a named object.Retrieves the schema associated with the named object.Retrieves the schema associated with the named object.Retrieves a context containing the schema objects of the named object's class definitions.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.search
(String name, String filterExpr, Object[] filterArgs, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.search
(String name, String filter, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.search
(String name, Attributes matchingAttributes) Searches in a single context for objects that contain a specified set of attributes.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.search
(Name name, String filterExpr, Object[] filterArgs, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.search
(Name name, String filter, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.search
(Name name, Attributes matchingAttributes) Searches in a single context for objects that contain a specified set of attributes.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.
-
Field Details
-
CONTROL_FACTORIES
Constant that holds the name of the environment property for specifying the list of control factories to use. The value of the property should be a colon-separated list of the fully qualified class names of factory classes that will create a control given another control. SeeControlFactory.getControlInstance()
for details. This property may be specified in the environment, a system property, or one or more resource files.The value of this constant is "java.naming.factory.control".
- See Also:
-
-
Method Details
-
extendedOperation
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
- If an error occurred while performing the extended operation.
-
newInstance
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:
requestControls
- 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:
-
reconnect
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 usingconnCtls
.connCtls
are also used as connection request controls for new context instances derived from this context. These connection request controls are not affected bysetRequestControls()
.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
- If an error occurred while reconnecting.- See Also:
-
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
- If an error occurred while getting the request controls.
-
setRequestControls
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 ofsetRequestControls()
. You need to explicitly invokesetRequestControls()
withnull
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, usegetRequestControls()
.- 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:
-
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
- If an error occurred while getting the request controls.- See Also:
-
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. InvokinggetResponseControls()
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
- If an error occurred while getting the response controls.
-