KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > naming > SynchronizedContext


1 /*
2  * Copyright 2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */

16
17
18 package org.apache.naming;
19
20 import java.util.Hashtable JavaDoc;
21 import javax.naming.Context JavaDoc;
22 import javax.naming.Name JavaDoc;
23 import javax.naming.NameParser JavaDoc;
24 import javax.naming.NamingEnumeration JavaDoc;
25 import javax.naming.NamingException JavaDoc;
26
27 /**
28  *
29  * Synchronized JNDI context implementation. Wraps a Context instance,
30  * synchronizing access to JNDI methods.
31  *
32  */

33 public class SynchronizedContext implements Context JavaDoc {
34
35     /** Environment property controlling synchronization */
36     public static final String JavaDoc SYNCHRONIZED =
37         "org.apache.naming.synchronization";
38
39     /** Underlying JNDI Context */
40     private Context JavaDoc context;
41
42     /**
43      * Creates a new SynchronizedContext based on the given Context.
44      *
45      * @param context underlying JNDI context
46      */

47     public SynchronizedContext(Context JavaDoc context) {
48         this.context = context;
49     }
50
51     /**
52      * Retrieves the named object. If name is empty, returns a new instance
53      * of this context (which represents the same naming context as this
54      * context, but its environment may be modified independently and it may
55      * be accessed concurrently).
56      * <p>
57      * Like other methods, this method delegates to the underlying Context
58      * instance. If a new context is returned, whether or not the returned
59      * context will be Synchronized therefore depends on the type of the
60      * Context (and the value of its {@link #SYNCHRONIZED} environment
61      * property).
62      *
63      * @param name the name of the object to look up
64      * @return the object bound to name
65      * @exception NamingException if a naming exception is encountered
66      */

67     public synchronized Object JavaDoc lookup(Name JavaDoc name)
68         throws NamingException JavaDoc {
69         return this.context.lookup(name);
70     }
71
72     /**
73      * Retrieves the named object.
74      *
75      * @param name the name of the object to look up
76      * @return the object bound to name
77      * @exception NamingException if a naming exception is encountered
78      */

79     public synchronized Object JavaDoc lookup(String JavaDoc name)
80         throws NamingException JavaDoc {
81         return this.context.lookup(name);
82     }
83
84     /**
85      * Binds a name to an object. All intermediate contexts and the target
86      * context (that named by all but terminal atomic component of the name)
87      * must already exist.
88      *
89      * @param name the name to bind; may not be empty
90      * @param obj the object to bind; possibly null
91      * @exception NameAlreadyBoundException if name is already bound
92      * @exception InvalidAttributesException if object did not supply all
93      * mandatory attributes
94      * @exception NamingException if a naming exception is encountered
95      */

96     public synchronized void bind(Name JavaDoc name, Object JavaDoc obj)
97         throws NamingException JavaDoc {
98         this.context.bind(name, obj);
99     }
100
101     /**
102      * Binds a name to an object.
103      *
104      * @param name the name to bind; may not be empty
105      * @param obj the object to bind; possibly null
106      * @exception NameAlreadyBoundException if name is already bound
107      * @exception InvalidAttributesException if object did not supply all
108      * mandatory attributes
109      * @exception NamingException if a naming exception is encountered
110      */

111     public synchronized void bind(String JavaDoc name, Object JavaDoc obj)
112         throws NamingException JavaDoc {
113         this.context.bind(name, obj);
114     }
115
116     /**
117      * Binds a name to an object, overwriting any existing binding. All
118      * intermediate contexts and the target context (that named by all but
119      * terminal atomic component of the name) must already exist.
120      * <p>
121      * If the object is a DirContext, any existing attributes associated with
122      * the name are replaced with those of the object. Otherwise, any
123      * existing attributes associated with the name remain unchanged.
124      *
125      * @param name the name to bind; may not be empty
126      * @param obj the object to bind; possibly null
127      * @exception InvalidAttributesException if object did not supply all
128      * mandatory attributes
129      * @exception NamingException if a naming exception is encountered
130      */

131     public synchronized void rebind(Name JavaDoc name, Object JavaDoc obj)
132         throws NamingException JavaDoc {
133         this.context.rebind(name, obj);
134     }
135
136     /**
137      * Binds a name to an object, overwriting any existing binding.
138      *
139      * @param name the name to bind; may not be empty
140      * @param obj the object to bind; possibly null
141      * @exception InvalidAttributesException if object did not supply all
142      * mandatory attributes
143      * @exception NamingException if a naming exception is encountered
144      */

145     public synchronized void rebind(String JavaDoc name, Object JavaDoc obj)
146         throws NamingException JavaDoc {
147         this.context.rebind(name, obj);
148     }
149
150     /**
151      * Unbinds the named object. Removes the terminal atomic name in name
152      * from the target context--that named by all but the terminal atomic
153      * part of name.
154      * <p>
155      * This method is idempotent. It succeeds even if the terminal atomic
156      * name is not bound in the target context, but throws
157      * NameNotFoundException if any of the intermediate contexts do not exist.
158      *
159      * @param name the name to bind; may not be empty
160      * @exception NameNotFoundException if an intermediate context does not
161      * exist
162      * @exception NamingException if a naming exception is encountered
163      */

164     public synchronized void unbind(Name JavaDoc name)
165         throws NamingException JavaDoc {
166         this.context.unbind(name);
167     }
168
169     /**
170      * Unbinds the named object.
171      *
172      * @param name the name to bind; may not be empty
173      * @exception NameNotFoundException if an intermediate context does not
174      * exist
175      * @exception NamingException if a naming exception is encountered
176      */

177     public synchronized void unbind(String JavaDoc name)
178         throws NamingException JavaDoc {
179         this.context.unbind(name);
180     }
181
182     /**
183      * Binds a new name to the object bound to an old name, and unbinds the
184      * old name. Both names are relative to this context. Any attributes
185      * associated with the old name become associated with the new name.
186      * Intermediate contexts of the old name are not changed.
187      *
188      * @param oldName the name of the existing binding; may not be empty
189      * @param newName the name of the new binding; may not be empty
190      * @exception NameAlreadyBoundException if newName is already bound
191      * @exception NamingException if a naming exception is encountered
192      */

193     public synchronized void rename(Name JavaDoc oldName, Name JavaDoc newName)
194         throws NamingException JavaDoc {
195         this.context.rename(oldName, newName);
196     }
197
198     /**
199      * Binds a new name to the object bound to an old name, and unbinds the
200      * old name.
201      *
202      * @param oldName the name of the existing binding; may not be empty
203      * @param newName the name of the new binding; may not be empty
204      * @exception NameAlreadyBoundException if newName is already bound
205      * @exception NamingException if a naming exception is encountered
206      */

207     public synchronized void rename(String JavaDoc oldName, String JavaDoc newName)
208         throws NamingException JavaDoc {
209         this.context.rename(oldName, newName);
210     }
211
212     /**
213      * Enumerates the names bound in the named context, along with the class
214      * names of objects bound to them. The contents of any subcontexts are
215      * not included.
216      * <p>
217      * If a binding is added to or removed from this context, its effect on
218      * an enumeration previously returned is undefined.
219      *
220      * @param name the name of the context to list
221      * @return an enumeration of the names and class names of the bindings in
222      * this context. Each element of the enumeration is of type NameClassPair.
223      * @exception NamingException if a naming exception is encountered
224      */

225     public synchronized NamingEnumeration JavaDoc list(Name JavaDoc name)
226         throws NamingException JavaDoc {
227         return this.context.list(name);
228     }
229
230     /**
231      * Enumerates the names bound in the named context, along with the class
232      * names of objects bound to them.
233      *
234      * @param name the name of the context to list
235      * @return an enumeration of the names and class names of the bindings in
236      * this context. Each element of the enumeration is of type NameClassPair.
237      * @exception NamingException if a naming exception is encountered
238      */

239     public synchronized NamingEnumeration JavaDoc list(String JavaDoc name)
240         throws NamingException JavaDoc {
241         return this.context.list(name);
242     }
243
244     /**
245      * Enumerates the names bound in the named context, along with the
246      * objects bound to them. The contents of any subcontexts are not
247      * included.
248      * <p>
249      * If a binding is added to or removed from this context, its effect on
250      * an enumeration previously returned is undefined.
251      *
252      * @param name the name of the context to list
253      * @return an enumeration of the bindings in this context.
254      * Each element of the enumeration is of type Binding.
255      * @exception NamingException if a naming exception is encountered
256      */

257     public synchronized NamingEnumeration JavaDoc listBindings(Name JavaDoc name)
258         throws NamingException JavaDoc {
259         return this.context.listBindings(name);
260     }
261
262     /**
263      * Enumerates the names bound in the named context, along with the
264      * objects bound to them.
265      *
266      * @param name the name of the context to list
267      * @return an enumeration of the bindings in this context.
268      * Each element of the enumeration is of type Binding.
269      * @exception NamingException if a naming exception is encountered
270      */

271     public synchronized NamingEnumeration JavaDoc listBindings(String JavaDoc name)
272         throws NamingException JavaDoc {
273         return this.context.listBindings(name);
274     }
275
276     /**
277      * Destroys the named context and removes it from the namespace. Any
278      * attributes associated with the name are also removed. Intermediate
279      * contexts are not destroyed.
280      * <p>
281      * This method is idempotent. It succeeds even if the terminal atomic
282      * name is not bound in the target context, but throws
283      * NameNotFoundException if any of the intermediate contexts do not exist.
284      *
285      * In a federated naming system, a context from one naming system may be
286      * bound to a name in another. One can subsequently look up and perform
287      * operations on the foreign context using a composite name. However, an
288      * attempt destroy the context using this composite name will fail with
289      * NotContextException, because the foreign context is not a "subcontext"
290      * of the context in which it is bound. Instead, use unbind() to remove
291      * the binding of the foreign context. Destroying the foreign context
292      * requires that the destroySubcontext() be performed on a context from
293      * the foreign context's "native" naming system.
294      *
295      * @param name the name of the context to be destroyed; may not be empty
296      * @exception NameNotFoundException if an intermediate context does not
297      * exist
298      * @exception NotContextException if the name is bound but does not name
299      * a context, or does not name a context of the appropriate type
300      */

301     public synchronized void destroySubcontext(Name JavaDoc name)
302         throws NamingException JavaDoc {
303         this.context.destroySubcontext(name);
304     }
305
306     /**
307      * Destroys the named context and removes it from the namespace.
308      *
309      * @param name the name of the context to be destroyed; may not be empty
310      * @exception NameNotFoundException if an intermediate context does not
311      * exist
312      * @exception NotContextException if the name is bound but does not name
313      * a context, or does not name a context of the appropriate type
314      */

315     public synchronized void destroySubcontext(String JavaDoc name)
316         throws NamingException JavaDoc {
317         this.context.destroySubcontext(name);
318     }
319
320     /**
321      * Creates and binds a new context. Creates a new context with the given
322      * name and binds it in the target context (that named by all but
323      * terminal atomic component of the name). All intermediate contexts and
324      * the target context must already exist.
325      * <p>
326      * Like other methods, this method delegates to the underlying Context
327      * instance. Whether or not the newly created context will be Synchronized
328      * therefore depends on the type of the Context (and the value of its
329      * {@link #SYNCHRONIZED} environment property).
330      *
331      * @param name the name of the context to create; may not be empty
332      * @return the newly created context
333      * @exception NameAlreadyBoundException if name is already bound
334      * @exception InvalidAttributesException if creation of the subcontext
335      * requires specification of mandatory attributes
336      * @exception NamingException if a naming exception is encountered
337      */

338     public synchronized Context JavaDoc createSubcontext(Name JavaDoc name)
339         throws NamingException JavaDoc {
340         return this.context.createSubcontext(name);
341     }
342
343     /**
344      * Creates and binds a new context.
345      * <p>
346      * Like other methods, this method delegates to the underlying Context
347      * instance. Whether or not the newly created context will be Synchronized
348      * therefore depends on the type of the Context (and the value of its
349      * {@link #SYNCHRONIZED} environment property).
350      *
351      * @param name the name of the context to create; may not be empty
352      * @return the newly created context
353      * @exception NameAlreadyBoundException if name is already bound
354      * @exception InvalidAttributesException if creation of the subcontext
355      * requires specification of mandatory attributes
356      * @exception NamingException if a naming exception is encountered
357      */

358     public synchronized Context JavaDoc createSubcontext(String JavaDoc name)
359         throws NamingException JavaDoc {
360         return this.context.createSubcontext(name);
361     }
362
363     /**
364      * Retrieves the named object, following links except for the terminal
365      * atomic component of the name. If the object bound to name is not a
366      * link, returns the object itself.
367      *
368      * @param name the name of the object to look up
369      * @return the object bound to name, not following the terminal link
370      * (if any).
371      * @exception NamingException if a naming exception is encountered
372      */

373     public synchronized Object JavaDoc lookupLink(Name JavaDoc name)
374         throws NamingException JavaDoc {
375         return this.context.lookupLink(name);
376     }
377
378     /**
379      * Retrieves the named object, following links except for the terminal
380      * atomic component of the name.
381      *
382      * @param name the name of the object to look up
383      * @return the object bound to name, not following the terminal link
384      * (if any).
385      * @exception NamingException if a naming exception is encountered
386      */

387     public synchronized Object JavaDoc lookupLink(String JavaDoc name)
388         throws NamingException JavaDoc {
389         return this.context.lookupLink(name);
390     }
391
392     /**
393      * Retrieves the parser associated with the named context. In a
394      * federation of namespaces, different naming systems will parse names
395      * differently. This method allows an application to get a parser for
396      * parsing names into their atomic components using the naming convention
397      * of a particular naming system. Within any single naming system,
398      * NameParser objects returned by this method must be equal (using the
399      * equals() test).
400      *
401      * @param name the name of the context from which to get the parser
402      * @return a name parser that can parse compound names into their atomic
403      * components
404      * @exception NamingException if a naming exception is encountered
405      */

406     public NameParser JavaDoc getNameParser(Name JavaDoc name)
407         throws NamingException JavaDoc {
408         return this.context.getNameParser(name);
409     }
410
411     /**
412      * Retrieves the parser associated with the named context.
413      *
414      * @param name the name of the context from which to get the parser
415      * @return a name parser that can parse compound names into their atomic
416      * components
417      * @exception NamingException if a naming exception is encountered
418      */

419     public NameParser JavaDoc getNameParser(String JavaDoc name)
420         throws NamingException JavaDoc {
421         return this.context.getNameParser(name);
422     }
423
424     /**
425      * Composes the name of this context with a name relative to this context.
426      * <p>
427      * Given a name (name) relative to this context, and the name (prefix)
428      * of this context relative to one of its ancestors, this method returns
429      * the composition of the two names using the syntax appropriate for the
430      * naming system(s) involved. That is, if name names an object relative
431      * to this context, the result is the name of the same object, but
432      * relative to the ancestor context. None of the names may be null.
433      *
434      * @param name a name relative to this context
435      * @param prefix the name of this context relative to one of its ancestors
436      * @return the composition of prefix and name
437      * @exception NamingException if a naming exception is encountered
438      */

439     public Name JavaDoc composeName(Name JavaDoc name, Name JavaDoc prefix)
440         throws NamingException JavaDoc {
441         return this.context.composeName(name, prefix);
442     }
443
444     /**
445      * Composes the name of this context with a name relative to this context.
446      *
447      * @param name a name relative to this context
448      * @param prefix the name of this context relative to one of its ancestors
449      * @return the composition of prefix and name
450      * @exception NamingException if a naming exception is encountered
451      */

452     public String JavaDoc composeName(String JavaDoc name, String JavaDoc prefix)
453         throws NamingException JavaDoc {
454         return this.context.composeName(name, prefix);
455     }
456
457     /**
458      * Adds a new environment property to the environment of this context. If
459      * the property already exists, its value is overwritten.
460      *
461      * @param propName the name of the environment property to add; may not
462      * be null
463      * @param propVal the value of the property to add; may not be null
464      * @exception NamingException if a naming exception is encountered
465      */

466     public Object JavaDoc addToEnvironment(String JavaDoc propName, Object JavaDoc propVal)
467         throws NamingException JavaDoc {
468         return this.context.addToEnvironment(propName, propVal);
469     }
470
471     /**
472      * Removes an environment property from the environment of this context.
473      *
474      * @param propName the name of the environment property to remove;
475      * may not be null
476      * @exception NamingException if a naming exception is encountered
477      */

478     public Object JavaDoc removeFromEnvironment(String JavaDoc propName)
479         throws NamingException JavaDoc {
480         return this.context.removeFromEnvironment(propName);
481     }
482
483     /**
484      * Retrieves the environment in effect for this context. See class
485      * description for more details on environment properties.
486      * The caller should not make any changes to the object returned: their
487      * effect on the context is undefined. The environment of this context
488      * may be changed using addToEnvironment() and removeFromEnvironment().
489      *
490      * @return the environment of this context; never null
491      * @exception NamingException if a naming exception is encountered
492      */

493     public Hashtable JavaDoc getEnvironment()
494         throws NamingException JavaDoc {
495         return this.context.getEnvironment();
496     }
497
498     /**
499      * Closes this context. This method releases this context's resources
500      * immediately, instead of waiting for them to be released automatically
501      * by the garbage collector.
502      * This method is idempotent: invoking it on a context that has already
503      * been closed has no effect. Invoking any other method on a closed
504      * context is not allowed, and results in undefined behaviour.
505      *
506      * @exception NamingException if a naming exception is encountered
507      */

508     public void close()
509         throws NamingException JavaDoc {
510         this.context.close();
511     }
512
513     /**
514      * Retrieves the full name of this context within its own namespace.
515      * <p>
516      * Many naming services have a notion of a "full name" for objects in
517      * their respective namespaces. For example, an LDAP entry has a
518      * distinguished name, and a DNS record has a fully qualified name. This
519      * method allows the client application to retrieve this name. The string
520      * returned by this method is not a JNDI composite name and should not be
521      * passed directly to context methods. In naming systems for which the
522      * notion of full name does not make sense,
523      * OperationNotSupportedException is thrown.
524      *
525      * @return this context's name in its own namespace; never null
526      * @exception OperationNotSupportedException if the naming system does
527      * not have the notion of a full name
528      * @exception NamingException if a naming exception is encountered
529      */

530     public String JavaDoc getNameInNamespace()
531         throws NamingException JavaDoc {
532         return this.context.getNameInNamespace();
533     }
534
535     /**
536      * Determines whether or not the given environment contains a
537      * {@link #SYNCHRONIZED} property with booleanValue true.
538      *
539      * @param environment environment to inspect
540      * @return true if the environment contains a SYNCHRONIZED property
541      * with value "true"
542      */

543     public static boolean isSynchronized(Hashtable JavaDoc environment) {
544         if (environment != null) {
545             Object JavaDoc prop = environment.get(SYNCHRONIZED);
546             if (prop instanceof String JavaDoc) {
547                 return Boolean.valueOf((String JavaDoc)prop).booleanValue();
548             }
549         }
550         return false;
551     }
552
553 }
554
555
Popular Tags