diff options
Diffstat (limited to 'javax/naming/spi/NamingManager.java')
| -rw-r--r-- | javax/naming/spi/NamingManager.java | 394 |
1 files changed, 325 insertions, 69 deletions
diff --git a/javax/naming/spi/NamingManager.java b/javax/naming/spi/NamingManager.java index cfc9dbd5f..a36d519d7 100644 --- a/javax/naming/spi/NamingManager.java +++ b/javax/naming/spi/NamingManager.java @@ -1,5 +1,6 @@ -/* NamingManager.java -- - Copyright (C) 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. +/* NamingManager.java -- Creates contexts and objects + Copyright (C) 2000, 2001, 2002, 2003, 2004, + 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -38,6 +39,8 @@ exception statement from your version. */ package javax.naming.spi; +import gnu.classpath.VMStackWalker; + import java.util.Enumeration; import java.util.Hashtable; import java.util.StringTokenizer; @@ -52,8 +55,19 @@ import javax.naming.Reference; import javax.naming.Referenceable; import javax.naming.StringRefAddr; +/** + * Contains methods for creating contexts and objects referred to by + * location information. The location is specified in the scope of the + * certain naming or directory service. This class only contais static + * methods and cannot be instantiated. + */ public class NamingManager { + /** + * The environment property into which getContinuationContext() stores the + * value of the CannotProceedException parameter. The value of this field + * is <i>java.naming.spi.CannotProceedException<i>. + */ public static final String CPE = "java.naming.spi.CannotProceedException"; private static InitialContextFactoryBuilder icfb; @@ -65,12 +79,37 @@ public class NamingManager NamingManager () { } - + + /** + * Checks if the initial context factory builder has been set. + * + * @return true if the builder has been set + * + * @see #setInitialContextFactoryBuilder(InitialContextFactoryBuilder) + */ public static boolean hasInitialContextFactoryBuilder () { return icfb != null; } + /** + * Creates the initial context. If the initial object factory builder has + * been set with {@link #setObjectFactoryBuilder(ObjectFactoryBuilder)}, + * the work is delegated to this builder. Otherwise, the method searches + * for the property Context.INITIAL_CONTEXT_FACTORY first in the passed + * table and then in the system properties. The value of this property is + * uses as a class name to install the context factory. The corresponding + * class must exist, be public and have the public parameterless constructor. + * + * @param environment the properties, used to create the context. + * + * @return the created context + * + * @throws NoInitialContextException if the initial builder is not set, + * the property Context.INITIAL_CONTEXT_FACTORY is missing of the + * class, named by this property, cannot be instantiated. + * @throws NamingException if throws by the context factory + */ public static Context getInitialContext (Hashtable environment) throws NamingException { @@ -112,77 +151,191 @@ public class NamingManager return icf.getInitialContext (environment); } - - static Context getURLContext (Object refInfo, - Name name, - Context nameCtx, - String scheme, - Hashtable environment) - throws NamingException + + /** + * <p> + * Creates the URL context for the given URL scheme id. + * </p> + * <p> + * The class name of the factory that creates the context has the naming + * pattern scheme-idURLContextFactory. For instance, the factory for the "ftp" + * sheme should be named "ftpURLContextFactory". + * </p> + * <p> + * The Context.URL_PKG_PREFIXES environment property contains the + * colon-separated list of the possible package prefixes. The package name is + * constructed concatenating the package prefix with the scheme id. This + * property is searched in the passed <i>environment</i> parameter and later + * in the system properties. + * </p> + * <p> + * If the factory class cannot be found in the specified packages, system will + * try to use the default internal factory for the given scheme. + * </p> + * <p> + * After the factory is instantiated, its method + * {@link ObjectFactory#getObjectInstance(Object, Name, Context, Hashtable)} + * is called to create and return the object instance. + * + * @param refInfo passed to the factory + * @param name passed to the factory + * @param nameCtx passed to the factory + * @param scheme the url scheme that must be supported by the given context + * @param environment the properties for creating the factory and context (may + * be null) + * @return the created context + * @throws NamingException if thrown by the factory when creating the context. + */ + static Context getURLContext(Object refInfo, Name name, Context nameCtx, + String scheme, Hashtable environment) + throws NamingException { - String prefixes = null; + // Specified as the default in the docs. Unclear if this is + // right for us. + String defaultPrefix = "com.sun.jndi.url"; + + StringBuffer allPrefixes = new StringBuffer(); + + String prefixes; if (environment != null) - prefixes = (String) environment.get (Context.URL_PKG_PREFIXES); - if (prefixes == null) - prefixes = System.getProperty (Context.URL_PKG_PREFIXES); - if (prefixes == null) { - // Specified as the default in the docs. Unclear if this is - // right for us. - prefixes = "com.sun.jndi.url"; + prefixes = (String) environment.get(Context.URL_PKG_PREFIXES); + if (prefixes != null) + allPrefixes.append(prefixes); + } + + prefixes = System.getProperty(Context.URL_PKG_PREFIXES); + if (prefixes != null) + { + if (allPrefixes.length() > 0) + allPrefixes.append(':'); + allPrefixes.append(prefixes); } + if (allPrefixes.length() > 0) + allPrefixes.append(':'); + allPrefixes.append(defaultPrefix); + scheme = scheme + "." + scheme + "URLContextFactory"; - StringTokenizer tokens = new StringTokenizer (prefixes, ":"); - while (tokens.hasMoreTokens ()) + StringTokenizer tokens = new StringTokenizer(allPrefixes.toString(), ":"); + while (tokens.hasMoreTokens()) { - String aTry = tokens.nextToken (); - try - { - Class factoryClass = Class.forName (aTry + "." + scheme, - true, - Thread.currentThread().getContextClassLoader()); - ObjectFactory factory = - (ObjectFactory) factoryClass.newInstance (); - Object obj = factory.getObjectInstance (refInfo, name, - nameCtx, environment); - Context ctx = (Context) obj; - if (ctx != null) - return ctx; - } - catch (ClassNotFoundException _1) - { - // Ignore it. - } - catch (ClassCastException _2) - { - // This means that the class we found was not an - // ObjectFactory or that the factory returned something - // which was not a Context. - } - catch (InstantiationException _3) - { - // If we couldn't instantiate the factory we might get - // this. - } - catch (IllegalAccessException _4) - { - // Another possibility when instantiating. - } - catch (NamingException _5) - { - throw _5; - } - catch (Exception _6) - { - // Anything from getObjectInstance. - } + String aTry = tokens.nextToken(); + try + { + String tryClass = aTry + "." + scheme; + Class factoryClass = forName(tryClass); + if (factoryClass != null) + { + ObjectFactory factory = (ObjectFactory) factoryClass.newInstance(); + Object obj = factory.getObjectInstance(refInfo, name, nameCtx, + environment); + Context ctx = (Context) obj; + if (ctx != null) + return ctx; + } + } + catch (ClassNotFoundException _1) + { + // Ignore it. + } + catch (ClassCastException _2) + { + // This means that the class we found was not an + // ObjectFactory or that the factory returned something + // which was not a Context. + } + catch (InstantiationException _3) + { + // If we couldn't instantiate the factory we might get + // this. + } + catch (IllegalAccessException _4) + { + // Another possibility when instantiating. + } + catch (NamingException _5) + { + throw _5; + } + catch (Exception _6) + { + // Anything from getObjectInstance. + } } return null; } - + + /** + * Load the class with the given name. This method tries to use the context + * class loader first. If this fails, it searches for the suitable class + * loader in the caller stack trace. This method is a central point where all + * requests to find a class by name are delegated. + */ + static Class forName(String className) + { + try + { + return Class.forName(className, true, + Thread.currentThread().getContextClassLoader()); + } + catch (ClassNotFoundException nex) + { + /** + * Returns the first user defined class loader on the call stack, or + * null when no non-null class loader was found. + */ + Class[] ctx = VMStackWalker.getClassContext(); + for (int i = 0; i < ctx.length; i++) + { + // Since we live in a class loaded by the bootstrap + // class loader, getClassLoader is safe to call without + // needing to be wrapped in a privileged action. + ClassLoader cl = ctx[i].getClassLoader(); + try + { + if (cl != null) + return Class.forName(className, true, cl); + } + catch (ClassNotFoundException nex2) + { + // Try next. + } + } + } + return null; + } + + + /** + * <p> + * Creates the URL context for the given URL scheme id. + * </p> + * <p> + * The class name of the factory that creates the context has the naming + * pattern scheme-idURLContextFactory. For instance, the factory for the "ftp" + * sheme should be named "ftpURLContextFactory". The Context.URL_PKG_PREFIXES + * environment property contains the colon-separated list of the possible + * package prefixes. The package name is constructed concatenating the package + * prefix with the scheme id. + * </p> + * <p> + * If the factory class cannot be found in the specified packages, system will + * try to use the default internal factory for the given scheme. + * </p> + * <p> + * After the factory is instantiated, its method + * {@link ObjectFactory#getObjectInstance(Object, Name, Context, Hashtable)} + * is called to create and return the object instance. + * + * @param scheme the url scheme that must be supported by the given context + * @param environment the properties for creating the factory and context (may + * be null) + * @return the created context + * @throws NamingException if thrown by the factory when creating the context. + */ public static Context getURLContext (String scheme, Hashtable environment) throws NamingException @@ -190,6 +343,17 @@ public class NamingManager return getURLContext (null, null, null, scheme, environment); } + /** + * Sets the initial object factory builder. + * + * @param builder the builder to set + * + * @throws SecurityException if the builder cannot be installed due + * security restrictions. + * @throws NamingException if the builder cannot be installed due other + * reasons + * @throws IllegalStateException if setting the builder repeatedly + */ public static void setObjectFactoryBuilder (ObjectFactoryBuilder builder) throws NamingException { @@ -198,7 +362,7 @@ public class NamingManager sm.checkSetFactory (); // Once the builder is installed it cannot be replaced. if (ofb != null) - throw new IllegalStateException ("builder already installed"); + throw new IllegalStateException ("object factory builder already installed"); if (builder != null) ofb = builder; } @@ -217,7 +381,58 @@ public class NamingManager path += ":" + path2; return new StringTokenizer (path != null ? path : "", ":"); } - + + /** + * <p>Creates an object for the specified name context, environment and + * referencing context object.</p> + * <p> + * If the builder factory is set by + * {@link #setObjectFactoryBuilder(ObjectFactoryBuilder)}, the call is + * delegated to that factory. Otherwise, the object is created using the + * following rules: + * <ul> + * <li>If the referencing object (refInfo) contains the factory class name, + * the object is created by this factory. If the creation fails, + * the parameter refInfo is returned as the method return value.</li> + * <li>If the referencing object has no factory class name, and the addresses + * are StringRefAddrs having the address type "URL", the object is + * created by the URL context factory. The used factory corresponds the + * the naming schema of the each URL. If the attempt to create + * the object this way is not successful, the subsequent rule is + * tried.</li> + * <li> If the refInfo is not an instance of Reference or Referencable + * (for example, null), the object is created by the factories, + * specified in the Context.OBJECT_FACTORIES property of the + * environment and the provider resource file, associated with the + * nameCtx. The value of this property is the colon separated list + * of the possible factories. If none of the factories can be + * loaded, the refInfo is returned. + * </ul> + * </p> + * <p>The object factory must be public and have the public parameterless + * constructor.</p> + * + * @param refInfo the referencing object, for which the new object must be + * created (can be null). If not null, it is usually an instance of + * the {@link Reference} or {@link Referenceable}. + * @param name the name of the object. The name is relative to + * the nameCtx naming context. The value of this parameter can be + * null if the name is not specified. + * @param nameCtx the naming context, in which scope the name of the new + * object is specified. If this parameter is null, the name is + * specified in the scope of the initial context. + * @param environment contains additional information for creating the object. + * This paramter can be null if there is no need to provide any + * additional information. + * + * @return the created object. If the creation fails, in some cases + * the parameter refInfo may be returned. + * + * @throws NamingException if the attempt to name the new object has failed + * @throws Exception if the object factory throws it. The object factory + * only throws an exception if it does not want other factories + * to be used to create the object. + */ public static Object getObjectInstance (Object refInfo, Name name, Context nameCtx, @@ -312,7 +527,21 @@ public class NamingManager return obj == null ? refInfo : obj; } - public static void setInitialContextFactoryBuilder (InitialContextFactoryBuilder builder) + /** + * Sets the initial context factory builder. + * + * @param builder the builder to set + * + * @throws SecurityException if the builder cannot be installed due + * security restrictions. + * @throws NamingException if the builder cannot be installed due other + * reasons + * @throws IllegalStateException if setting the builder repeatedly + * + * @see #hasInitialContextFactoryBuilder() + */ + public static void setInitialContextFactoryBuilder + (InitialContextFactoryBuilder builder) throws NamingException { SecurityManager sm = System.getSecurityManager (); @@ -320,11 +549,23 @@ public class NamingManager sm.checkSetFactory (); // Once the builder is installed it cannot be replaced. if (icfb != null) - throw new IllegalStateException ("builder already installed"); + throw new IllegalStateException ("ctx factory builder already installed"); if (builder != null) icfb = builder; } - + + /** + * Creates a context in which the context operation must be continued. + * This method is used by operations on names that span multiple namespaces. + * + * @param cpe the exception that triggered this continuation. This method + * obtains the environment ({@link CannotProceedException#getEnvironment()} + * and sets the environment property {@link #CPE} = cpe. + * + * @return a non null context for continuing the operation + * + * @throws NamingException if the naming problems have occured + */ public static Context getContinuationContext (CannotProceedException cpe) throws NamingException { @@ -332,7 +573,7 @@ public class NamingManager if (env != null) env.put (CPE, cpe); - // It is really unclear to me if this is right. + // TODO: Check if this implementation matches the API specification try { Object obj = getObjectInstance (cpe.getResolvedObj(), @@ -351,7 +592,22 @@ public class NamingManager throw cpe; } - + + /** + * Get the object state for binding. + * + * @param obj the object, for that the binding state must be retrieved. Cannot + * be null. + * @param name the name of this object, related to the nameCtx. Can be null if + * not specified. + * @param nameCtx the naming context, to that the object name is related. Can + * be null if the name is related to the initial default context. + * @param environment the properties for creating the object state. Can be + * null if no properties are provided. + * @return the object state for binding, may be null if no changes are + * returned by the factory + * @throws NamingException + */ public static Object getStateToBind (Object obj, Name name, Context nameCtx, Hashtable environment) throws NamingException |