DirectoryManager


1   /*
2    * @(#)DirectoryManager.java    1.13 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.spi;
9   
10  import java.util.Hashtable  ;
11  
12  import javax.naming.Context  ;
13  import javax.naming.Name  ;
14  import javax.naming.Reference  ;
15  import javax.naming.Referenceable  ;
16  import javax.naming.NamingException  ;
17  import javax.naming.CannotProceedException  ;
18  import javax.naming.directory.DirContext  ;
19  import javax.naming.directory.Attributes  ;
20  
21  import com.sun.naming.internal.ResourceManager;
22  import com.sun.naming.internal.FactoryEnumeration;
23  
24  
25  /**
26    * This class contains methods for supporting <tt>DirContext</tt>
27    * implementations.
28    *<p>
29    * This class is an extension of <tt>NamingManager</tt>.  It contains methods
30    * for use by service providers for accessing object factories and
31    * state factories, and for getting continuation contexts for
32    * supporting federation.
33    *<p>
34    * <tt>DirectoryManager</tt> is safe for concurrent access by multiple threads.
35    *<p>
36    * Except as otherwise noted,
37    * a <tt>Name</tt>, <tt>Attributes</tt>, or environment parameter
38    * passed to any method is owned by the caller.
39    * The implementation will not modify the object or keep a reference
40    * to it, although it may keep a reference to a clone or copy.
41    *
42    * @author Rosanna Lee
43    * @author Scott Seligman
44    * @version 1.13 04/07/16
45    *
46    * @see DirObjectFactory
47    * @see DirStateFactory
48    * @since 1.3
49    */
50  
51  public class DirectoryManager extends NamingManager   {
52  
53      /*
54       * Disallow anyone from creating one of these.
55       */
56      DirectoryManager() {}
57  
58      /**
59        * Creates a context in which to continue a <tt>DirContext</tt> operation.
60        * Operates just like <tt>NamingManager.getContinuationContext()</tt>,
61        * only the continuation context returned is a <tt>DirContext</tt>.
62        *
63        * @param cpe
64        *     The non-null exception that triggered this continuation.
65        * @return A non-null <tt>DirContext</tt> object for continuing the operation.
66        * @exception NamingException If a naming exception occurred.
67        *
68        * @see NamingManager#getContinuationContext(CannotProceedException)
69        */
70      public static DirContext   getContinuationDirContext(
71          CannotProceedException   cpe) throws NamingException   {
72  
73      Hashtable   env = cpe.getEnvironment();
74      if (env == null) {
75          env = new Hashtable  (7);
76      } else {
77          // Make a (shallow) copy of the environment.
78          env = (Hashtable  ) env.clone();
79      }
80      env.put(CPE, cpe);
81  
82      return (new ContinuationDirContext  (cpe, env));
83      }
84  
85      /**
86        * Creates an instance of an object for the specified object,
87        * attributes, and environment.
88        * <p>
89        * This method is the same as <tt>NamingManager.getObjectInstance</tt>
90        * except for the following differences:
91        *<ul>
92        *<li>
93        * It accepts an <tt>Attributes</tt> parameter that contains attributes
94        * associated with the object. The <tt>DirObjectFactory</tt> might use these
95        * attributes to save having to look them up from the directory.
96        *<li>
97        * The object factories tried must implement either
98        * <tt>ObjectFactory</tt> or <tt>DirObjectFactory</tt>.
99        * If it implements <tt>DirObjectFactory</tt>, 
100       * <tt>DirObjectFactory.getObjectInstance()</tt> is used, otherwise,
101       * <tt>ObjectFactory.getObjectInstance()</tt> is used.
102       *</ul>
103       * Service providers that implement the <tt>DirContext</tt> interface
104       * should use this method, not <tt>NamingManager.getObjectInstance()</tt>.
105       *<p>
106       *
107       * @param refInfo The possibly null object for which to create an object.
108       * @param name The name of this object relative to <code>nameCtx</code>.
109       *     Specifying a name is optional; if it is
110       *     omitted, <code>name</code> should be null.
111       * @param nameCtx The context relative to which the <code>name</code>
112       *     parameter is specified.  If null, <code>name</code> is
113       *     relative to the default initial context.
114       * @param environment The possibly null environment to 
115       *     be used in the creation of the object factory and the object.
116       * @param attrs The possibly null attributes associated with refInfo.
117       *     This might not be the complete set of attributes for refInfo;
118       *     you might be able to read more attributes from the directory.
119       * @return An object created using <code>refInfo</code> and <tt>attrs</tt>; or
120       *     <code>refInfo</code> if an object cannot be created by
121       *     a factory.
122       * @exception NamingException If a naming exception was encountered
123       *     while attempting to get a URL context, or if one of the
124       *     factories accessed throws a NamingException.
125       * @exception Exception If one of the factories accessed throws an
126       *     exception, or if an error was encountered while loading
127       *         and instantiating the factory and object classes.
128       *     A factory should only throw an exception if it does not want
129       *     other factories to be used in an attempt to create an object.
130       *     See <tt>DirObjectFactory.getObjectInstance()</tt>.
131       * @see NamingManager#getURLContext
132       * @see DirObjectFactory
133       * @see DirObjectFactory#getObjectInstance
134       * @since 1.3
135       */
136     public static Object  
137     getObjectInstance(Object   refInfo, Name   name, Context   nameCtx,
138               Hashtable  <?,?> environment, Attributes   attrs)
139     throws Exception   {
140 
141         ObjectFactory   factory;
142 
143         ObjectFactoryBuilder   builder = getObjectFactoryBuilder();
144         if (builder != null) {
145         // builder must return non-null factory
146         factory = builder.createObjectFactory(refInfo, environment);
147         if (factory instanceof DirObjectFactory  ) {
148             return ((DirObjectFactory  )factory).getObjectInstance(
149             refInfo, name, nameCtx, environment, attrs);
150         } else {
151             return factory.getObjectInstance(refInfo, name, nameCtx,
152             environment);
153         }
154         }
155 
156         // use reference if possible
157         Reference   ref = null;
158         if (refInfo instanceof Reference  ) {
159         ref = (Reference  ) refInfo;
160         } else if (refInfo instanceof Referenceable  ) {
161         ref = ((Referenceable  )(refInfo)).getReference();
162         }
163 
164         Object   answer;
165 
166         if (ref != null) {
167         String   f = ref.getFactoryClassName();
168         if (f != null) {
169             // if reference identifies a factory, use exclusively
170 
171             factory = getObjectFactoryFromReference(ref, f);
172             if (factory instanceof DirObjectFactory  ) {
173             return ((DirObjectFactory  )factory).getObjectInstance(
174                 ref, name, nameCtx, environment, attrs);
175             } else if (factory != null) {
176             return factory.getObjectInstance(ref, name, nameCtx,
177                              environment);
178             }
179             // No factory found, so return original refInfo.
180             // Will reach this point if factory class is not in
181             // class path and reference does not contain a URL for it
182             return refInfo;
183 
184         } else {
185             // if reference has no factory, check for addresses
186             // containing URLs
187             // ignore name & attrs params; not used in URL factory
188 
189             answer = processURLAddrs(ref, name, nameCtx, environment);
190             if (answer != null) {
191             return answer;
192             }
193         }
194         }
195 
196         // try using any specified factories
197         answer = createObjectFromFactories(refInfo, name, nameCtx,
198                            environment, attrs);
199         return (answer != null) ? answer : refInfo;
200     }
201 
202     private static Object   createObjectFromFactories(Object   obj, Name   name,
203         Context   nameCtx, Hashtable   environment, Attributes   attrs) 
204     throws Exception   {
205 
206         FactoryEnumeration factories = ResourceManager.getFactories(
207         Context.OBJECT_FACTORIES, environment, nameCtx);
208 
209     if (factories == null)
210         return null;
211 
212     ObjectFactory   factory;
213     Object   answer = null;
214     // Try each factory until one succeeds
215     while (answer == null && factories.hasMore()) {
216         factory = (ObjectFactory  )factories.next();
217         if (factory instanceof DirObjectFactory  ) {
218         answer = ((DirObjectFactory  )factory).
219             getObjectInstance(obj, name, nameCtx, environment, attrs);
220         } else {
221         answer =
222             factory.getObjectInstance(obj, name, nameCtx, environment);
223         }
224     }
225     return answer;
226     }
227 
228     /**
229       * Retrieves the state of an object for binding when given the original
230       * object and its attributes.
231       * <p>
232       * This method is like <tt>NamingManager.getStateToBind</tt> except
233       * for the following differences:
234       *<ul>
235       *<li>It accepts an <tt>Attributes</tt> parameter containing attributes
236       *    that were passed to the <tt>DirContext.bind()</tt> method.
237       *<li>It returns a non-null <tt>DirStateFactory.Result</tt> instance
238       *    containing the object to be bound, and the attributes to
239       *    accompany the binding. Either the object or the attributes may be null.
240       *<li>
241       * The state factories tried must each implement either 
242       * <tt>StateFactory</tt> or <tt>DirStateFactory</tt>.
243       * If it implements <tt>DirStateFactory</tt>, then
244       * <tt>DirStateFactory.getStateToBind()</tt> is called; otherwise,
245       * <tt>StateFactory.getStateToBind()</tt> is called.
246       *</ul>
247       *
248       * Service providers that implement the <tt>DirContext</tt> interface
249       * should use this method, not <tt>NamingManager.getStateToBind()</tt>.
250       *<p>
251       * See NamingManager.getStateToBind() for a description of how
252       * the list of state factories to be tried is determined.
253       *<p>
254       * The object returned by this method is owned by the caller.
255       * The implementation will not subsequently modify it.
256       * It will contain either a new <tt>Attributes</tt> object that is
257       * likewise owned by the caller, or a reference to the original
258       * <tt>attrs</tt> parameter.
259       *
260       * @param obj The non-null object for which to get state to bind.
261       * @param name The name of this object relative to <code>nameCtx</code>,
262       *     or null if no name is specified.
263       * @param nameCtx The context relative to which the <code>name</code>
264       *     parameter is specified, or null if <code>name</code> is
265       *     relative to the default initial context.
266       * @param environment The possibly null environment to 
267       *     be used in the creation of the state factory and 
268       *     the object's state.
269       * @param attrs The possibly null Attributes that is to be bound with the
270       *     object.
271       * @return A non-null DirStateFactory.Result containing
272       *  the object and attributes to be bound.
273       *  If no state factory returns a non-null answer, the result will contain
274       *  the object (<tt>obj</tt>) itself with the original attributes.
275       * @exception NamingException If a naming exception was encountered
276       *     while using the factories.
277       *     A factory should only throw an exception if it does not want
278       *     other factories to be used in an attempt to create an object.
279       *     See <tt>DirStateFactory.getStateToBind()</tt>.
280       * @see DirStateFactory
281       * @see DirStateFactory#getStateToBind
282       * @see NamingManager#getStateToBind
283       * @since 1.3
284       */
285     public static DirStateFactory.Result   
286     getStateToBind(Object   obj, Name   name, Context   nameCtx,
287                Hashtable  <?,?> environment, Attributes   attrs)
288     throws NamingException   {
289 
290     // Get list of state factories
291     FactoryEnumeration factories = ResourceManager.getFactories(
292         Context.STATE_FACTORIES, environment, nameCtx);
293 
294     if (factories == null) {
295         // no factories to try; just return originals
296         return new DirStateFactory.Result  (obj, attrs);
297     }
298 
299     // Try each factory until one succeeds
300     StateFactory   factory; 
301     Object   objanswer;
302     DirStateFactory.Result   answer = null;
303     while (answer == null && factories.hasMore()) {
304         factory = (StateFactory  )factories.next();
305         if (factory instanceof DirStateFactory  ) {
306         answer = ((DirStateFactory  )factory).
307             getStateToBind(obj, name, nameCtx, environment, attrs);
308         } else {
309         objanswer = 
310             factory.getStateToBind(obj, name, nameCtx, environment);
311         if (objanswer != null) {
312             answer = new DirStateFactory.Result  (objanswer, attrs);
313         }
314         }
315     }
316 
317     return (answer != null) ? answer :
318         new DirStateFactory.Result  (obj, attrs); // nothing new
319     }
320 }
321
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags