/*

 * Copyright (c) 1999, 2014, 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 {@code javax.naming.directory.DirContext}

 * 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

 * {@code Context}/{@code 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.

 *

 * <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><code>ldapContext.newInstance(<strong>reqCtls</strong>)</code>

 * <li><code>ldapContext.setRequestControls(<strong>reqCtls</strong>)</code>

 * </ol>

 * where {@code ldapContext} is an instance of {@code LdapContext}.

 * Specifying {@code null} or an empty array for {@code reqCtls}

 * means no request controls.

 * {@code newInstance()} creates a new instance of a context using

 * {@code reqCtls}, while {@code setRequestControls()}

 * updates an existing context instance's request controls to {@code reqCtls}.

 * <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 {@code null} as their context

 * request controls.  You must set the request controls of a derived context

 * instance explicitly using {@code setRequestControls()}.

 * <p>

 * A context instance's request controls are retrieved using

 * the method {@code getRequestControls()}.

 *

 * <h4>Connection Request Controls</h4>

 * There are three ways in which connection request controls are set:

 * <ol>

 * <li><code>

 * new InitialLdapContext(env, <strong>connCtls</strong>)</code>

 * <li><code>refException.getReferralContext(env, <strong>connCtls</strong>)</code>

 * <li><code>ldapContext.reconnect(<strong>connCtls</strong>);</code>

 * </ol>

 * where {@code refException} is an instance of

 * {@code LdapReferralException}, and {@code ldapContext} is an

 * instance of {@code LdapContext}.

 * Specifying {@code null} or an empty array for {@code connCtls}

 * 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

 * {@code InitialLdapContext} constructor or

 * {@code 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.

 * <p>

 * Use {@code reconnect()} to change the connection request controls of

 * a context.

 * Invoking {@code ldapContext.reconnect()} affects only the

 * connection used by {@code ldapContext} and any new contexts instances that are

 * derived form {@code ldapContext}. Contexts that previously shared the

 * connection with {@code 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.

 * <p>

 * A context instance's connection request controls are retrieved using

 * the method {@code getConnectControls()}.

 *

 * <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 {@code LdapContext.getResponseControls()} is used to

 * retrieve the response controls generated by LDAP operations executed

 * as the result of invoking a {@code Context}/{@code 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 {@code reconnect()} followed by {@code getResponseControls()}.

 *

 * <h3>Parameters</h3>

 *

 * A {@code 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 {@code Control} objects

 * in the array.

 * A {@code 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

 * @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.

    * @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.

     *<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 {@code LdapContext} 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.

     *<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 {@code 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 {@code connCtls}.

     * {@code connCtls} are also used as

     * connection request controls for new context instances derived from this

     * context.

     * These connection request controls are not

     * affected by {@code setRequestControls()}.

     *<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.

     *

     * @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.

     * <p>

     * This removes any previous request controls and adds

     * {@code requestControls}

     * for use by subsequent methods invoked on this context.

     * This method does not affect this context's connection request controls.

     *<p>

     * Note that {@code requestControls} will be in effect until the next

     * invocation of {@code setRequestControls()}. You need to explicitly

     * invoke {@code setRequestControls()} with {@code 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

     * {@code getRequestControls()}.

     * @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.

     *

     * @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.

     *<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.

     * {@code 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 {@code 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.

     *

     * @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

     * {@code ControlFactory.getControlInstance()} for details.

     * This property may be specified in the environment, 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";

}