ControlFactory


1   /*
2    * @(#)ControlFactory.java  1.12 04/07/16
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.naming.ldap;
9   
10  import javax.naming.NamingException  ;
11  import javax.naming.Context  ;
12  
13  import java.util.Hashtable  ;
14  
15  import com.sun.naming.internal.FactoryEnumeration;
16  import com.sun.naming.internal.ResourceManager;
17  
18  
19  /**
20    * This abstract class represents a factory for creating LDAPv3 controls.
21    * LDAPv3 controls are defined in 
22    * <A HREF="ftp://ftp.isi.edu/in-notes/rfc2251.txt">RFC 2251</A>.
23    *<p>
24    * When a service provider receives a response control, it uses control 
25    * factories to return the specific/appropriate control class implementation.
26    * 
27    * @author Rosanna Lee
28    * @author Scott Seligman
29    * @author Vincent Ryan
30    * @version 1.12 04/07/16
31    *
32    * @see Control
33    * @since 1.3
34    */
35  
36  public abstract class ControlFactory {
37      /*
38       * Creates a new instance of a control factory.
39       */
40      protected ControlFactory() {
41      }
42  
43      /**
44        * Creates a control using this control factory.
45        *<p>
46        * The factory is used by the service provider to return controls
47        * that it reads from the LDAP protocol as specialized control classes.
48        * Without this mechanism, the provider would be returning
49        * controls that only contained data in BER encoded format.
50        *<p>
51        * Typically, <tt>ctl</tt> is a "basic" control containing
52        * BER encoded data. The factory is used to create a specialized
53        * control implementation, usually by decoding the BER encoded data,
54        * that provides methods to access that data in a type-safe and friendly
55        * manner. 
56        * <p>
57        * For example, a factory might use the BER encoded data in
58        * basic control and return an instance of a VirtualListReplyControl.
59        *<p>
60        * If this factory cannot create a control using the argument supplied,
61        * it should return null. 
62        * A factory should only throw an exception if it is sure that
63        * it is the only intended factory and that no other control factories
64        * should be tried. This might happen, for example, if the BER data
65        * in the control does not match what is expected of a control with
66        * the given OID. Since this method throws <tt>NamingException</tt>,
67        * any other internally generated exception that should be propagated
68        * must be wrapped inside a <tt>NamingException</tt>.
69        *
70        * @param ctl A non-null control.
71        *
72        * @return A possibly null Control.
73        * @exception NamingException If <tt>ctl</tt> contains invalid data that prevents it
74        * from being used to create a control. A factory should only throw 
75        * an exception if it knows how to produce the control (identified by the OID)
76        * but is unable to because of, for example invalid BER data. 
77        */
78      public abstract Control   getControlInstance(Control   ctl) throws NamingException  ;
79  
80      /**
81        * Creates a control using known control factories.
82        * <p>
83        * The following rule is used to create the control:
84        *<ul>
85        * <li> Use the control factories specified in 
86        *    the <tt>LdapContext.CONTROL_FACTORIES</tt> property of the
87        *    environment, and of the provider resource file associated with
88        *    <tt>ctx</tt>, in that order.
89        *    The value of this property is a colon-separated list of factory
90        *    class names that are tried in order, and the first one that succeeds
91        *    in creating the control is the one used.
92        *    If none of the factories can be loaded,
93        *    return <code>ctl</code>.
94        *    If an exception is encountered while creating the control, the
95        *    exception is passed up to the caller.
96        *</ul>
97        * <p>
98        * Note that a control factory
99        * must be public and must have a public constructor that accepts no arguments.
100       * <p>
101       * @param ctl The non-null control object containing the OID and BER data.
102       * @param ctx The possibly null context in which the control is being created.
103       * If null, no such information is available.
104       * @param env The possibly null environment of the context. This is used
105       * to find the value of the <tt>LdapContext.CONTROL_FACTORIES</tt> property.
106       * @return A control object created using <code>ctl</code>; or
107       *     <code>ctl</code> if a control object cannot be created using
108       *     the algorithm described above.
109       * @exception NamingException if a naming exception was encountered
110       *     while attempting to create the control object.
111       *         If one of the factories accessed throws an
112       *     exception, it is propagated up to the caller.
113       * If an error was encountered while loading
114       * and instantiating the factory and object classes, the exception
115       * is wrapped inside a <tt>NamingException</tt> and then rethrown.
116       */
117     public static Control   getControlInstance(Control   ctl, Context   ctx, 
118                          Hashtable  <?,?> env) 
119     throws NamingException   {
120 
121     // Get object factories list from environment properties or
122     // provider resource file.
123     FactoryEnumeration factories = ResourceManager.getFactories(
124         LdapContext.CONTROL_FACTORIES, env, ctx);
125 
126     if (factories == null) {
127         return ctl;
128     }
129 
130     // Try each factory until one succeeds
131     Control   answer = null;
132     ControlFactory   factory;
133     while (answer == null && factories.hasMore()) {
134         factory = (ControlFactory  )factories.next();
135         answer = factory.getControlInstance(ctl);
136     }
137 
138     return (answer != null)? answer : ctl;
139     }
140 }
141
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags