directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pste...@apache.org
Subject svn commit: rev 46920 - incubator/directory/naming/trunk/core/src/java/org/apache/naming
Date Sun, 19 Sep 2004 21:33:46 GMT
Author: psteitz
Date: Sun Sep 19 14:33:45 2004
New Revision: 46920

Modified:
   incubator/directory/naming/trunk/core/src/java/org/apache/naming/ContextBindings.java
Log:
Javadoc.

Modified: incubator/directory/naming/trunk/core/src/java/org/apache/naming/ContextBindings.java
==============================================================================
--- incubator/directory/naming/trunk/core/src/java/org/apache/naming/ContextBindings.java
(original)
+++ incubator/directory/naming/trunk/core/src/java/org/apache/naming/ContextBindings.java
Sun Sep 19 14:33:45 2004
@@ -22,12 +22,38 @@
 import javax.naming.Context;
 
 /**
- * Handles the associations :
- * <ul>
- * <li>Catalina context name with the NamingContext</li>
- * <li>Calling thread with the NamingContext</li>
- * </ul>
- *
+ * Maintains bindings associating user-defined names, NamingContexts, threads
+ * and classloaders.  User-defined names are bound to contexts using
+ * <code>bindContext.</code>  Threads and classloaders are bound to 
+ * NamingContexts indirectly, using <code>bindXxx</code> methods that take
+ * user-defined context names as parameters.  The currently executing thread
+ * and the context classloaders of the current thread are implicit arguments to
+ * the thread and classloader binding methods -- that is, it is only possible
+ * to bind the current thread and its context classloader. 
+ * <p>
+ * If a context name has a security token associated with it (set using 
+ * {@link ContextAccessController#setSecurityToken(Object,Object)}), this token
+ * must be supplied to bind and unbind methods.
+ * <p>
+ * <table border=1, cellpadding=5>
+ * <tr align=left><th>Key</th><th>Value</th><th>Bind
methods</th><th>Lookup method</th></tr>
+ * <tr><td>User-defined name</td><td>NamingContext</td>
+ *      <td>{@link #bindContext(Object,Context)}, 
+ *              {@link #bindContext(Object,Context,Object)}</td>
+ *      <td>{@link #getContext(Object)}</td></tr>
+ * <tr><td>Thread</td><td>NamingContext</td>
+ *      <td>{@link #bindThread(Object)}, 
+ *              {@link #bindThread(Object, Object)}</td>
+ *      <td>{@link #getThread()}</td></tr>
+ * <tr><td>ClassLoader</td><td>NamingContext</td>
+ *      <td>{@link #bindClassLoader(Object, Object)}, 
+ *              {@link #bindClassLoader(Object,Object, ClassLoader)}</td>
+ *      <td>{@link #getClassLoader()}</td></tr>
+ * </table>
+ * <p>
+ *  Also includes <code>unbind</code> methods and methods for determining
+ *  whether or not classloaders and threads are bound to contexts.   
+ * 
  * @author Remy Maucherat
  * @version $Revision: 1.2 $ $Date: 2003/10/13 08:16:47 $
  */
@@ -79,7 +105,8 @@
 
 
     /**
-     * Binds a context name.
+     * Binds a context name.  Overwrites any existing binding using 
+     * <code>name.</code>
      * 
      * @param name Name of the context
      * @param context Associated naming context instance
@@ -90,11 +117,13 @@
 
 
     /**
-     * Binds a context name.
+     * Binds a context name.  Checks the security token first and does nothing
+     * if the check fails.  Overwrites any existing binding using 
+     * <code>name.</code>
      * 
      * @param name Name of the context
      * @param context Associated naming context instance
-     * @param token Security token
+     * @param token Security token associated with the context
      */
     public static void bindContext(Object name, Context context, 
                                    Object token) {
@@ -104,7 +133,7 @@
 
 
     /**
-     * Unbind context name.
+     * Unbinds a context name.
      * 
      * @param name Name of the context
      */
@@ -114,7 +143,8 @@
 
 
     /**
-     * Unbind context name.
+     * Unbinds a context name.  Checks the security token first and does nothing
+     * if the check fails.
      * 
      * @param name Name of the context
      * @param token Security token
@@ -126,9 +156,11 @@
 
 
     /**
-     * Retrieve a naming context.
+     * Retrieves a naming context.  Returns <code>null</code> if there is no
+     * context associated with <code>name.</code>
      * 
      * @param name Name of the context
+     * @return the context bound to the name
      */
     static Context getContext(Object name) {
         return (Context) contextNameBindings.get(name);
@@ -136,9 +168,16 @@
 
 
     /**
-     * Binds a naming context to a thread.
+     * Binds a naming context to the currently executing thread.  The 
+     * <code>name</code> must have been previously bound to a 
+     * <code>NamingContext</code> using 
+     * {@link #bindContext(Object, Context)}; otherwise a 
+     * <code>NamingException</code> is thrown.   Overwrites any existing
+     * binding for the currently executing thread.
      * 
      * @param name Name of the context
+     * @throws NamingException  if <code>name</code> is not bound
+     *  to a context
      */
     public static void bindThread(Object name) 
         throws NamingException {
@@ -147,10 +186,18 @@
 
 
     /**
-     * Binds a naming context to a thread.
+     * Binds a naming context to the currently executing thread.  The 
+     * <code>name</code> must have been previously bound to a 
+     * <code>NamingContext</code> using 
+     * {@link #bindContext(Object, Context, Object)}; otherwise a 
+     * <code>NamingException</code> is thrown.  Checks the security token first
+     * and does nothing if the check fails. Overwrites any existing
+     * binding for the currently executing thread.
      * 
      * @param name Name of the context
      * @param token Security token
+     * @throws NamingException  if <code>name</code> is not bound
+     *  to a context
      */
     public static void bindThread(Object name, Object token) 
         throws NamingException {
@@ -166,7 +213,8 @@
 
 
     /**
-     * Unbinds a naming context to a thread.
+     * Unbinds a naming context from the currently executing thread.  
+     * Does nothing if <code>name</code> is not bound to a context.
      * 
      * @param name Name of the context
      */
@@ -176,7 +224,9 @@
 
 
     /**
-     * Unbinds a naming context to a thread.
+     * Unbinds a naming context from the currently executing thread.  Checks
+     * the security token first and does nothing if the check fails or if
+     * <code>name</code> is not bound to a context. 
      * 
      * @param name Name of the context
      * @param token Security token
@@ -190,7 +240,13 @@
 
 
     /**
-     * Retrieves the naming context bound to a thread.
+     * Retrieves the naming context bound to the currently executing thread. 
+     * Throws a <code>NamingException</code> if the current thread is not bound
+     * to a context.
+     * 
+     * @return  context bound to the current thread
+     * @throws NamingException if the current thread is not bound
+     * @see #bindThread(Object)
      */
     public static Context getThread()
         throws NamingException {
@@ -204,7 +260,14 @@
 
 
     /**
-     * Retrieves the naming context name bound to a thread.
+     * Retrieves the (user-defined) name of the naming context bound to the
+     * currently executing thread. Throws a <code>NamingException</code> if the
+     * current thread is not bound to a context.
+     * 
+     * @return  name of context bound to the current thread
+     * @throws NamingException if the current thread is not bound
+     * @see #bindThread(Object)
+     * @see #bindContext(Object, Context)
      */
     static Object getThreadName()
         throws NamingException {
@@ -218,6 +281,8 @@
 
     /**
      * Tests if current thread is bound to a context.
+     * 
+     * @return true if the current thread is bound
      */
     public static boolean isThreadBound() {
         return (threadBindings.containsKey(Thread.currentThread()));
@@ -225,9 +290,21 @@
 
 
     /**
-     * Binds a naming context to a class loader.
+     * Binds a naming context to the context ClassLoader for the currently
+     * executing thread.  The <code>name</code> must have been previously
+     * bound to a <code>NamingContext</code> using 
+     * {@link #bindContext(Object, Context, Object)}; otherwise a 
+     * <code>NamingException</code> is thrown. 
+     * <p>
+     * Note:  this method does <strong>not</strong> overwrite existing bindings.
+     * If the ClassLoader is already bound to a context, activating this method
+     * with a new context name does nothing.
      * 
      * @param name Name of the context
+     * @throws NamingException if the current thread is not bound
+     * @throws SecurityException if a security manager exists and its 
+     * <code>checkPermission</code> method doesn't allow getting the context
+     * ClassLoader
      */
     public static void bindClassLoader(Object name) 
         throws NamingException {
@@ -236,10 +313,23 @@
 
 
     /**
-     * Binds a naming context to a thread.
-     * 
-     * @param name Name of the context
-     * @param token Security token
+     * Binds a naming context to the context ClassLoader for the currently
+     * executing thread.  The <code>name</code> must have been previously
+     * bound to a <code>NamingContext</code> using 
+     * {@link #bindContext(Object, Context, Object)}; otherwise a 
+     * <code>NamingException</code> is thrown.   Checks the security token
+     * and does nothing if the check fails.
+     * <p>
+     * Note:  this method does <strong>not</strong> overwrite existing bindings.
+     * If the ClassLoader is already bound to a context, activating this method
+     * with a new context name does nothing.
+     * 
+     * @param name Name of the context
+     * @param token Security token associated with the name
+     * @throws NamingException if the current thread is not bound
+     * @throws SecurityException if a security manager exists and its 
+     * <code>checkPermission</code> method doesn't allow getting the context
+     * ClassLoader
      */
     public static void bindClassLoader(Object name, Object token) 
         throws NamingException {
@@ -249,10 +339,20 @@
 
 
     /**
-     * Binds a naming context to a thread.
+     * Binds a naming context to a ClassLoader.  The <code>name</code>
+     * must have been previously bound to a <code>NamingContext</code> using

+     * {@link #bindContext(Object, Context, Object)}; otherwise a 
+     * <code>NamingException</code> is thrown.   Checks the security token
+     * and does nothing if the check fails.
+     * <p>
+     * Note:  this method does <strong>not</strong> overwrite existing bindings.
+     * If the ClassLoader is already bound to a context, activating this method
+     * with a new context name does nothing.
      * 
      * @param name Name of the context
      * @param token Security token
+     * @param classLoader  ClassLoader to bind
+     * @throws NamingException if the name is not bound to a context
      */
     public static void bindClassLoader(Object name, Object token, 
                                        ClassLoader classLoader) 
@@ -273,9 +373,13 @@
 
 
     /**
-     * Unbinds a naming context to a class loader.
+     * Unbinds a naming context from the context ClassLoader for the currently
+     * executing thread.
      * 
      * @param name Name of the context
+     * @throws SecurityException if a security manager exists and its 
+     * <code>checkPermission</code> method doesn't allow getting the context
+     * ClassLoader
      */
     public static void unbindClassLoader(Object name) {
         unbindClassLoader(name, null);
@@ -283,10 +387,15 @@
 
 
     /**
-     * Unbinds a naming context to a class loader.
+     * Unbinds a naming context from the context ClassLoader for the currently
+     * executing thread.  Checks the security token first and does nothing
+     * if the check fails.
      * 
      * @param name Name of the context
      * @param token Security token
+     * @throws SecurityException if a security manager exists and its 
+     * <code>checkPermission</code> method doesn't allow getting the context
+     * ClassLoader
      */
     public static void unbindClassLoader(Object name, Object token) {
         unbindClassLoader(name, token, 
@@ -295,10 +404,12 @@
 
 
     /**
-     * Unbinds a naming context to a class loader.
+     * Unbinds a naming context from a class loader.  Checks the security
+     * token first and does nothing if the check fails.
      * 
      * @param name Name of the context
      * @param token Security token
+     * @param classLoader ClassLoader to unbind
      */
     public static void unbindClassLoader(Object name, Object token, 
                                          ClassLoader classLoader) {
@@ -314,7 +425,18 @@
 
 
     /**
-     * Retrieves the naming context bound to a class loader.
+     * Retrieves the naming context bound to the context ClassLoader for
+     * the currently executing thread, if that ClassLoader is bound.  If the
+     * context ClassLoader is not bound, the ClassLoader bindings table is
+     * queried for parent ClassLoaders, moving up the hierarchy until a bound
+     * ClassLoader is found.  Throws a <code>NamingException</code>
+     * if no ClassLoader in the hierarchy is bound to a context.
+     * 
+     * @return  context bound to the first bound ClassLoader found
+     * @throws NamingException if no bound ClassLoader is found
+     * @throws SecurityException if a security manager exists and its 
+     * <code>checkPermission</code> blocks access to a ClassLoader
+     * @see #bindClassLoader(Object)
      */
     public static Context getClassLoader()
         throws NamingException {
@@ -332,7 +454,19 @@
 
 
     /**
-     * Retrieves the naming context name bound to a class loader.
+     * Retrieves the (user-defined) name of the context bound to the context
+     * ClassLoader for the currently executing thread, if that ClassLoader
+     * is bound.  If the context ClassLoader is not bound, the ClassLoader
+     * bindings table is queried for parent ClassLoaders, moving up the
+     * hierarchy until a bound ClassLoader is found.  Throws a 
+     * <code>NamingException</code> if no ClassLoader in the hierarchy
+     * is bound to a context.
+     * 
+     * @return name of context bound to the first bound ClassLoader found
+     * @throws NamingException if no bound ClassLoader is found
+     * @throws SecurityException if a security manager exists and its 
+     * <code>checkPermission</code> blocks access to a ClassLoader
+     * @see #bindClassLoader(Object)
      */
     static Object getClassLoaderName()
         throws NamingException {
@@ -351,6 +485,8 @@
 
     /**
      * Tests if current class loader is bound to a context.
+     * 
+     * @return true if the context ClassLoader for the current thread is bound
      */
     public static boolean isClassLoaderBound() {
         ClassLoader cl = Thread.currentThread().getContextClassLoader();
@@ -361,7 +497,7 @@
         } while ((cl = cl.getParent()) != null);
         return false;
     }
-
+    
 
 }
 

Mime
View raw message