All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class javax.naming.spi.NamingManager

java.lang.Object
   |
   +----javax.naming.spi.NamingManager

public class NamingManager
extends Object
The NamingManager class contains methods for creating context objects and objects referred to by location information in the directory. This class is cannot be instantiated. You only perform static methods against it.

The mention of URL in the documentation for this class refers to a URL string as defined by RFC 1738 and its related RFCs. It is any string that conforms to the syntax described therein, and may not always have corresponding support in the java.net.URL class or Web browsers.

NamingManager is safe for concurrent access by multiple threads.


Method Index

 o getContinuationContext(CannotProceedException)
Creates a context in which to continue a context operation.
 o getInitialContext(Hashtable)
Creates an initial context using the specified environment properties.
 o getObjectInstance(Object, Name, Context, Hashtable)
Creates an instance of an object for the specified object and environment.
 o getURLContext(String, Hashtable)
Creates a context for the given URL scheme id.
 o hasInitialContextFactoryBuilder()
Determines whether an initial context factory builder has been set.
 o setInitialContextFactoryBuilder(InitialContextFactoryBuilder)
Sets the InitialContextFactory builder to be builder.
 o setObjectFactoryBuilder(ObjectFactoryBuilder)
The ObjectFactoryBuilder determines the policy used when trying to load object factories.

Methods

 o setObjectFactoryBuilder
 public static synchronized void setObjectFactoryBuilder(ObjectFactoryBuilder builder) throws NamingException
The ObjectFactoryBuilder determines the policy used when trying to load object factories. The default policy is:
  1. If object is a Reference, use information in the reference to load its object factory.
  2. If object is a URL string, try to find a context factory using the URL's scheme id.
  3. Use any object factories specified in the java.naming.factory.object property (an ordered, colon (':') separated factory class names).
See getObjectInstance() and class ObjectFactory for details on this default policy.

setObjectFactoryBuilder() overrides this policy by installing its own 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 to do so. Once installed, the builder cannot be replaced.

Parameters:
builder - The factory builder to install. If null, no builder is installed.
Throws: SecurityException
Factory builder cannot be installed for security reasons.
Throws: NamingException
Factory build cannot be installed for a non-security-related reason.
Throws: IllegalStateException
If a factory has already been installed.
See Also:
getObjectInstance, ObjectFactory, ObjectFactoryBuilder, checkSetFactory
 o getObjectInstance
 public static synchronized Object getObjectInstance(Object refInfo,
                                                     Name name,
                                                     Context nameCtx,
                                                     Hashtable environment) throws Exception
Creates an instance of an object for the specified object and environment.

If an object factory builder has been installed, use it to create a factory for creating the object. Otherwise, the following rules are used to create the object:

  1. If refInfo is a Reference or Referenceable, use information in the reference to create a factory for creating the object and return the object. If a factory cannot be created, return refInfo. Note that in order for classes to be loaded from the URL specified in the reference, a SecurityManager must have been installed. If there is no SecurityManager installed, the classes will not be loaded.
  2. If refInfo is a URL string, or an array of URL strings, use the URL context factory corresponding to the URL's scheme id to create the object (see getURLContext()). If that fails, continue to step 3.
  3. Use the specified object factories in the java.naming.factory.object environment or system property (a colon separated list of factory class names). If both properties exist, the environment property takes precedence. If the object cannot be created, return refInfo.

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.

Parameters:
refInfo - The possibly null object for which to create an object.
name - The name of this object relative to nameCtx. Specifying a name is optional; if it is omitted, name should be null.
nameCtx - The context relative to which the name parameter is specified. If null, name is relative to the default initial context.
environment - The possibly null environment to be used in the creation of the object factory and the object.
Returns:
An object created using refInfo; or refInfo if an object cannot be created using the algorithm described above.
Throws: NamingException
if a naming exception was encountered while attempting to get a URL context, or if one of the factories accessed throws a NamingException.
Throws: Exception
if one of the factories accessed throws an exception. 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 Also:
getURLContext, ObjectFactory, getObjectInstance
 o getURLContext
 public static Context getURLContext(String scheme,
                                     Hashtable environment) throws NamingException
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 java.naming.factory.url.pkgs environment or system property contains a colon-separated list of package prefixes. If both properties exist, the environment property takes precedence. 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 java.naming.factory.url.pkgs property contains "com.widget:com.wiz.jndi", the naming manager would attempt to load the following classes until one is successfully instantiated:

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", ...).

Parameters:
scheme - The non-null scheme-id of the URLs supported by the context.
environment - The possibly null environment properties to be used in the creation of the object factory and the context.
Returns:
A context for resolving URLs with the scheme id scheme; null if the factory for creating the context is not found.
Throws: NamingException
If a naming exception occurs while creating the context.
See Also:
getObjectInstance, getObjectInstance
 o getInitialContext
 public static synchronized Context getInitialContext(Hashtable environment) throws NamingException
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 java.naming.factory.initial system or environment property is used. If both properties exist, the environment property takes precedence.

Parameters:
environment - The possibly null environment properties used when creating the context.
Returns:
An initial context; null if no initial context can be created.
Throws: NoInitialContextException
If java.naming.factory.initial is neither an environment property nor a system property, or the property does exist but names a nonexistent class or a class that cannot be instantiated.
Throws: NamingException
If some other naming exception was encountered.
See Also:
InitialContext, InitialDirContext
 o setInitialContextFactoryBuilder
 public static synchronized void setInitialContextFactoryBuilder(InitialContextFactoryBuilder builder) throws NamingException
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.

Parameters:
builder - The initial context factory builder to install. If null, no builder is set.
Throws: SecurityException
builder cannot be installed for security reasons.
Throws: NamingException
Factory build cannot be installed for a non-security-related reason.
Throws: IllegalStateException
If a builder was previous installed.
See Also:
hasInitialContextFactoryBuilder, checkSetFactory
 o hasInitialContextFactoryBuilder
 public static synchronized boolean hasInitialContextFactoryBuilder()
Determines whether an initial context factory builder has been set.

Returns:
true if an initial context factory builder has been set; false otherwise.
See Also:
setInitialContextFactoryBuilder
 o getContinuationContext
 public static Context getContinuationContext(CannotProceedException cpe) throws NamingException
Creates a context in which to continue a context operation.

Parameters:
cpe - The non-null exception that triggered this continuation.
Returns:
A non-null Context object for continuing context operations.
Throws: NamingException
If a naming exception occurred.

All Packages  Class Hierarchy  This Package  Previous  Next  Index