public interface LdapContext extends DirContext
javax.naming.directory.DirContextshould be used instead.
DirContextmethods, 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.
There are two types of request controls:
Unless explicitly qualified, the term "request controls" refers to context request controls.
ldapContextis an instance of
nullor an empty array for
reqCtlsmeans no request controls.
newInstance()creates a new instance of a context using
setRequestControls()updates an existing context instance's request controls to
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
A context instance's request controls are retrieved using
new InitialLdapContext(env, connCtls)
refExceptionis an instance of
ldapContextis an instance of
nullor an empty array for
connCtlsmeans 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
reconnect() to change the connection request controls of
ldapContext.reconnect() affects only the
connection used by
ldapContext and any new contexts instances that are
ldapContext. Contexts that previously shared the
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
A context instance's connection request controls are retrieved using
LdapContext.getResponseControls()is used to retrieve the response controls generated by LDAP operations executed as the result of invoking a
DirContextoperation. 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
Controlarray 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
Controlobjects in the array. A
Controlarray returned by any method is immutable, and may not subsequently be modified by either the caller or the service provider.
|Modifier and Type||Field||Description|
Constant that holds the name of the environment property for specifying the list of control factories to use.
APPLET, 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||Method||Description|
Performs an extended operation.
Retrieves the connection request controls in effect for this context.
Retrieves the request controls in effect for this context.
Retrieves the response controls produced as a result of the last method invoked on this context.
Creates a new instance of this context initialized using request controls.
Reconnects to the LDAP server using the supplied controls and this context's environment.
Sets the request controls for methods subsequently invoked on this 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
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
static final String CONTROL_FACTORIES
ControlFactory.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".
ExtendedResponse extendedOperation(ExtendedRequest request) throws NamingException
request- The non-null request to be performed.
NamingException- If an error occurred while performing the extended operation.
LdapContext newInstance(Control requestControls) throws NamingException
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.
requestControls- The possibly null request controls to use for the new context. If null, the context is initialized with no request controls.
NamingException- If an error occurred while creating the new instance.
void reconnect(Control connCtls) throws NamingException
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
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 are also used as
connection request controls for new context instances derived from this
These connection request controls are not
Service provider implementors should read the "Service Provider" section in the class description for implementation details.
Control getConnectControls() throws NamingException
NamingException- If an error occurred while getting the request controls.
void setRequestControls(Control requestControls) throws NamingException
This removes any previous request controls and adds
for use by subsequent methods invoked on this context.
This method does not affect this context's connection request controls.
requestControls will be in effect until the next
setRequestControls(). You need to explicitly
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
Control getRequestControls() throws NamingException
Control getResponseControls() throws NamingException
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.
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.
NamingException- If an error occurred while getting the response controls.
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2017, Oracle and/or its affiliates. 500 Oracle Parkway
Redwood Shores, CA 94065 USA. All rights reserved.