Java > Open Source Codes > javax > naming > InitialContext


1 /*
2  * @(#)InitialContext.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;
9
10 import java.util.Hashtable ;
11 import javax.naming.spi.NamingManager ;
12 import com.sun.naming.internal.ResourceManager;
13
14 /**
15  * This class is the starting context for performing naming operations.
16  *<p>
17  * All naming operations are relative to a context.
18  * The initial context implements the Context interface and
19  * provides the starting point for resolution of names.
20  *<p>
21  * <a name=ENVIRONMENT></a>
22  * When the initial context is constructed, its environment
23  * is initialized with properties defined in the environment parameter
24  * passed to the constructor, and in any
25  * <a HREF=Context.html#RESOURCEFILES>application resource files</a>.
26  * In addition, a small number of standard JNDI properties may
27  * be specified as system properties or as applet parameters
28  * (through the use of {@link Context#APPLET}).
29  * These special properties are listed in the field detail sections of the
30  * <a HREF=Context.html#field_detail><tt>Context</tt></a> and
31  * <a HREF=ldap/LdapContext.html#field_detail><tt>LdapContext</tt></a>
32  * interface documentation.
33  *<p>
34  * JNDI determines each property's value by merging
35  * the values from the following two sources, in order:
36  * <ol>
37  * <li>
38  * The first occurrence of the property from the constructor's
39  * environment parameter and (for appropriate properties) the applet
40  * parameters and system properties.
41  * <li>
42  * The application resource files (<tt>jndi.properties</tt>).
43  * </ol>
44  * For each property found in both of these two sources, or in
45  * more than one application resource file, the property's value
46  * is determined as follows. If the property is
47  * one of the standard JNDI properties that specify a list of JNDI
48  * factories (see <a HREF=Context.html#LISTPROPS><tt>Context</tt></a>),
49  * all of the values are
50  * concatenated into a single colon-separated list. For other
51  * properties, only the first value found is used.
52  *
53  *<p>
54  * The initial context implementation is determined at runtime.
55  * The default policy uses the environment property
56  * "{@link Context#INITIAL_CONTEXT_FACTORY java.naming.factory.initial}",
57  * which contains the class name of the initial context factory.
58  * An exception to this policy is made when resolving URL strings, as described
59  * below.
60  *<p>
61  * When a URL string (a <tt>String</tt> of the form
62  * <em>scheme_id:rest_of_name</em>) is passed as a name parameter to
63  * any method, a URL context factory for handling that scheme is
64  * located and used to resolve the URL. If no such factory is found,
65  * the initial context specified by
66  * <tt>"java.naming.factory.initial"</tt> is used. Similarly, when a
67  * <tt>CompositeName</tt> object whose first component is a URL string is
68  * passed as a name parameter to any method, a URL context factory is
69  * located and used to resolve the first name component.
70  * See {@link NamingManager#getURLContext
71  * <tt>NamingManager.getURLContext()</tt>} for a description of how URL
72  * context factories are located.
73  *<p>
74  * This default policy of locating the initial context and URL context
75  * factories may be overridden
76  * by calling
77  * <tt>NamingManager.setInitialContextFactoryBuilder()</tt>.
78  *<p>
79  * NoInitialContextException is thrown when an initial context cannot
80  * be instantiated. This exception can be thrown during any interaction
81  * with the InitialContext, not only when the InitialContext is constructed.
82  * For example, the implementation of the initial context might lazily
83  * retrieve the context only when actual methods are invoked on it.
84  * The application should not have any dependency on when the existence
85  * of an initial context is determined.
86  *<p>
87  * When the environment property "java.naming.factory.initial" is
88  * non-null, the InitialContext constructor will attempt to create the
89  * initial context specified therein. At that time, the initial context factory
90  * involved might throw an exception if a problem is encountered. However,
91  * it is provider implementation-dependent when it verifies and indicates
92  * to the users of the initial context any environment property- or
93  * connection- related problems. It can do so lazily--delaying until
94  * an operation is performed on the context, or eagerly, at the time
95  * the context is constructed.
96  *<p>
97  * An InitialContext instance is not synchronized against concurrent
98  * access by multiple threads. Multiple threads each manipulating a
99  * different InitialContext instance need not synchronize.
100  * Threads that need to access a single InitialContext instance
101  * concurrently should synchronize amongst themselves and provide the
102  * necessary locking.
103  *
104  * @author Rosanna Lee
105  * @author Scott Seligman
106  * @version 1.13 04/07/16
107  *
108  * @see Context
109  * @see NamingManager#setInitialContextFactoryBuilder
110  * NamingManager.setInitialContextFactoryBuilder
111  * @since JNDI 1.1 / Java 2 Platform, Standard Edition, v 1.3
112  */
113
114 public class InitialContext implements Context {
115
116     /**
117      * The environment associated with this InitialContext.
118      * It is initialized to null and is updated by the constructor
119      * that accepts an environment or by the <tt>init()</tt> method.
120      * @see #addToEnvironment
121      * @see #removeFromEnvironment
122      * @see #getEnvironment
123      */
124     protected Hashtable <Object ,Object > myProps = null;
125
126     /**
127      * Field holding the result of calling NamingManager.getInitialContext().
128      * It is set by getDefaultInitCtx() the first time getDefaultInitCtx()
129      * is called. Subsequent invocations of getDefaultInitCtx() return
130      * the value of defaultInitCtx.
131      * @see #getDefaultInitCtx
132      */
133     protected Context defaultInitCtx = null;
134
135     /**
136      * Field indicating whether the initial context has been obtained
137      * by calling NamingManager.getInitialContext().
138      * If true, its result is in <code>defaultInitCtx</code>.
139      */
140     protected boolean gotDefault = false;
141
142     /**
143      * Constructs an initial context with the option of not
144      * initializing it. This may be used by a constructor in
145      * a subclass when the value of the environment parameter
146      * is not yet known at the time the <tt>InitialContext</tt>
147      * constructor is called. The subclass's constructor will
148      * call this constructor, compute the value of the environment,
149      * and then call <tt>init()</tt> before returning.
150      *
151      * @param lazy
152      * true means do not initialize the initial context; false
153      * is equivalent to calling <tt>new InitialContext()</tt>
154      * @throws NamingException if a naming exception is encountered
155      *
156      * @see #init(Hashtable)
157      * @since 1.3
158      */
159     protected InitialContext(boolean lazy) throws NamingException {
160     if (!lazy) {
161         init(null);
162     }
163     }
164
165     /**
166      * Constructs an initial context.
167      * No environment properties are supplied.
168      * Equivalent to <tt>new InitialContext(null)</tt>.
169      *
170      * @throws NamingException if a naming exception is encountered
171      *
172      * @see #InitialContext(Hashtable)
173      */
174     public InitialContext() throws NamingException {
175     init(null);
176     }
177
178     /**
179      * Constructs an initial context using the supplied environment.
180      * Environment properties are discussed in the class description.
181      *
182      * <p> This constructor will not modify <tt>environment</tt>
183      * or save a reference to it, but may save a clone.
184      *
185      * @param environment
186      * environment used to create the initial context.
187      * Null indicates an empty environment.
188      *
189      * @throws NamingException if a naming exception is encountered
190      */
191     public InitialContext(Hashtable <?,?> environment)
192     throws NamingException
193     {
194     if (environment != null) {
195         environment = (Hashtable )environment.clone();
196     }
197     init(environment);
198     }
199
200     /**
201      * Initializes the initial context using the supplied environment.
202      * Environment properties are discussed in the class description.
203      *
204      * <p> This method will modify <tt>environment</tt> and save
205      * a reference to it. The caller may no longer modify it.
206      *
207      * @param environment
208      * environment used to create the initial context.
209      * Null indicates an empty environment.
210      *
211      * @throws NamingException if a naming exception is encountered
212      *
213      * @see #InitialContext(boolean)
214      * @since 1.3
215      */
216     protected void init(Hashtable <?,?> environment)
217     throws NamingException
218     {
219     myProps = ResourceManager.getInitialEnvironment(environment);
220
221     if (myProps.get(Context.INITIAL_CONTEXT_FACTORY) != null) {
222         // user has specified initial context factory; try to get it
223 getDefaultInitCtx();
224     }
225     }
226
227     private static String getURLScheme(String str) {
228     int colon_posn = str.indexOf(':');
229     int slash_posn = str.indexOf('/');
230
231     if (colon_posn > 0 && (slash_posn == -1 || colon_posn < slash_posn))
232         return str.substring(0, colon_posn);
233     return null;
234     }
235
236     /**
237      * Retrieves the initial context by calling
238      * <code>NamingManager.getInitialContext()</code>
239      * and cache it in defaultInitCtx.
240      * Set <code>gotDefault</code> so that we know we've tried this before.
241      * @return The non-null cached initial context.
242      * @exception NoInitialContextException If cannot find an initial context.
243      * @exception NamingException If a naming exception was encountered.
244      */
245     protected Context getDefaultInitCtx() throws NamingException {
246     if (!gotDefault) {
247         defaultInitCtx = NamingManager.getInitialContext(myProps);
248         gotDefault = true;
249     }
250     if (defaultInitCtx == null)
251         throw new NoInitialContextException ();
252
253     return defaultInitCtx;
254     }
255
256     /**
257      * Retrieves a context for resolving the string name <code>name</code>.
258      * If <code>name</code> name is a URL string, then attempt
259      * to find a URL context for it. If none is found, or if
260      * <code>name</code> is not a URL string, then return
261      * <code>getDefaultInitCtx()</code>.
262      *<p>
263      * See getURLOrDefaultInitCtx(Name) for description
264      * of how a subclass should use this method.
265      * @param name The non-null name for which to get the context.
266      * @return A URL context for <code>name</code> or the cached
267      * initial context. The result cannot be null.
268      * @exception NoInitialContextException If cannot find an initial context.
269      * @exception NamingException In a naming exception is encountered.
270      * @see javax.naming.spi.NamingManager#getURLContext
271      */
272     protected Context getURLOrDefaultInitCtx(String name)
273     throws NamingException {
274     if (NamingManager.hasInitialContextFactoryBuilder()) {
275         return getDefaultInitCtx();
276     }
277     String scheme = getURLScheme(name);
278     if (scheme != null) {
279         Context ctx = NamingManager.getURLContext(scheme, myProps);
280         if (ctx != null) {
281         return ctx;
282         }
283     }
284     return getDefaultInitCtx();
285     }
286
287     /**
288      * Retrieves a context for resolving <code>name</code>.
289      * If the first component of <code>name</code> name is a URL string,
290      * then attempt to find a URL context for it. If none is found, or if
291      * the first component of <code>name</code> is not a URL string,
292      * then return <code>getDefaultInitCtx()</code>.
293      *<p>
294      * When creating a subclass of InitialContext, use this method as
295      * follows.
296      * Define a new method that uses this method to get an initial
297      * context of the desired subclass.
298      * <p><blockquote><pre>
299      * protected XXXContext getURLOrDefaultInitXXXCtx(Name name)
300      * throws NamingException {
301      * Context answer = getURLOrDefaultInitCtx(name);
302      * if (!(answer instanceof XXXContext)) {
303      * if (answer == null) {
304      * throw new NoInitialContextException();
305      * } else {
306      * throw new NotContextException("Not an XXXContext");
307      * }
308      * }
309      * return (XXXContext)answer;
310      * }
311      * </pre></blockquote>
312      * When providing implementations for the new methods in the subclass,
313      * use this newly defined method to get the initial context.
314      * <p><blockquote><pre>
315      * public Object XXXMethod1(Name name, ...) {
316      * throws NamingException {
317      * return getURLOrDefaultInitXXXCtx(name).XXXMethod1(name, ...);
318      * }
319      * </pre></blockquote>
320      *
321      * @param name The non-null name for which to get the context.
322      * @return A URL context for <code>name</code> or the cached
323      * initial context. The result cannot be null.
324      * @exception NoInitialContextException If cannot find an initial context.
325      * @exception NamingException In a naming exception is encountered.
326      *
327      * @see javax.naming.spi.NamingManager#getURLContext
328      */
329     protected Context getURLOrDefaultInitCtx(Name name)
330     throws NamingException {
331     if (NamingManager.hasInitialContextFactoryBuilder()) {
332         return getDefaultInitCtx();
333     }
334     if (name.size() > 0) {
335         String first = name.get(0);
336         String scheme = getURLScheme(first);
337         if (scheme != null) {
338         Context ctx = NamingManager.getURLContext(scheme, myProps);
339         if (ctx != null) {
340             return ctx;
341         }
342         }
343     }
344     return getDefaultInitCtx();
345     }
346
347 // Context methods
348 // Most Javadoc is deferred to the Context interface.
349
350     public Object lookup(String name) throws NamingException {
351     return getURLOrDefaultInitCtx(name).lookup(name);
352     }
353
354     public Object lookup(Name name) throws NamingException {
355     return getURLOrDefaultInitCtx(name).lookup(name);
356     }
357
358     public void bind(String name, Object obj) throws NamingException {
359     getURLOrDefaultInitCtx(name).bind(name, obj);
360     }
361
362     public void bind(Name name, Object obj) throws NamingException {
363     getURLOrDefaultInitCtx(name).bind(name, obj);
364     }
365
366     public void rebind(String name, Object obj) throws NamingException {
367     getURLOrDefaultInitCtx(name).rebind(name, obj);
368     }
369
370     public void rebind(Name name, Object obj) throws NamingException {
371     getURLOrDefaultInitCtx(name).rebind(name, obj);
372     }
373
374     public void unbind(String name) throws NamingException {
375     getURLOrDefaultInitCtx(name).unbind(name);
376     }
377
378     public void unbind(Name name) throws NamingException {
379     getURLOrDefaultInitCtx(name).unbind(name);
380     }
381
382     public void rename(String oldName, String newName) throws NamingException {
383     getURLOrDefaultInitCtx(oldName).rename(oldName, newName);
384     }
385
386     public void rename(Name oldName, Name newName)
387     throws NamingException
388     {
389     getURLOrDefaultInitCtx(oldName).rename(oldName, newName);
390     }
391
392     public NamingEnumeration <NameClassPair > list(String name)
393     throws NamingException
394     {
395     return (getURLOrDefaultInitCtx(name).list(name));
396     }
397
398     public NamingEnumeration <NameClassPair > list(Name name)
399     throws NamingException
400     {
401     return (getURLOrDefaultInitCtx(name).list(name));
402     }
403
404     public NamingEnumeration <Binding > listBindings(String name)
405         throws NamingException {
406     return getURLOrDefaultInitCtx(name).listBindings(name);
407     }
408
409     public NamingEnumeration <Binding > listBindings(Name name)
410         throws NamingException {
411     return getURLOrDefaultInitCtx(name).listBindings(name);
412     }
413
414     public void destroySubcontext(String name) throws NamingException {
415     getURLOrDefaultInitCtx(name).destroySubcontext(name);
416     }
417
418     public void destroySubcontext(Name name) throws NamingException {
419     getURLOrDefaultInitCtx(name).destroySubcontext(name);
420     }
421
422     public Context createSubcontext(String name) throws NamingException {
423     return getURLOrDefaultInitCtx(name).createSubcontext(name);
424     }
425
426     public Context createSubcontext(Name name) throws NamingException {
427     return getURLOrDefaultInitCtx(name).createSubcontext(name);
428     }
429
430     public Object lookupLink(String name) throws NamingException {
431     return getURLOrDefaultInitCtx(name).lookupLink(name);
432     }
433
434     public Object lookupLink(Name name) throws NamingException {
435     return getURLOrDefaultInitCtx(name).lookupLink(name);
436     }
437
438     public NameParser getNameParser(String name) throws NamingException {
439     return getURLOrDefaultInitCtx(name).getNameParser(name);
440     }
441
442     public NameParser getNameParser(Name name) throws NamingException {
443     return getURLOrDefaultInitCtx(name).getNameParser(name);
444     }
445
446     /**
447      * Composes the name of this context with a name relative to
448      * this context.
449      * Since an initial context may never be named relative
450      * to any context other than itself, the value of the
451      * <tt>prefix</tt> parameter must be an empty name (<tt>""</tt>).
452      */
453     public String composeName(String name, String prefix)
454         throws NamingException {
455     return name;
456     }
457
458     /**
459      * Composes the name of this context with a name relative to
460      * this context.
461      * Since an initial context may never be named relative
462      * to any context other than itself, the value of the
463      * <tt>prefix</tt> parameter must be an empty name.
464      */
465     public Name composeName(Name name, Name prefix)
466     throws NamingException
467     {
468     return (Name )name.clone();
469     }
470
471     public Object addToEnvironment(String propName, Object propVal)
472         throws NamingException {
473     myProps.put(propName, propVal);
474     return getDefaultInitCtx().addToEnvironment(propName, propVal);
475     }
476
477     public Object removeFromEnvironment(String propName)
478         throws NamingException {
479     myProps.remove(propName);
480     return getDefaultInitCtx().removeFromEnvironment(propName);
481     }
482
483     public Hashtable <?,?> getEnvironment() throws NamingException {
484     return getDefaultInitCtx().getEnvironment();
485     }
486
487     public void close() throws NamingException {
488     myProps = null;
489     if (defaultInitCtx != null) {
490         defaultInitCtx.close();
491         defaultInitCtx = null;
492     }
493     gotDefault = false;
494     }
495
496     public String getNameInNamespace() throws NamingException {
497     return getDefaultInitCtx().getNameInNamespace();
498     }
499 };
500

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags