Home » openjdk-7 » javax » naming » ldap » [javadoc | source]

    1   /*
    2    * Copyright (c) 1999, 2000, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package javax.naming.ldap;
   27   
   28   import javax.naming.NamingException;
   29   import javax.naming.directory.DirContext;
   30   import java.util.Hashtable;
   31   
   32   /**
   33    * This interface represents a context in which you can perform
   34    * operations with LDAPv3-style controls and perform LDAPv3-style
   35    * extended operations.
   36    *
   37    * For applications that do not require such controls or extended
   38    * operations, the more generic <tt>javax.naming.directory.DirContext</tt>
   39    * should be used instead.
   40    *
   41    * <h3>Usage Details About Controls</h3>
   42    *
   43    * This interface provides support for LDAP v3 controls.
   44    * At a high level, this support allows a user
   45    * program to set request controls for LDAP operations that are executed
   46    * in the course of the user program's invocation of
   47    * <tt>Context</tt>/<tt>DirContext</tt>
   48    * methods, and read response controls resulting from LDAP operations.
   49    * At the implementation level, there are some details that developers of
   50    * both the user program and service providers need to understand in order
   51    * to correctly use request and response controls.
   52    *
   53    * <h3>Request Controls</h3>
   54    * <p>
   55    * There are two types of request controls:
   56    * <ul>
   57    * <li>Request controls that affect how a connection is created
   58    * <li>Request controls that affect context methods
   59    * </ul>
   60    *
   61    * The former is used whenever a connection needs to be established or
   62    * re-established with an LDAP server. The latter is used when all other
   63    * LDAP operations are sent to the LDAP server.  The reason why a
   64    * distinction between these two types of request controls is necessary
   65    * is because JNDI is a high-level API that does not deal directly with
   66    * connections.  It is the job of service providers to do any necessary
   67    * connection management. Consequently, a single
   68    * connection may be shared by multiple context instances, and a service provider
   69    * is free to use its own algorithms to conserve connection and network
   70    * usage. Thus, when a method is invoked on the context instance, the service
   71    * provider might need to do some connection management in addition to
   72    * performing the corresponding LDAP operations. For connection management,
   73    * it uses the <em>connection request controls</em>, while for the normal
   74    * LDAP operations, it uses the <em>context request controls</em>.
   75    *<p>Unless explicitly qualified, the term "request controls" refers to
   76    * context request controls.
   77    *
   78    * <h4>Context Request Controls</h4>
   79    * There are two ways in which a context instance gets its request controls:
   80    * <ol>
   81    * <tt>
   82    * <li>ldapContext.newInstance(<strong>reqCtls</strong>)
   83    * <li>ldapContext.setRequestControls(<strong>reqCtls</strong>)
   84    * </tt>
   85    * </ol>
   86    * where <tt>ldapContext</tt> is an instance of <tt>LdapContext</tt>.
   87    * Specifying <tt>null</tt> or an empty array for <tt>reqCtls</tt>
   88    * means no request controls.
   89    * <tt>newInstance()</tt> creates a new instance of a context using
   90    * <tt>reqCtls</tt>, while <tt>setRequestControls()</tt>
   91    * updates an existing context instance's request controls to <tt>reqCtls</tt>.
   92    * <p>
   93    * Unlike environment properties, request controls of a context instance
   94    * <em>are not inherited</em> by context instances that are derived from
   95    * it.  Derived context instances have <tt>null</tt> as their context
   96    * request controls.  You must set the request controls of a derived context
   97    * instance explicitly using <tt>setRequestControls()</tt>.
   98    * <p>
   99    * A context instance's request controls are retrieved using
  100    * the method <tt>getRequestControls()</tt>.
  101    *
  102    * <h4>Connection Request Controls</h4>
  103    * There are three ways in which connection request controls are set:
  104    * <ol>
  105    * <tt>
  106    * <li>
  107    * new InitialLdapContext(env, <strong>connCtls</strong>)
  108    * <li>refException.getReferralContext(env, <strong>connCtls</strong>)
  109    * <li>ldapContext.reconnect(<strong>connCtls</strong>);
  110    * </tt>
  111    * </ol>
  112    * where <tt>refException</tt> is an instance of
  113    * <tt>LdapReferralException</tt>, and <tt>ldapContext</tt> is an
  114    * instance of <tt>LdapContext</tt>.
  115    * Specifying <tt>null</tt> or an empty array for <tt>connCtls</tt>
  116    * means no connection request controls.
  117    * <p>
  118    * Like environment properties, connection request controls of a context
  119    * <em>are inherited</em> by contexts that are derived from it.
  120    * Typically, you initialize the connection request controls using the
  121    * <tt>InitialLdapContext</tt> constructor or
  122    * <tt>LdapReferralContext.getReferralContext()</tt>. These connection
  123    * request controls are inherited by contexts that share the same
  124    * connection--that is, contexts derived from the initial or referral
  125    * contexts.
  126    * <p>
  127    * Use <tt>reconnect()</tt> to change the connection request controls of
  128    * a context.
  129    * Invoking <tt>ldapContext.reconnect()</tt> affects only the
  130    * connection used by <tt>ldapContext</tt> and any new contexts instances that are
  131    * derived form <tt>ldapContext</tt>. Contexts that previously shared the
  132    * connection with <tt>ldapContext</tt> remain unchanged. That is, a context's
  133    * connection request controls must be explicitly changed and is not
  134    * affected by changes to another context's connection request
  135    * controls.
  136    * <p>
  137    * A context instance's connection request controls are retrieved using
  138    * the method <tt>getConnectControls()</tt>.
  139    *
  140    * <h4>Service Provider Requirements</h4>
  141    *
  142    * A service provider supports connection and context request controls
  143    * in the following ways.  Context request controls must be associated on
  144    * a per context instance basis while connection request controls must be
  145    * associated on a per connection instance basis.  The service provider
  146    * must look for the connection request controls in the environment
  147    * property "java.naming.ldap.control.connect" and pass this environment
  148    * property on to context instances that it creates.
  149    *
  150    * <h3>Response Controls</h3>
  151    *
  152    * The method <tt>LdapContext.getResponseControls()</tt> is used to
  153    * retrieve the response controls generated by LDAP operations executed
  154    * as the result of invoking a <tt>Context</tt>/<tt>DirContext</tt>
  155    * operation. The result is all of the responses controls generated
  156    * by the underlying LDAP operations, including any implicit reconnection.
  157    * To get only the reconnection response controls,
  158    * use <tt>reconnect()</tt> followed by <tt>getResponseControls()</tt>.
  159    *
  160    * <h3>Parameters</h3>
  161    *
  162    * A <tt>Control[]</tt> array
  163    * passed as a parameter to any method is owned by the caller.
  164    * The service provider will not modify the array or keep a reference to it,
  165    * although it may keep references to the individual <tt>Control</tt> objects
  166    * in the array.
  167    * A <tt>Control[]</tt> array returned by any method is immutable, and may
  168    * not subsequently be modified by either the caller or the service provider.
  169    *
  170    * @author Rosanna Lee
  171    * @author Scott Seligman
  172    * @author Vincent Ryan
  173    *
  174    * @see InitialLdapContext
  175    * @see LdapReferralException#getReferralContext(java.util.Hashtable,javax.naming.ldap.Control[])
  176    * @since 1.3
  177    */
  178   
  179   public interface LdapContext extends DirContext {
  180      /**
  181       * Performs an extended operation.
  182       *
  183       * This method is used to support LDAPv3 extended operations.
  184       * @param request The non-null request to be performed.
  185       * @return The possibly null response of the operation. null means
  186       * the operation did not generate any response.
  187       * @throws NamingException If an error occurred while performing the
  188       * extended operation.
  189       */
  190       public ExtendedResponse extendedOperation(ExtendedRequest request)
  191           throws NamingException;
  192   
  193       /**
  194        * Creates a new instance of this context initialized using request controls.
  195        *
  196        * This method is a convenience method for creating a new instance
  197        * of this context for the purposes of multithreaded access.
  198        * For example, if multiple threads want to use different context
  199        * request controls,
  200        * each thread may use this method to get its own copy of this context
  201        * and set/get context request controls without having to synchronize with other
  202        * threads.
  203        *<p>
  204        * The new context has the same environment properties and connection
  205        * request controls as this context. See the class description for details.
  206        * Implementations might also allow this context and the new context
  207        * to share the same network connection or other resources if doing
  208        * so does not impede the independence of either context.
  209        *
  210        * @param requestControls The possibly null request controls
  211        * to use for the new context.
  212        * If null, the context is initialized with no request controls.
  213        *
  214        * @return A non-null <tt>LdapContext</tt> instance.
  215        * @exception NamingException If an error occurred while creating
  216        * the new instance.
  217        * @see InitialLdapContext
  218        */
  219       public LdapContext newInstance(Control[] requestControls)
  220           throws NamingException;
  221   
  222       /**
  223        * Reconnects to the LDAP server using the supplied controls and
  224        * this context's environment.
  225        *<p>
  226        * This method is a way to explicitly initiate an LDAP "bind" operation.
  227        * For example, you can use this method to set request controls for
  228        * the LDAP "bind" operation, or to explicitly connect to the server
  229        * to get response controls returned by the LDAP "bind" operation.
  230        *<p>
  231        * This method sets this context's <tt>connCtls</tt>
  232        * to be its new connection request controls. This context's
  233        * context request controls are not affected.
  234        * After this method has been invoked, any subsequent
  235        * implicit reconnections will be done using <tt>connCtls</tt>.
  236        * <tt>connCtls</tt> are also used as
  237        * connection request controls for new context instances derived from this
  238        * context.
  239        * These connection request controls are not
  240        * affected by <tt>setRequestControls()</tt>.
  241        *<p>
  242        * Service provider implementors should read the "Service Provider" section
  243        * in the class description for implementation details.
  244        * @param connCtls The possibly null controls to use. If null, no
  245        * controls are used.
  246        * @exception NamingException If an error occurred while reconnecting.
  247        * @see #getConnectControls
  248        * @see #newInstance
  249        */
  250       public void reconnect(Control[] connCtls) throws NamingException;
  251   
  252       /**
  253        * Retrieves the connection request controls in effect for this context.
  254        * The controls are owned by the JNDI implementation and are
  255        * immutable. Neither the array nor the controls may be modified by the
  256        * caller.
  257        *
  258        * @return A possibly-null array of controls. null means no connect controls
  259        * have been set for this context.
  260        * @exception NamingException If an error occurred while getting the request
  261        * controls.
  262        */
  263       public Control[] getConnectControls() throws NamingException;
  264   
  265       /**
  266        * Sets the request controls for methods subsequently
  267        * invoked on this context.
  268        * The request controls are owned by the JNDI implementation and are
  269        * immutable. Neither the array nor the controls may be modified by the
  270        * caller.
  271        * <p>
  272        * This removes any previous request controls and adds
  273        * <tt>requestControls</tt>
  274        * for use by subsequent methods invoked on this context.
  275        * This method does not affect this context's connection request controls.
  276        *<p>
  277        * Note that <tt>requestControls</tt> will be in effect until the next
  278        * invocation of <tt>setRequestControls()</tt>. You need to explicitly
  279        * invoke <tt>setRequestControls()</tt> with <tt>null</tt> or an empty
  280        * array to clear the controls if you don't want them to affect the
  281        * context methods any more.
  282        * To check what request controls are in effect for this context, use
  283        * <tt>getRequestControls()</tt>.
  284        * @param requestControls The possibly null controls to use. If null, no
  285        * controls are used.
  286        * @exception NamingException If an error occurred while setting the
  287        * request controls.
  288        * @see #getRequestControls
  289        */
  290       public void setRequestControls(Control[] requestControls)
  291           throws NamingException;
  292   
  293       /**
  294        * Retrieves the request controls in effect for this context.
  295        * The request controls are owned by the JNDI implementation and are
  296        * immutable. Neither the array nor the controls may be modified by the
  297        * caller.
  298        *
  299        * @return A possibly-null array of controls. null means no request controls
  300        * have been set for this context.
  301        * @exception NamingException If an error occurred while getting the request
  302        * controls.
  303        * @see #setRequestControls
  304        */
  305       public Control[] getRequestControls() throws NamingException;
  306   
  307       /**
  308        * Retrieves the response controls produced as a result of the last
  309        * method invoked on this context.
  310        * The response controls are owned by the JNDI implementation and are
  311        * immutable. Neither the array nor the controls may be modified by the
  312        * caller.
  313        *<p>
  314        * These response controls might have been generated by a successful or
  315        * failed operation.
  316        *<p>
  317        * When a context method that may return response controls is invoked,
  318        * response controls from the previous method invocation are cleared.
  319        * <tt>getResponseControls()</tt> returns all of the response controls
  320        * generated by LDAP operations used by the context method in the order
  321        * received from the LDAP server.
  322        * Invoking <tt>getResponseControls()</tt> does not
  323        * clear the response controls. You can call it many times (and get
  324        * back the same controls) until the next context method that may return
  325        * controls is invoked.
  326        *<p>
  327        * @return A possibly null array of controls. If null, the previous
  328        * method invoked on this context did not produce any controls.
  329        * @exception NamingException If an error occurred while getting the response
  330        * controls.
  331        */
  332       public Control[] getResponseControls() throws NamingException;
  333   
  334       /**
  335        * Constant that holds the name of the environment property
  336        * for specifying the list of control factories to use. The value
  337        * of the property should be a colon-separated list of the fully
  338        * qualified class names of factory classes that will create a control
  339        * given another control. See
  340        * <tt>ControlFactory.getControlInstance()</tt> for details.
  341        * This property may be specified in the environment, an applet
  342        * parameter, a system property, or one or more resource files.
  343        *<p>
  344        * The value of this constant is "java.naming.factory.control".
  345        *<p>
  346        * @see ControlFactory
  347        * @see javax.naming.Context#addToEnvironment
  348        * @see javax.naming.Context#removeFromEnvironment
  349        */
  350       static final String CONTROL_FACTORIES = "java.naming.factory.control";
  351   }

Home » openjdk-7 » javax » naming » ldap » [javadoc | source]