1 /*
   2  * Copyright (c) 1999, 2010, 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.Context;
  30 
  31 import java.util.Hashtable;
  32 
  33 import com.sun.naming.internal.FactoryEnumeration;
  34 import com.sun.naming.internal.ResourceManager;
  35 
  36 
  37 /**
  38   * This abstract class represents a factory for creating LDAPv3 controls.
  39   * LDAPv3 controls are defined in
  40   * <A HREF="http://www.ietf.org/rfc/rfc2251.txt">RFC 2251</A>.
  41   *<p>
  42   * When a service provider receives a response control, it uses control
  43   * factories to return the specific/appropriate control class implementation.
  44   *
  45   * @author Rosanna Lee
  46   * @author Scott Seligman
  47   * @author Vincent Ryan
  48   *
  49   * @see Control
  50   * @since 1.3
  51   */
  52 
  53 public abstract class ControlFactory {
  54     /*
  55      * Creates a new instance of a control factory.
  56      */
  57     protected ControlFactory() {
  58     }
  59 
  60     /**
  61       * Creates a control using this control factory.
  62       *<p>
  63       * The factory is used by the service provider to return controls
  64       * that it reads from the LDAP protocol as specialized control classes.
  65       * Without this mechanism, the provider would be returning
  66       * controls that only contained data in BER encoded format.
  67       *<p>
  68       * Typically, <tt>ctl</tt> is a "basic" control containing
  69       * BER encoded data. The factory is used to create a specialized
  70       * control implementation, usually by decoding the BER encoded data,
  71       * that provides methods to access that data in a type-safe and friendly
  72       * manner.
  73       * <p>
  74       * For example, a factory might use the BER encoded data in
  75       * basic control and return an instance of a VirtualListReplyControl.
  76       *<p>
  77       * If this factory cannot create a control using the argument supplied,
  78       * it should return null.
  79       * A factory should only throw an exception if it is sure that
  80       * it is the only intended factory and that no other control factories
  81       * should be tried. This might happen, for example, if the BER data
  82       * in the control does not match what is expected of a control with
  83       * the given OID. Since this method throws <tt>NamingException</tt>,
  84       * any other internally generated exception that should be propagated
  85       * must be wrapped inside a <tt>NamingException</tt>.
  86       *
  87       * @param ctl A non-null control.
  88       *
  89       * @return A possibly null Control.
  90       * @exception NamingException If <tt>ctl</tt> contains invalid data that prevents it
  91       * from being used to create a control. A factory should only throw
  92       * an exception if it knows how to produce the control (identified by the OID)
  93       * but is unable to because of, for example invalid BER data.
  94       */
  95     public abstract Control getControlInstance(Control ctl) throws NamingException;
  96 
  97     /**
  98       * Creates a control using known control factories.
  99       * <p>
 100       * The following rule is used to create the control:
 101       *<ul>
 102       * <li> Use the control factories specified in
 103       *    the <tt>LdapContext.CONTROL_FACTORIES</tt> property of the
 104       *    environment, and of the provider resource file associated with
 105       *    <tt>ctx</tt>, in that order.
 106       *    The value of this property is a colon-separated list of factory
 107       *    class names that are tried in order, and the first one that succeeds
 108       *    in creating the control is the one used.
 109       *    If none of the factories can be loaded,
 110       *    return <code>ctl</code>.
 111       *    If an exception is encountered while creating the control, the
 112       *    exception is passed up to the caller.
 113       *</ul>
 114       * <p>
 115       * Note that a control factory
 116       * must be public and must have a public constructor that accepts no arguments.
 117       * <p>
 118       * @param ctl The non-null control object containing the OID and BER data.
 119       * @param ctx The possibly null context in which the control is being created.
 120       * If null, no such information is available.
 121       * @param env The possibly null environment of the context. This is used
 122       * to find the value of the <tt>LdapContext.CONTROL_FACTORIES</tt> property.
 123       * @return A control object created using <code>ctl</code>; or
 124       *         <code>ctl</code> if a control object cannot be created using
 125       *         the algorithm described above.
 126       * @exception NamingException if a naming exception was encountered
 127       *         while attempting to create the control object.
 128       *         If one of the factories accessed throws an
 129       *         exception, it is propagated up to the caller.
 130       * If an error was encountered while loading
 131       * and instantiating the factory and object classes, the exception
 132       * is wrapped inside a <tt>NamingException</tt> and then rethrown.
 133       */
 134     public static Control getControlInstance(Control ctl, Context ctx,
 135                                              Hashtable<?,?> env)
 136         throws NamingException {
 137 
 138         // Get object factories list from environment properties or
 139         // provider resource file.
 140         FactoryEnumeration factories = ResourceManager.getFactories(
 141             LdapContext.CONTROL_FACTORIES, env, ctx);
 142 
 143         if (factories == null) {
 144             return ctl;
 145         }
 146 
 147         // Try each factory until one succeeds
 148         Control answer = null;
 149         ControlFactory factory;
 150         while (answer == null && factories.hasMore()) {
 151             factory = (ControlFactory)factories.next();
 152             answer = factory.getControlInstance(ctl);
 153         }
 154 
 155         return (answer != null)? answer : ctl;
 156     }
 157 }