39 import com.sun.naming.internal.ResourceManager; |
39 import com.sun.naming.internal.ResourceManager; |
40 import com.sun.naming.internal.FactoryEnumeration; |
40 import com.sun.naming.internal.FactoryEnumeration; |
41 |
41 |
42 |
42 |
43 /** |
43 /** |
44 * This class contains methods for supporting <tt>DirContext</tt> |
44 * This class contains methods for supporting {@code DirContext} |
45 * implementations. |
45 * implementations. |
46 *<p> |
46 *<p> |
47 * This class is an extension of <tt>NamingManager</tt>. It contains methods |
47 * This class is an extension of {@code NamingManager}. It contains methods |
48 * for use by service providers for accessing object factories and |
48 * for use by service providers for accessing object factories and |
49 * state factories, and for getting continuation contexts for |
49 * state factories, and for getting continuation contexts for |
50 * supporting federation. |
50 * supporting federation. |
51 *<p> |
51 *<p> |
52 * <tt>DirectoryManager</tt> is safe for concurrent access by multiple threads. |
52 * {@code DirectoryManager} is safe for concurrent access by multiple threads. |
53 *<p> |
53 *<p> |
54 * Except as otherwise noted, |
54 * Except as otherwise noted, |
55 * a <tt>Name</tt>, <tt>Attributes</tt>, or environment parameter |
55 * a {@code Name}, {@code Attributes}, or environment parameter |
56 * passed to any method is owned by the caller. |
56 * passed to any method is owned by the caller. |
57 * The implementation will not modify the object or keep a reference |
57 * The implementation will not modify the object or keep a reference |
58 * to it, although it may keep a reference to a clone or copy. |
58 * to it, although it may keep a reference to a clone or copy. |
59 * |
59 * |
60 * @author Rosanna Lee |
60 * @author Rosanna Lee |
71 * Disallow anyone from creating one of these. |
71 * Disallow anyone from creating one of these. |
72 */ |
72 */ |
73 DirectoryManager() {} |
73 DirectoryManager() {} |
74 |
74 |
75 /** |
75 /** |
76 * Creates a context in which to continue a <tt>DirContext</tt> operation. |
76 * Creates a context in which to continue a {@code DirContext} operation. |
77 * Operates just like <tt>NamingManager.getContinuationContext()</tt>, |
77 * Operates just like {@code NamingManager.getContinuationContext()}, |
78 * only the continuation context returned is a <tt>DirContext</tt>. |
78 * only the continuation context returned is a {@code DirContext}. |
79 * |
79 * |
80 * @param cpe |
80 * @param cpe |
81 * The non-null exception that triggered this continuation. |
81 * The non-null exception that triggered this continuation. |
82 * @return A non-null <tt>DirContext</tt> object for continuing the operation. |
82 * @return A non-null {@code DirContext} object for continuing the operation. |
83 * @exception NamingException If a naming exception occurred. |
83 * @exception NamingException If a naming exception occurred. |
84 * |
84 * |
85 * @see NamingManager#getContinuationContext(CannotProceedException) |
85 * @see NamingManager#getContinuationContext(CannotProceedException) |
86 */ |
86 */ |
87 @SuppressWarnings("unchecked") |
87 @SuppressWarnings("unchecked") |
102 |
102 |
103 /** |
103 /** |
104 * Creates an instance of an object for the specified object, |
104 * Creates an instance of an object for the specified object, |
105 * attributes, and environment. |
105 * attributes, and environment. |
106 * <p> |
106 * <p> |
107 * This method is the same as <tt>NamingManager.getObjectInstance</tt> |
107 * This method is the same as {@code NamingManager.getObjectInstance} |
108 * except for the following differences: |
108 * except for the following differences: |
109 *<ul> |
109 *<ul> |
110 *<li> |
110 *<li> |
111 * It accepts an <tt>Attributes</tt> parameter that contains attributes |
111 * It accepts an {@code Attributes} parameter that contains attributes |
112 * associated with the object. The <tt>DirObjectFactory</tt> might use these |
112 * associated with the object. The {@code DirObjectFactory} might use these |
113 * attributes to save having to look them up from the directory. |
113 * attributes to save having to look them up from the directory. |
114 *<li> |
114 *<li> |
115 * The object factories tried must implement either |
115 * The object factories tried must implement either |
116 * <tt>ObjectFactory</tt> or <tt>DirObjectFactory</tt>. |
116 * {@code ObjectFactory} or {@code DirObjectFactory}. |
117 * If it implements <tt>DirObjectFactory</tt>, |
117 * If it implements {@code DirObjectFactory}, |
118 * <tt>DirObjectFactory.getObjectInstance()</tt> is used, otherwise, |
118 * {@code DirObjectFactory.getObjectInstance()} is used, otherwise, |
119 * <tt>ObjectFactory.getObjectInstance()</tt> is used. |
119 * {@code ObjectFactory.getObjectInstance()} is used. |
120 *</ul> |
120 *</ul> |
121 * Service providers that implement the <tt>DirContext</tt> interface |
121 * Service providers that implement the {@code DirContext} interface |
122 * should use this method, not <tt>NamingManager.getObjectInstance()</tt>. |
122 * should use this method, not {@code NamingManager.getObjectInstance()}. |
123 * |
123 * |
124 * @param refInfo The possibly null object for which to create an object. |
124 * @param refInfo The possibly null object for which to create an object. |
125 * @param name The name of this object relative to <code>nameCtx</code>. |
125 * @param name The name of this object relative to {@code nameCtx}. |
126 * Specifying a name is optional; if it is |
126 * Specifying a name is optional; if it is |
127 * omitted, <code>name</code> should be null. |
127 * omitted, {@code name} should be null. |
128 * @param nameCtx The context relative to which the <code>name</code> |
128 * @param nameCtx The context relative to which the {@code name} |
129 * parameter is specified. If null, <code>name</code> is |
129 * parameter is specified. If null, {@code name} is |
130 * relative to the default initial context. |
130 * relative to the default initial context. |
131 * @param environment The possibly null environment to |
131 * @param environment The possibly null environment to |
132 * be used in the creation of the object factory and the object. |
132 * be used in the creation of the object factory and the object. |
133 * @param attrs The possibly null attributes associated with refInfo. |
133 * @param attrs The possibly null attributes associated with refInfo. |
134 * This might not be the complete set of attributes for refInfo; |
134 * This might not be the complete set of attributes for refInfo; |
135 * you might be able to read more attributes from the directory. |
135 * you might be able to read more attributes from the directory. |
136 * @return An object created using <code>refInfo</code> and <tt>attrs</tt>; or |
136 * @return An object created using {@code refInfo} and {@code attrs}; or |
137 * <code>refInfo</code> if an object cannot be created by |
137 * {@code refInfo} if an object cannot be created by |
138 * a factory. |
138 * a factory. |
139 * @exception NamingException If a naming exception was encountered |
139 * @exception NamingException If a naming exception was encountered |
140 * while attempting to get a URL context, or if one of the |
140 * while attempting to get a URL context, or if one of the |
141 * factories accessed throws a NamingException. |
141 * factories accessed throws a NamingException. |
142 * @exception Exception If one of the factories accessed throws an |
142 * @exception Exception If one of the factories accessed throws an |
143 * exception, or if an error was encountered while loading |
143 * exception, or if an error was encountered while loading |
144 * and instantiating the factory and object classes. |
144 * and instantiating the factory and object classes. |
145 * A factory should only throw an exception if it does not want |
145 * A factory should only throw an exception if it does not want |
146 * other factories to be used in an attempt to create an object. |
146 * other factories to be used in an attempt to create an object. |
147 * See <tt>DirObjectFactory.getObjectInstance()</tt>. |
147 * See {@code DirObjectFactory.getObjectInstance()}. |
148 * @see NamingManager#getURLContext |
148 * @see NamingManager#getURLContext |
149 * @see DirObjectFactory |
149 * @see DirObjectFactory |
150 * @see DirObjectFactory#getObjectInstance |
150 * @see DirObjectFactory#getObjectInstance |
151 * @since 1.3 |
151 * @since 1.3 |
152 */ |
152 */ |
244 |
244 |
245 /** |
245 /** |
246 * Retrieves the state of an object for binding when given the original |
246 * Retrieves the state of an object for binding when given the original |
247 * object and its attributes. |
247 * object and its attributes. |
248 * <p> |
248 * <p> |
249 * This method is like <tt>NamingManager.getStateToBind</tt> except |
249 * This method is like {@code NamingManager.getStateToBind} except |
250 * for the following differences: |
250 * for the following differences: |
251 *<ul> |
251 *<ul> |
252 *<li>It accepts an <tt>Attributes</tt> parameter containing attributes |
252 *<li>It accepts an {@code Attributes} parameter containing attributes |
253 * that were passed to the <tt>DirContext.bind()</tt> method. |
253 * that were passed to the {@code DirContext.bind()} method. |
254 *<li>It returns a non-null <tt>DirStateFactory.Result</tt> instance |
254 *<li>It returns a non-null {@code DirStateFactory.Result} instance |
255 * containing the object to be bound, and the attributes to |
255 * containing the object to be bound, and the attributes to |
256 * accompany the binding. Either the object or the attributes may be null. |
256 * accompany the binding. Either the object or the attributes may be null. |
257 *<li> |
257 *<li> |
258 * The state factories tried must each implement either |
258 * The state factories tried must each implement either |
259 * <tt>StateFactory</tt> or <tt>DirStateFactory</tt>. |
259 * {@code StateFactory} or {@code DirStateFactory}. |
260 * If it implements <tt>DirStateFactory</tt>, then |
260 * If it implements {@code DirStateFactory}, then |
261 * <tt>DirStateFactory.getStateToBind()</tt> is called; otherwise, |
261 * {@code DirStateFactory.getStateToBind()} is called; otherwise, |
262 * <tt>StateFactory.getStateToBind()</tt> is called. |
262 * {@code StateFactory.getStateToBind()} is called. |
263 *</ul> |
263 *</ul> |
264 * |
264 * |
265 * Service providers that implement the <tt>DirContext</tt> interface |
265 * Service providers that implement the {@code DirContext} interface |
266 * should use this method, not <tt>NamingManager.getStateToBind()</tt>. |
266 * should use this method, not {@code NamingManager.getStateToBind()}. |
267 *<p> |
267 *<p> |
268 * See NamingManager.getStateToBind() for a description of how |
268 * See NamingManager.getStateToBind() for a description of how |
269 * the list of state factories to be tried is determined. |
269 * the list of state factories to be tried is determined. |
270 *<p> |
270 *<p> |
271 * The object returned by this method is owned by the caller. |
271 * The object returned by this method is owned by the caller. |
272 * The implementation will not subsequently modify it. |
272 * The implementation will not subsequently modify it. |
273 * It will contain either a new <tt>Attributes</tt> object that is |
273 * It will contain either a new {@code Attributes} object that is |
274 * likewise owned by the caller, or a reference to the original |
274 * likewise owned by the caller, or a reference to the original |
275 * <tt>attrs</tt> parameter. |
275 * {@code attrs} parameter. |
276 * |
276 * |
277 * @param obj The non-null object for which to get state to bind. |
277 * @param obj The non-null object for which to get state to bind. |
278 * @param name The name of this object relative to <code>nameCtx</code>, |
278 * @param name The name of this object relative to {@code nameCtx}, |
279 * or null if no name is specified. |
279 * or null if no name is specified. |
280 * @param nameCtx The context relative to which the <code>name</code> |
280 * @param nameCtx The context relative to which the {@code name} |
281 * parameter is specified, or null if <code>name</code> is |
281 * parameter is specified, or null if {@code name} is |
282 * relative to the default initial context. |
282 * relative to the default initial context. |
283 * @param environment The possibly null environment to |
283 * @param environment The possibly null environment to |
284 * be used in the creation of the state factory and |
284 * be used in the creation of the state factory and |
285 * the object's state. |
285 * the object's state. |
286 * @param attrs The possibly null Attributes that is to be bound with the |
286 * @param attrs The possibly null Attributes that is to be bound with the |
287 * object. |
287 * object. |
288 * @return A non-null DirStateFactory.Result containing |
288 * @return A non-null DirStateFactory.Result containing |
289 * the object and attributes to be bound. |
289 * the object and attributes to be bound. |
290 * If no state factory returns a non-null answer, the result will contain |
290 * If no state factory returns a non-null answer, the result will contain |
291 * the object (<tt>obj</tt>) itself with the original attributes. |
291 * the object ({@code obj}) itself with the original attributes. |
292 * @exception NamingException If a naming exception was encountered |
292 * @exception NamingException If a naming exception was encountered |
293 * while using the factories. |
293 * while using the factories. |
294 * A factory should only throw an exception if it does not want |
294 * A factory should only throw an exception if it does not want |
295 * other factories to be used in an attempt to create an object. |
295 * other factories to be used in an attempt to create an object. |
296 * See <tt>DirStateFactory.getStateToBind()</tt>. |
296 * See {@code DirStateFactory.getStateToBind()}. |
297 * @see DirStateFactory |
297 * @see DirStateFactory |
298 * @see DirStateFactory#getStateToBind |
298 * @see DirStateFactory#getStateToBind |
299 * @see NamingManager#getStateToBind |
299 * @see NamingManager#getStateToBind |
300 * @since 1.3 |
300 * @since 1.3 |
301 */ |
301 */ |