/*
 * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.naming.ldap;

import javax.naming.NamingException;
import javax.naming.directory.DirContext;
import java.util.Hashtable;

This interface represents a context in which you can perform
operations with LDAPv3-style controls and perform LDAPv3-style
extended operations.
For applications that do not require such controls or extended
operations, the more generic 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 of
Context/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

The former is used whenever a connection needs to be established or
re-established with an LDAP server. The latter is used when all other
LDAP operations are sent to the LDAP server.  The reason why a
distinction between these two types of request controls is necessary
is because JNDI is a high-level API that does not deal directly with
connections.  It is the job of service providers to do any necessary
connection management. Consequently, a single
connection may be shared by multiple context instances, and a service provider
is free to use its own algorithms to conserve connection and network
usage. Thus, when a method is invoked on the context instance, the service
provider might need to do some connection management in addition to
performing the corresponding LDAP operations. For connection management,
it uses the connection request controls, while for the normal
LDAP operations, it uses the context request controls.
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)

where 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);

where 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 method LdapContext.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
A Control[] 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.
Author:
Rosanna Lee, Scott Seligman, Vincent Ryan
See Also:
InitialLdapContext
LdapReferralException.getReferralContext(Hashtable<?,?>, Control[])
Since:
1.3/**
 * This interface represents a context in which you can perform
 * operations with LDAPv3-style controls and perform LDAPv3-style
 * extended operations.
 *
 * For applications that do not require such controls or extended
 * operations, the more generic <tt>javax.naming.directory.DirContext</tt>
 * should be used instead.
 *
 * <h3>Usage Details About Controls</h3>
 *
 * 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 of
 * <tt>Context</tt>/<tt>DirContext</tt>
 * 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.
 *
 * <h3>Request Controls</h3>
 * <p>
 * There are two types of request controls:
 * <ul>
 * <li>Request controls that affect how a connection is created
 * <li>Request controls that affect context methods
 * </ul>
 *
 * The former is used whenever a connection needs to be established or
 * re-established with an LDAP server. The latter is used when all other
 * LDAP operations are sent to the LDAP server.  The reason why a
 * distinction between these two types of request controls is necessary
 * is because JNDI is a high-level API that does not deal directly with
 * connections.  It is the job of service providers to do any necessary
 * connection management. Consequently, a single
 * connection may be shared by multiple context instances, and a service provider
 * is free to use its own algorithms to conserve connection and network
 * usage. Thus, when a method is invoked on the context instance, the service
 * provider might need to do some connection management in addition to
 * performing the corresponding LDAP operations. For connection management,
 * it uses the <em>connection request controls</em>, while for the normal
 * LDAP operations, it uses the <em>context request controls</em>.
 *<p>Unless explicitly qualified, the term "request controls" refers to
 * context request controls.
 *
 * <h4>Context Request Controls</h4>
 * There are two ways in which a context instance gets its request controls:
 * <ol>
 * <li><tt>ldapContext.newInstance(<strong>reqCtls</strong>)</tt>
 * <li><tt>ldapContext.setRequestControls(<strong>reqCtls</strong>)</tt>
 * </ol>
 * where <tt>ldapContext</tt> is an instance of <tt>LdapContext</tt>.
 * Specifying <tt>null</tt> or an empty array for <tt>reqCtls</tt>
 * means no request controls.
 * <tt>newInstance()</tt> creates a new instance of a context using
 * <tt>reqCtls</tt>, while <tt>setRequestControls()</tt>
 * updates an existing context instance's request controls to <tt>reqCtls</tt>.
 * <p>
 * Unlike environment properties, request controls of a context instance
 * <em>are not inherited</em> by context instances that are derived from
 * it.  Derived context instances have <tt>null</tt> as their context
 * request controls.  You must set the request controls of a derived context
 * instance explicitly using <tt>setRequestControls()</tt>.
 * <p>
 * A context instance's request controls are retrieved using
 * the method <tt>getRequestControls()</tt>.
 *
 * <h4>Connection Request Controls</h4>
 * There are three ways in which connection request controls are set:
 * <ol>
 * <li><tt>
 * new InitialLdapContext(env, <strong>connCtls</strong>)</tt>
 * <li><tt>refException.getReferralContext(env, <strong>connCtls</strong>)</tt>
 * <li><tt>ldapContext.reconnect(<strong>connCtls</strong>);</tt>
 * </ol>
 * where <tt>refException</tt> is an instance of
 * <tt>LdapReferralException</tt>, and <tt>ldapContext</tt> is an
 * instance of <tt>LdapContext</tt>.
 * Specifying <tt>null</tt> or an empty array for <tt>connCtls</tt>
 * means no connection request controls.
 * <p>
 * Like environment properties, connection request controls of a context
 * <em>are inherited</em> by contexts that are derived from it.
 * Typically, you initialize the connection request controls using the
 * <tt>InitialLdapContext</tt> constructor or
 * <tt>LdapReferralContext.getReferralContext()</tt>. These connection
 * request controls are inherited by contexts that share the same
 * connection--that is, contexts derived from the initial or referral
 * contexts.
 * <p>
 * Use <tt>reconnect()</tt> to change the connection request controls of
 * a context.
 * Invoking <tt>ldapContext.reconnect()</tt> affects only the
 * connection used by <tt>ldapContext</tt> and any new contexts instances that are
 * derived form <tt>ldapContext</tt>. Contexts that previously shared the
 * connection with <tt>ldapContext</tt> 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.
 * <p>
 * A context instance's connection request controls are retrieved using
 * the method <tt>getConnectControls()</tt>.
 *
 * <h4>Service Provider Requirements</h4>
 *
 * 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.
 *
 * <h3>Response Controls</h3>
 *
 * The method <tt>LdapContext.getResponseControls()</tt> is used to
 * retrieve the response controls generated by LDAP operations executed
 * as the result of invoking a <tt>Context</tt>/<tt>DirContext</tt>
 * 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 <tt>reconnect()</tt> followed by <tt>getResponseControls()</tt>.
 *
 * <h3>Parameters</h3>
 *
 * A <tt>Control[]</tt> 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 <tt>Control</tt> objects
 * in the array.
 * A <tt>Control[]</tt> array returned by any method is immutable, and may
 * not subsequently be modified by either the caller or the service provider.
 *
 * @author Rosanna Lee
 * @author Scott Seligman
 * @author Vincent Ryan
 *
 * @see InitialLdapContext
 * @see LdapReferralException#getReferralContext(java.util.Hashtable,javax.naming.ldap.Control[])
 * @since 1.3
 */

public interface LdapContext extends DirContext {
   
Performs an extended operation.
This method is used to support LDAPv3 extended operations.
Params:
request – The non-null request to be performed.
Throws:
NamingException – If an error occurred while performing the
extended operation.
Returns:
The possibly null response of the operation. null means
the operation did not generate any response./**
    * Performs an extended operation.
    *
    * This method is used to support LDAPv3 extended operations.
    * @param request The non-null request to be performed.
    * @return 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.
    */
    public ExtendedResponse extendedOperation(ExtendedRequest request)
        throws NamingException;

    
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.
Params:
requestControls – The possibly null request controls
to use for the new context.
If null, the context is initialized with no request controls.
Throws:
NamingException – If an error occurred while creating
the new instance.
See Also:
InitialLdapContext
Returns:
A non-null LdapContext instance./**
     * 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.
     *<p>
     * 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.
     *
     * @param requestControls The possibly null request controls
     * to use for the new context.
     * If null, the context is initialized with no request controls.
     *
     * @return A non-null <tt>LdapContext</tt> instance.
     * @exception NamingException If an error occurred while creating
     * the new instance.
     * @see InitialLdapContext
     */
    public LdapContext newInstance(Control[] requestControls)
        throws NamingException;

    
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.
Params:
connCtls – The possibly null controls to use. If null, no
controls are used.
Throws:
NamingException – If an error occurred while reconnecting.
See Also:
getConnectControls
newInstance/**
     * Reconnects to the LDAP server using the supplied controls and
     * this context's environment.
     *<p>
     * 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.
     *<p>
     * This method sets this context's <tt>connCtls</tt>
     * 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 <tt>connCtls</tt>.
     * <tt>connCtls</tt> are also used as
     * connection request controls for new context instances derived from this
     * context.
     * These connection request controls are not
     * affected by <tt>setRequestControls()</tt>.
     *<p>
     * Service provider implementors should read the "Service Provider" section
     * in the class description for implementation details.
     * @param connCtls The possibly null controls to use. If null, no
     * controls are used.
     * @exception NamingException If an error occurred while reconnecting.
     * @see #getConnectControls
     * @see #newInstance
     */
    public void reconnect(Control[] connCtls) throws NamingException;

    
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.
Throws:
NamingException – If an error occurred while getting the request
controls.
Returns:
A possibly-null array of controls. null means no connect controls
have been set for this context./**
     * 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.
     *
     * @return A possibly-null array of controls. null means no connect controls
     * have been set for this context.
     * @exception NamingException If an error occurred while getting the request
     * controls.
     */
    public Control[] getConnectControls() throws NamingException;

    
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().
Params:
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/**
     * 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.
     * <p>
     * This removes any previous request controls and adds
     * <tt>requestControls</tt>
     * for use by subsequent methods invoked on this context.
     * This method does not affect this context's connection request controls.
     *<p>
     * Note that <tt>requestControls</tt> will be in effect until the next
     * invocation of <tt>setRequestControls()</tt>. You need to explicitly
     * invoke <tt>setRequestControls()</tt> with <tt>null</tt> 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
     * <tt>getRequestControls()</tt>.
     * @param requestControls The possibly null controls to use. If null, no
     * controls are used.
     * @exception NamingException If an error occurred while setting the
     * request controls.
     * @see #getRequestControls
     */
    public void setRequestControls(Control[] requestControls)
        throws NamingException;

    
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.
Throws:
NamingException – If an error occurred while getting the request
controls.
See Also:
setRequestControls
Returns:
A possibly-null array of controls. null means no request controls
have been set for this context./**
     * 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.
     *
     * @return A possibly-null array of controls. null means no request controls
     * have been set for this context.
     * @exception NamingException If an error occurred while getting the request
     * controls.
     * @see #setRequestControls
     */
    public Control[] getRequestControls() throws NamingException;

    
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.

Throws:
NamingException – If an error occurred while getting the response
controls.
Returns:
A possibly null array of controls. If null, the previous
method invoked on this context did not produce any controls./**
     * 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.
     *<p>
     * These response controls might have been generated by a successful or
     * failed operation.
     *<p>
     * When a context method that may return response controls is invoked,
     * response controls from the previous method invocation are cleared.
     * <tt>getResponseControls()</tt> returns all of the response controls
     * generated by LDAP operations used by the context method in the order
     * received from the LDAP server.
     * Invoking <tt>getResponseControls()</tt> 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.
     *<p>
     * @return A possibly null array of controls. If null, the previous
     * method invoked on this context did not produce any controls.
     * @exception NamingException If an error occurred while getting the response
     * controls.
     */
    public Control[] getResponseControls() throws NamingException;

    
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. See
ControlFactory.getControlInstance() for details.
This property may be specified in the environment, an applet
parameter, a system property, or one or more resource files.

The value of this constant is "java.naming.factory.control".
See Also:
ControlFactory
Context.addToEnvironment
Context.removeFromEnvironment/**
     * 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. See
     * <tt>ControlFactory.getControlInstance()</tt> for details.
     * This property may be specified in the environment, an applet
     * parameter, a system property, or one or more resource files.
     *<p>
     * The value of this constant is "java.naming.factory.control".
     *
     * @see ControlFactory
     * @see javax.naming.Context#addToEnvironment
     * @see javax.naming.Context#removeFromEnvironment
     */
    static final String CONTROL_FACTORIES = "java.naming.factory.control";
}