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  ;
21  import javax.naming.Context  ;
22  import javax.naming.Name  ;
23  import javax.naming.NameParser  ;
24  import javax.naming.NamingEnumeration  ;
25  import javax.naming.NamingException  ;
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   {
34  
35      /** Environment property controlling synchronization */
36      public static final String   SYNCHRONIZED = 
37          "org.apache.naming.synchronization";
38  
39      /** Underlying JNDI Context */
40      private Context   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   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   lookup(Name   name)
68          throws NamingException   {
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   lookup(String   name)
80          throws NamingException   {
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   name, Object   obj)
97          throws NamingException   {
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   name, Object   obj)
112         throws NamingException   {
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   name, Object   obj)
132         throws NamingException   {
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   name, Object   obj)
146         throws NamingException   {
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   name)
165         throws NamingException   {
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   name)
178         throws NamingException   {
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   oldName, Name   newName)
194         throws NamingException   {
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   oldName, String   newName)
208         throws NamingException   {
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   list(Name   name)
226         throws NamingException   {
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   list(String   name)
240         throws NamingException   {
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   listBindings(Name   name)
258         throws NamingException   {
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   listBindings(String   name)
272         throws NamingException   {
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   name)
302         throws NamingException   {
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   name)
316         throws NamingException   {
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   createSubcontext(Name   name)
339         throws NamingException   {
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   createSubcontext(String   name)
359         throws NamingException   {
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   lookupLink(Name   name)
374         throws NamingException   {
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   lookupLink(String   name)
388         throws NamingException   {
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   getNameParser(Name   name)
407         throws NamingException   {
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   getNameParser(String   name)
420         throws NamingException   {
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   composeName(Name   name, Name   prefix)
440         throws NamingException   {
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   composeName(String   name, String   prefix)
453         throws NamingException   {
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   addToEnvironment(String   propName, Object   propVal)
467         throws NamingException   {
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   removeFromEnvironment(String   propName)
479         throws NamingException   {
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   getEnvironment()
494         throws NamingException   {
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   {
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   getNameInNamespace()
531         throws NamingException   {
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   environment) {
544         if (environment != null) {
545             Object   prop = environment.get(SYNCHRONIZED);
546             if (prop instanceof String  ) {
547                 return Boolean.valueOf((String  )prop).booleanValue();
548             }
549         }
550         return false;
551     }
552 
553 }
554 
555
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags