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
+ * [EMAIL PROTECTED]
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>[EMAIL PROTECTED] #bindContext(Object,Context)},
+ * [EMAIL PROTECTED] #bindContext(Object,Context,Object)}</td>
+ * <td>[EMAIL PROTECTED] #getContext(Object)}</td></tr>
+ * <tr><td>Thread</td><td>NamingContext</td>
+ * <td>[EMAIL PROTECTED] #bindThread(Object)},
+ * [EMAIL PROTECTED] #bindThread(Object, Object)}</td>
+ * <td>[EMAIL PROTECTED] #getThread()}</td></tr>
+ * <tr><td>ClassLoader</td><td>NamingContext</td>
+ * <td>[EMAIL PROTECTED] #bindClassLoader(Object, Object)},
+ * [EMAIL PROTECTED] #bindClassLoader(Object,Object,
ClassLoader)}</td>
+ * <td>[EMAIL PROTECTED] #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
+ * [EMAIL PROTECTED] #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
+ * [EMAIL PROTECTED] #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
+ * [EMAIL PROTECTED] #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
+ * [EMAIL PROTECTED] #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
+ * [EMAIL PROTECTED] #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;
}
-
+
}
