File	Doc	Category	Size	Date	Package
NamingManager.java	API Doc	Java SE 5 API	32187	Fri Aug 26 14:57:42 BST 2005	javax.naming.spi

NamingManager

• java.lang.Object

Fields Summary
static final VersionHelper	helper
private static ObjectFactoryBuilder	object_factory_builder Package-private; used by DirectoryManager and NamingManager.
private static final String	defaultPkgPrefix
private static InitialContextFactoryBuilder	initctx_factory_builder
public static final String	CPE Constant that holds the name of the environment property into which getContinuationContext() stores the value of its CannotProceedException parameter. This property is inherited by the continuation context, and may be used by that context's service provider to inspect the fields of the exception. The value of this constant is "java.naming.spi.CannotProceedException".

Constructors Summary
NamingManager()

Methods Summary
private static java.lang.Object	createObjectFromFactories(java.lang.Object obj, javax.naming.Name name, javax.naming.Context nameCtx, java.util.Hashtable environment) Creates an object using the factories specified in the Context.OBJECT_FACTORIES property of the environment or of the provider resource file associated with nameCtx. return factory created; null if cannot create FactoryEnumeration factories = ResourceManager.getFactories( Context.OBJECT_FACTORIES, environment, nameCtx); if (factories == null) return null; // Try each factory until one succeeds ObjectFactory factory; Object answer = null; while (answer == null && factories.hasMore()) { factory = (ObjectFactory)factories.next(); answer = factory.getObjectInstance(obj, name, nameCtx, environment); } return answer;
static javax.naming.Context	getContext(java.lang.Object obj, javax.naming.Name name, javax.naming.Context nameCtx, java.util.Hashtable environment) Retrieves a context identified by obj, using the specified environment. Used by ContinuationContext. param obj The object identifying the context. param name The name of the context being returned, relative to nameCtx, or null if no name is being specified. See the getObjectInstance method for details. param ctx The context relative to which name is specified, or null for the default initial context. See the getObjectInstance method for details. param environment Environment specifying characteristics of the resulting context. return A context identified by obj. see #getObjectInstance Object answer; if (obj instanceof Context) { // %%% Ignore environment for now. OK since method not public. return (Context)obj; } try { answer = getObjectInstance(obj, name, nameCtx, environment); } catch (NamingException e) { throw e; } catch (Exception e) { NamingException ne = new NamingException(); ne.setRootCause(e); throw ne; } return (answer instanceof Context) ? (Context)answer : null;
public static javax.naming.Context	getContinuationContext(javax.naming.CannotProceedException cpe) Creates a context in which to continue a context operation. In performing an operation on a name that spans multiple namespaces, a context from one naming system may need to pass the operation on to the next naming system. The context implementation does this by first constructing a CannotProceedException containing information pinpointing how far it has proceeded. It then obtains a continuation context from JNDI by calling getContinuationContext. The context implementation should then resume the context operation by invoking the same operation on the continuation context, using the remainder of the name that has not yet been resolved. Before making use of the cpe parameter, this method updates the environment associated with that object by setting the value of the property CPE to cpe. This property will be inherited by the continuation context, and may be used by that context's service provider to inspect the fields of this exception. param cpe The non-null exception that triggered this continuation. return A non-null Context object for continuing the operation. exception NamingException If a naming exception occurred. Hashtable env = cpe.getEnvironment(); if (env == null) { env = new Hashtable(7); } else { // Make a (shallow) copy of the environment. env = (Hashtable) env.clone(); } env.put(CPE, cpe); ContinuationContext cctx = new ContinuationContext(cpe, env); return cctx.getTargetContext();
public static javax.naming.Context	getInitialContext(java.util.Hashtable env) Creates an initial context using the specified environment properties. If an InitialContextFactoryBuilder has been installed, it is used to create the factory for creating the initial context. Otherwise, the class specified in the Context.INITIAL_CONTEXT_FACTORY environment property is used. Note that an initial context factory (an object that implements the InitialContextFactory interface) must be public and must have a public constructor that accepts no arguments. param env The possibly null environment properties used when creating the context. return A non-null initial context. exception NoInitialContextException If the Context.INITIAL_CONTEXT_FACTORY property is not found or names a nonexistent class or a class that cannot be instantiated, or if the initial context could not be created for some other reason. exception NamingException If some other naming exception was encountered. see javax.naming.InitialContext see javax.naming.directory.InitialDirContext InitialContextFactory factory; InitialContextFactoryBuilder builder = getInitialContextFactoryBuilder(); if (builder == null) { // No factory installed, use property // Get initial context factory class name String className = env != null ? (String)env.get(Context.INITIAL_CONTEXT_FACTORY) : null; if (className == null) { NoInitialContextException ne = new NoInitialContextException( "Need to specify class name in environment or system " + "property, or as an applet parameter, or in an " + "application resource file: " + Context.INITIAL_CONTEXT_FACTORY); throw ne; } try { factory = (InitialContextFactory) helper.loadClass(className).newInstance(); } catch(Exception e) { NoInitialContextException ne = new NoInitialContextException( "Cannot instantiate class: " + className); ne.setRootCause(e); throw ne; } } else { factory = builder.createInitialContextFactory(env); } return factory.getInitialContext(env);
private static synchronized javax.naming.spi.InitialContextFactoryBuilder	getInitialContextFactoryBuilder() Use this method for accessing initctx_factory_builder while inside an unsynchronized method. return initctx_factory_builder;
static synchronized javax.naming.spi.ObjectFactoryBuilder	getObjectFactoryBuilder() Used for accessing object factory builder. return object_factory_builder;
static javax.naming.spi.ObjectFactory	getObjectFactoryFromReference(javax.naming.Reference ref, java.lang.String factoryName) Retrieves the ObjectFactory for the object identified by a reference, using the reference's factory class name and factory codebase to load in the factory's class. param ref The non-null reference to use. param factoryName The non-null class name of the factory. return The object factory for the object identified by ref; null if unable to load the factory. Class clas = null; // Try to use current class loader try { clas = helper.loadClass(factoryName); } catch (ClassNotFoundException e) { // ignore and continue // e.printStackTrace(); } // All other exceptions are passed up. // Not in class path; try to use codebase String codebase; if (clas == null && (codebase = ref.getFactoryClassLocation()) != null) { try { clas = helper.loadClass(factoryName, codebase); } catch (ClassNotFoundException e) { } } return (clas != null) ? (ObjectFactory) clas.newInstance() : null;
public static java.lang.Object	getObjectInstance(java.lang.Object refInfo, javax.naming.Name name, javax.naming.Context nameCtx, java.util.Hashtable environment) Creates an instance of an object for the specified object and environment. If an object factory builder has been installed, it is used to create a factory for creating the object. Otherwise, the following rules are used to create the object: If refInfo is a Reference or Referenceable containing a factory class name, use the named factory to create the object. Return refInfo if the factory cannot be created. Under JDK 1.1, if the factory class must be loaded from a location specified in the reference, a SecurityManager must have been installed or the factory creation will fail. If an exception is encountered while creating the factory, it is passed up to the caller. If refInfo is a Reference or Referenceable with no factory class name, and the address or addresses are StringRefAddrs with address type "URL", try the URL context factory corresponding to each URL's scheme id to create the object (see getURLContext()). If that fails, continue to the next step. Use the object factories specified in the Context.OBJECT_FACTORIES property of the environment, and of the provider resource file associated with nameCtx, in that order. The value of this property is a colon-separated list of factory class names that are tried in order, and the first one that succeeds in creating an object is the one used. If none of the factories can be loaded, return refInfo. If an exception is encountered while creating the object, the exception is passed up to the caller. Service providers that implement the DirContext interface should use DirectoryManager.getObjectInstance(), not this method. Service providers that implement only the Context interface should use this method. Note that an object factory (an object that implements the ObjectFactory interface) must be public and must have a public constructor that accepts no arguments. The name and nameCtx parameters may optionally be used to specify the name of the object being created. name is the name of the object, relative to context nameCtx. This information could be useful to the object factory or to the object implementation. If there are several possible contexts from which the object could be named -- as will often be the case -- it is up to the caller to select one. A good rule of thumb is to select the "deepest" context available. If nameCtx is null, name is relative to the default initial context. If no name is being specified, the name parameter should be null. param refInfo The possibly null object for which to create an object. param name The name of this object relative to nameCtx. Specifying a name is optional; if it is omitted, name should be null. param nameCtx The context relative to which the name parameter is specified. If null, name is relative to the default initial context. param environment The possibly null environment to be used in the creation of the object factory and the object. return An object created using refInfo; or refInfo if an object cannot be created using the algorithm described above. exception NamingException if a naming exception was encountered while attempting to get a URL context, or if one of the factories accessed throws a NamingException. exception Exception if one of the factories accessed throws an exception, or if an error was encountered while loading and instantiating the factory and object classes. A factory should only throw an exception if it does not want other factories to be used in an attempt to create an object. See ObjectFactory.getObjectInstance(). see #getURLContext see ObjectFactory see ObjectFactory#getObjectInstance ObjectFactory factory; // Use builder if installed ObjectFactoryBuilder builder = getObjectFactoryBuilder(); if (builder != null) { // builder must return non-null factory factory = builder.createObjectFactory(refInfo, environment); return factory.getObjectInstance(refInfo, name, nameCtx, environment); } // Use reference if possible Reference ref = null; if (refInfo instanceof Reference) { ref = (Reference) refInfo; } else if (refInfo instanceof Referenceable) { ref = ((Referenceable)(refInfo)).getReference(); } Object answer; if (ref != null) { String f = ref.getFactoryClassName(); if (f != null) { // if reference identifies a factory, use exclusively factory = getObjectFactoryFromReference(ref, f); if (factory != null) { return factory.getObjectInstance(ref, name, nameCtx, environment); } // No factory found, so return original refInfo. // Will reach this point if factory class is not in // class path and reference does not contain a URL for it return refInfo; } else { // if reference has no factory, check for addresses // containing URLs answer = processURLAddrs(ref, name, nameCtx, environment); if (answer != null) { return answer; } } } // try using any specified factories answer = createObjectFromFactories(refInfo, name, nameCtx, environment); return (answer != null) ? answer : refInfo;
static javax.naming.spi.Resolver	getResolver(java.lang.Object obj, javax.naming.Name name, javax.naming.Context nameCtx, java.util.Hashtable environment) Object answer; if (obj instanceof Resolver) { // %%% Ignore environment for now. OK since method not public. return (Resolver)obj; } try { answer = getObjectInstance(obj, name, nameCtx, environment); } catch (NamingException e) { throw e; } catch (Exception e) { NamingException ne = new NamingException(); ne.setRootCause(e); throw ne; } return (answer instanceof Resolver) ? (Resolver)answer : null;
public static java.lang.Object	getStateToBind(java.lang.Object obj, javax.naming.Name name, javax.naming.Context nameCtx, java.util.Hashtable environment) Retrieves the state of an object for binding. Service providers that implement the DirContext interface should use DirectoryManager.getStateToBind(), not this method. Service providers that implement only the Context interface should use this method. This method uses the specified state factories in the Context.STATE_FACTORIES property from the environment properties, and from the provider resource file associated with nameCtx, in that order. The value of this property is a colon-separated list of factory class names that are tried in order, and the first one that succeeds in returning the object's state is the one used. If no object's state can be retrieved in this way, return the object itself. If an exception is encountered while retrieving the state, the exception is passed up to the caller. Note that a state factory (an object that implements the StateFactory interface) must be public and must have a public constructor that accepts no arguments. The name and nameCtx parameters may optionally be used to specify the name of the object being created. See the description of "Name and Context Parameters" in {@link ObjectFactory#getObjectInstance ObjectFactory.getObjectInstance()} for details. This method may return a Referenceable object. The service provider obtaining this object may choose to store it directly, or to extract its reference (using Referenceable.getReference()) and store that instead. param obj The non-null object for which to get state to bind. param name The name of this object relative to nameCtx, or null if no name is specified. param nameCtx The context relative to which the name parameter is specified, or null if name is relative to the default initial context. param environment The possibly null environment to be used in the creation of the state factory and the object's state. return The non-null object representing obj's state for binding. It could be the object (obj) itself. exception NamingException If one of the factories accessed throws an exception, or if an error was encountered while loading and instantiating the factory and object classes. A factory should only throw an exception if it does not want other factories to be used in an attempt to create an object. See StateFactory.getStateToBind(). see StateFactory see StateFactory#getStateToBind see DirectoryManager#getStateToBind since 1.3 FactoryEnumeration factories = ResourceManager.getFactories( Context.STATE_FACTORIES, environment, nameCtx); if (factories == null) { return obj; } // Try each factory until one succeeds StateFactory factory; Object answer = null; while (answer == null && factories.hasMore()) { factory = (StateFactory)factories.next(); answer = factory.getStateToBind(obj, name, nameCtx, environment); } return (answer != null) ? answer : obj;
public static javax.naming.Context	getURLContext(java.lang.String scheme, java.util.Hashtable environment) Creates a context for the given URL scheme id. The resulting context is for resolving URLs of the scheme scheme. The resulting context is not tied to a specific URL. It is able to handle arbitrary URLs with the specified scheme. The class name of the factory that creates the resulting context has the naming convention scheme-idURLContextFactory (e.g. "ftpURLContextFactory" for the "ftp" scheme-id), in the package specified as follows. The Context.URL_PKG_PREFIXES environment property (which may contain values taken from applet parameters, system properties, or application resource files) contains a colon-separated list of package prefixes. Each package prefix in the property is tried in the order specified to load the factory class. The default package prefix is "com.sun.jndi.url" (if none of the specified packages work, this default is tried). The complete package name is constructed using the package prefix, concatenated with the scheme id. For example, if the scheme id is "ldap", and the Context.URL_PKG_PREFIXES property contains "com.widget:com.wiz.jndi", the naming manager would attempt to load the following classes until one is successfully instantiated: com.widget.ldap.ldapURLContextFactory com.wiz.jndi.ldap.ldapURLContextFactory com.sun.jndi.url.ldap.ldapURLContextFactory If none of the package prefixes work, null is returned. If a factory is instantiated, it is invoked with the following parameters to produce the resulting context. factory.getObjectInstance(null, environment); For example, invoking getObjectInstance() as shown above on a LDAP URL context factory would return a context that can resolve LDAP urls (e.g. "ldap://ldap.wiz.com/o=wiz,c=us", "ldap://ldap.umich.edu/o=umich,c=us", ...). Note that an object factory (an object that implements the ObjectFactory interface) must be public and must have a public constructor that accepts no arguments. param scheme The non-null scheme-id of the URLs supported by the context. param environment The possibly null environment properties to be used in the creation of the object factory and the context. return A context for resolving URLs with the scheme id scheme; null if the factory for creating the context is not found. exception NamingException If a naming exception occurs while creating the context. see #getObjectInstance see ObjectFactory#getObjectInstance // pass in 'null' to indicate creation of generic context for scheme // (i.e. not specific to a URL). Object answer = getURLObject(scheme, null, null, null, environment); if (answer instanceof Context) { return (Context)answer; } else { return null; }
private static java.lang.Object	getURLObject(java.lang.String scheme, java.lang.Object urlInfo, javax.naming.Name name, javax.naming.Context nameCtx, java.util.Hashtable environment) Creates an object for the given URL scheme id using the supplied urlInfo. If urlInfo is null, the result is a context for resolving URLs with the scheme id 'scheme'. If urlInfo is a URL, the result is a context named by the URL. Names passed to this context is assumed to be relative to this context (i.e. not a URL). For example, if urlInfo is "ldap://ldap.wiz.com/o=Wiz,c=us", the resulting context will be that pointed to by "o=Wiz,c=us" on the server 'ldap.wiz.com'. Subsequent names that can be passed to this context will be LDAP names relative to this context (e.g. cn="Barbs Jensen"). If urlInfo is an array of URLs, the URLs are assumed to be equivalent in terms of the context to which they refer. The resulting context is like that of the single URL case. If urlInfo is of any other type, that is handled by the context factory for the URL scheme. param scheme the URL scheme id for the context param urlInfo information used to create the context param name name of this object relative to nameCtx param nameCtx Context whose provider resource file will be searched for package prefix values (or null if none) param environment Environment properties for creating the context see javax.naming.InitialContext // e.g. "ftpURLContextFactory" ObjectFactory factory = (ObjectFactory)ResourceManager.getFactory( Context.URL_PKG_PREFIXES, environment, nameCtx, "." + scheme + "." + scheme + "URLContextFactory", defaultPkgPrefix); if (factory == null) return null; // Found object factory try { return factory.getObjectInstance(urlInfo, name, nameCtx, environment); } catch (NamingException e) { throw e; } catch (Exception e) { NamingException ne = new NamingException(); ne.setRootCause(e); throw ne; }
private static java.lang.String	getURLScheme(java.lang.String str) int colon_posn = str.indexOf(':"); int slash_posn = str.indexOf('/"); if (colon_posn > 0 && (slash_posn == -1 || colon_posn < slash_posn)) return str.substring(0, colon_posn); return null;
public static boolean	hasInitialContextFactoryBuilder() Determines whether an initial context factory builder has been set. return true if an initial context factory builder has been set; false otherwise. see #setInitialContextFactoryBuilder return (getInitialContextFactoryBuilder() != null);
private static java.lang.Object	processURL(java.lang.Object refInfo, javax.naming.Name name, javax.naming.Context nameCtx, java.util.Hashtable environment) Object answer; // If refInfo is a URL string, try to use its URL context factory // If no context found, continue to try object factories. if (refInfo instanceof String) { String url = (String)refInfo; String scheme = getURLScheme(url); if (scheme != null) { answer = getURLObject(scheme, refInfo, name, nameCtx, environment); if (answer != null) { return answer; } } } // If refInfo is an array of URL strings, // try to find a context factory for any one of its URLs. // If no context found, continue to try object factories. if (refInfo instanceof String[]) { String[] urls = (String[])refInfo; for (int i = 0; i <urls.length; i++) { String scheme = getURLScheme(urls[i]); if (scheme != null) { answer = getURLObject(scheme, refInfo, name, nameCtx, environment); if (answer != null) return answer; } } } return null;
static java.lang.Object	processURLAddrs(javax.naming.Reference ref, javax.naming.Name name, javax.naming.Context nameCtx, java.util.Hashtable environment) for (int i = 0; i < ref.size(); i++) { RefAddr addr = ref.get(i); if (addr instanceof StringRefAddr && addr.getType().equalsIgnoreCase("URL")) { String url = (String)addr.getContent(); Object answer = processURL(url, name, nameCtx, environment); if (answer != null) { return answer; } } } return null;
public static synchronized void	setInitialContextFactoryBuilder(javax.naming.spi.InitialContextFactoryBuilder builder) Sets the InitialContextFactory builder to be builder. The builder can only be installed if the executing thread is allowed by the security manager to do so. Once installed, the builder cannot be replaced. param builder The initial context factory builder to install. If null, no builder is set. exception SecurityException builder cannot be installed for security reasons. exception NamingException builder cannot be installed for a non-security-related reason. exception IllegalStateException If a builder was previous installed. see #hasInitialContextFactoryBuilder see java.lang.SecurityManager#checkSetFactory if (initctx_factory_builder != null) throw new IllegalStateException( "InitialContextFactoryBuilder already set"); SecurityManager security = System.getSecurityManager(); if (security != null) { security.checkSetFactory(); } initctx_factory_builder = builder;
public static synchronized void	setObjectFactoryBuilder(javax.naming.spi.ObjectFactoryBuilder builder) The ObjectFactoryBuilder determines the policy used when trying to load object factories. See getObjectInstance() and class ObjectFactory for a description of the default policy. setObjectFactoryBuilder() overrides this default policy by installing an ObjectFactoryBuilder. Subsequent object factories will be loaded and created using the installed builder. The builder can only be installed if the executing thread is allowed (by the security manager's checkSetFactory() method) to do so. Once installed, the builder cannot be replaced. param builder The factory builder to install. If null, no builder is installed. exception SecurityException builder cannot be installed for security reasons. exception NamingException builder cannot be installed for a non-security-related reason. exception IllegalStateException If a factory has already been installed. see #getObjectInstance see ObjectFactory see ObjectFactoryBuilder see java.lang.SecurityManager#checkSetFactory if (object_factory_builder != null) throw new IllegalStateException("ObjectFactoryBuilder already set"); SecurityManager security = System.getSecurityManager(); if (security != null) { security.checkSetFactory(); } object_factory_builder = builder;