ControlFactory.java revision 2395
2362N/A * Copyright 1999-2004 Sun Microsystems, Inc. All Rights Reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 0N/A * published by the Free Software Foundation. Sun designates this 0N/A * particular file as subject to the "Classpath" exception as provided 0N/A * by Sun in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 2362N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 0N/A * CA 95054 USA or visit www.sun.com if you need additional information or 0N/A * have any questions. * This abstract class represents a factory for creating LDAPv3 controls. * LDAPv3 controls are defined in * When a service provider receives a response control, it uses control * Creates a new instance of a control factory. * Creates a control using this control factory. * The factory is used by the service provider to return controls * that it reads from the LDAP protocol as specialized control classes. * Without this mechanism, the provider would be returning * controls that only contained data in BER encoded format. * Typically, <tt>ctl</tt> is a "basic" control containing * BER encoded data. The factory is used to create a specialized * control implementation, usually by decoding the BER encoded data, * that provides methods to access that data in a type-safe and friendly * For example, a factory might use the BER encoded data in * basic control and return an instance of a VirtualListReplyControl. * If this factory cannot create a control using the argument supplied, * A factory should only throw an exception if it is sure that * it is the only intended factory and that no other control factories * should be tried. This might happen, for example, if the BER data * in the control does not match what is expected of a control with * the given OID. Since this method throws <tt>NamingException</tt>, * any other internally generated exception that should be propagated * must be wrapped inside a <tt>NamingException</tt>. * @param ctl A non-null control. * @return A possibly null Control. * @exception NamingException If <tt>ctl</tt> contains invalid data that prevents it * from being used to create a control. A factory should only throw * an exception if it knows how to produce the control (identified by the OID) * but is unable to because of, for example invalid BER data. * Creates a control using known control factories. * The following rule is used to create the control: * <li> Use the control factories specified in * the <tt>LdapContext.CONTROL_FACTORIES</tt> property of the * environment, and of the provider resource file associated with * <tt>ctx</tt>, in that order. * The value of this property is a colon-separated list of factory * class names that are tried in order, and the first one that succeeds * in creating the control is the one used. * If none of the factories can be loaded, * return <code>ctl</code>. * If an exception is encountered while creating the control, the * exception is passed up to the caller. * Note that a control factory * must be public and must have a public constructor that accepts no arguments. * @param ctl The non-null control object containing the OID and BER data. * @param ctx The possibly null context in which the control is being created. * If null, no such information is available. * @param env The possibly null environment of the context. This is used * to find the value of the <tt>LdapContext.CONTROL_FACTORIES</tt> property. * @return A control object created using <code>ctl</code>; or * <code>ctl</code> if a control object cannot be created using * the algorithm described above. * @exception NamingException if a naming exception was encountered * while attempting to create the control object. * If one of the factories accessed throws an * exception, it is propagated up to the caller. * If an error was encountered while loading * and instantiating the factory and object classes, the exception * is wrapped inside a <tt>NamingException</tt> and then rethrown. // Get object factories list from environment properties or // provider resource file. // Try each factory until one succeeds