Java Doc for NamingManager.java in  » Apache-Harmony-Java-SE » javax-package » javax » naming » spi » Java Source Code / Java DocumentationJava Source Code and Java Documentation

The methods are used by service providers for accessing object and state factories and for determining continuation contexts. Many of the methods create objects. These may be Context objects or objects referred to by the naming service.

The Name and Hashtable arguments passed to the NamingManager methods remain owned purely by the calling method. They must not be changed or referenced.

It should be noted that it is possible for an application to access a namespace other than that supplied by the default InitialContext (as specified by Context.INITIAL_CONTEXT_FACTORY). It is possible to call the following InitialContext methods passing a URL string either as the String or Name parameter: lookup, bin, rebind, unbind, rename, list, listBindings, destroySubcontext, createSubcontext, lookupLink, getNameParser. This allows you to have one InitialContext object where these methods usually use the default initial context but access a URL Context instead when invoked with a URL string.

A URL string is of the format abc:\nnnnnn where abc is the scheme of the URL. (See InitialContext where it refers to RFC1738.) When a URL string is supplied to those InitialContext methods, a URL context is used instead of the default initial context when performing that method. URL context factories are used to create URL contexts. A URL context factory is really just a service provider's implementation of an ObjectFactory. It is not essential that a service provider supplies one if they do not wish to support URL Contexts.

See the getURLContext method for a description of how a URL context factory is located.

Please note that multithreaded access to this class must be safe. For example, for thread safety, it should not be possible for one thread to read the installed InitialContextFactoryBuilder or ObjectFactoryBuilder while another thread is in the process of setting it.

Also note that privileges should be granted to get the context classloader and to read the resource files.

An installed ObjectFactoryBuilder can generate a factory which can be used to create the object instance to return to caller.

The Context.STATE_FACTORIES property from the Hashtable h together with the Context.STATE_FACTORIES property from the provider resource file of the Context c provides the list of factories tried to get an object's state.

Each factory in the list is attempted to be loaded using the context class loader.

If the resolved object is not already a Context then it is necessary to use the resolved object together with the altName name, the altNameCtx context and the environment hashtable to get an instance of the object. This should then be a context which is returned as the continuation context. If an instance cannot be obtained then throw the supplied CannotProceedException using the stack details from this thread.

This method is responsible for setting the property denoted by the CPE string to be the supplied CannotProceedException for the exception e environment. The continuation context should then inherit this property.

An installed ObjectFactoryBuilder can generate a factory which can be used to create the object instance to return to caller. Any encountered exceptions are thrown.

If an ObjectFactoryBuilder has not been installed then the supplied Object o may provide a Reference or Referenceable object. If so, then that Object o may have an associated class in a factory which could be loaded and used to create the object instance. If the factory class cannot be loaded then the URLClassLoader may be able to load a class from the list of URLs specified in the reference's factory class location. Any exceptions encountered are passed up.

If a reference is supplied but no factory class can be loaded from it then this method returns the supplied object o.

If a factory class loads successfully and can then be used to create an object instance then that instance is returned to the caller.

If no factory name was associated with the Reference object o then see whether the Reference or Referenceable object has any StringRefAddrs of address type URL or url in its address list. For each entry in the list, in the order they appear in the list, it may be possible to use the URL factory to create the object. A URL in a StringRefAddr should have a scheme which can be used to locate the associated URL context factory in the same way as in the getURLContext method. (The scheme is the part which comes before :\. For example the URL http://www.apache.org has the scheme http.) A URL with no scheme would be ignored for these purposes.

If no ObjectFactoryBuilder was installed, no factory class name is supplied with a Reference and no URL contexts succeeded in creating an Object then try the factories in Context.OBJECT_FACTORIES for this environment. Also try the provider resource file belonging to the context c. (See Context description for details of Provider resource files.) If any factory throws an exception then pass that back to the caller - no further factories are tried.

If all factories fail to load or create the Object then return the argument object o as the returned object.

The Context.STATE_FACTORIES property from the Hashtable h together with the Context.STATE_FACTORIES property from the provider resource file of the Context c provides the list of factories tried to get an object's state.

Each factory in the list is attempted to be loaded using the context class loader. Once a class is loaded then it can be used to create a new instance of it to obtain the factory which can then use its getStateToBind to find the return object. Once an object is found then it is not necessary to examine further factories and the object is returned it as the return parameter.

If no factory is loaded or all loaded factories fail to return an object then return the supplied Object o as the return param.

Note for service provider implementors: Classes which implement the StateFactory interface must be public with a public constructor that has no parameters.

This getURLContext method tries to locate the URLContextFactory based on the Context.URL_PKG_PREFIXES property which contains the prefixes to be tried as the start of the package name. (See Context).

Each package prefix entry (and finally the default value) are tried to find the class which can be used to create the Context.

A full class name is derived as packageprefix.s.sURLContextFactory where s is the scheme.

For example if a scheme is abc and the package prefix to try is com.ibm then the factory class to try is com.ibm.abc.abcURLContextFactory. Once a factory is created then a Context is created using the special use of ObjectFactory.getObjectInstance.

Once a first factory is created, it is used to create the context, and NO further attempts will be made on other pkg prefixes.