Save This Page
Home » apache-harmony-6.0-src-r917296-snapshot » javax » naming » [javadoc | source]
javax.naming
public class: InitialContext [javadoc | source]
java.lang.Object
   javax.naming.InitialContext

All Implemented Interfaces:
    Context

Direct Known Subclasses:
    InitialLdapContext, InitialDirContext

An InitialContext object is required as the starting context for any naming operations. Other contexts and subcontexts may be created later. Contexts may consist of different implementations according to the needs of the application. All naming operations are performed relative to a context and names are resolved beginning with the initial context.

When constructing an initial context, environment properties from a range of sources may be used to initialize the environment. See the specification of the Context interface for further details of environment properties.

The environment at runtime determines the initial context implementation. By default, the naming frameworks look for the initial context factory class name in the property Context.INITIAL_CONTEXT_FACTORY. When URL strings must be resolved, a different policy is used which is described below.

A NoInitialContextException is thrown when it cannot create an initial context. The exception may occur not only during constructor invocation, but may occur later. For example, when a subclass of InitialContext uses the lazy initialization option, InitialContext methods may be invoked later which require the initialization to be completed at that time using the init protected method. In these circumstances, NoInitialContextException may be thrown some time after the constructor was invoked. JNDI applications should be written to be independent of when initial context is actually initialized.

If environment property Context.INITIAL_CONTEXT_FACTORY has a non-null value, then the specified initial context factory may experience a problem trying to instantiate an initial context and so throw an exception. It is a responsibility of the service provider implementation as to when an exception is thrown to report the problem to the JNDI application.

URL names comprising a String format described by RFC1738 may be components of names passed to naming operations. Typically, the URL is composed of the "scheme" - such as one of http, ldap, dns - followed by additional text. If the JNDI can identify the URL scheme from the specified name, then it is used to construct a classname suffix in the following form:

           <package_prefix> . <scheme> . <scheme>URLContextFactory
Several variants of the classname are constructed using each element of the Context.URL_PACKAGE_PREFIXES environment property. Note that an additional package prefix - "com.sun.jndi.url" - is always considered to be at the end of those already present in the value of that environment property. Although a service provider may also provide a URL context implementation as well as a context implementation, it is not required to do so, and so an arbitrary service provider might not provide for creating URL contexts.

If a URL context is successfully created for a specified URL scheme, the factory can create contexts for arbitrary URLs of the same scheme. NamingManager.setInitialContextFactoryBuilder may be used to specify an alternate policy for locating factories for initial contexts and URL contexts.

On successful completion of InitialContext initialization, the service provider implementation will have returned an appropriate Context object which can be used for looking up and manipulating names which may or may not be URL names. InitialContext methods other than those dealing with environments should delegate context operations to that Context object.

Field Summary
protected  Context defaultInitCtx    Set to the result of the first successful invocation of NamingManager.getInitialContext by getDefaultInitCtx . Initially null. 
protected  boolean gotDefault    Set to true when NamingManager.getInitialContext has been invoked to obtain an initial context. Initially false. 
protected  Hashtable<Object, Object> myProps    Contains all those JNDI environment properties that were found in any of the the sources of JNDI environment properties. Initially null. 
Constructor:
 public InitialContext() throws NamingException 
    Constructs an InitialContext instance without using any environment properties. This constructor is effectively the same as using constructor InitialContext((Hashtable)null).
    Throws:
    NamingException - If failed to create an InitialContext.
 public InitialContext(Hashtable<?, ?> environment) throws NamingException 
    Constructs an InitialContext instance using environment properties in the supplied parameter which may be null.
    Parameters:
    environment - the JNDI environment properties used to create the context
    Throws:
    NamingException - If failed to create an InitialContext.
 protected InitialContext(boolean doNotInit) throws NamingException 
    Constructs an InitialContext instance by indicating whether a lazy initialization is desired. Effectively, this is the same as using constructor InitialContext() if lazy initialization is not indicated.

    This constructor may be invoked with a parameter value of true and the implementation will defer initialization of the instance. This may be used in an InitialContext subclass constructor in which later action will set up a Hashtable object with appropriate environment properties and pass that to the init method to complete initialization of the InitialContext object.

    Parameters:
    doNotInit - Specifies whether to initialize the new instance.
    Throws:
    NamingException - If failed to create an InitialContext.
Method from javax.naming.InitialContext Summary:
addToEnvironment,   bind,   bind,   close,   composeName,   composeName,   createSubcontext,   createSubcontext,   destroySubcontext,   destroySubcontext,   doLookup,   doLookup,   getDefaultInitCtx,   getEnvironment,   getNameInNamespace,   getNameParser,   getNameParser,   getURLOrDefaultInitCtx,   getURLOrDefaultInitCtx,   init,   list,   list,   listBindings,   listBindings,   lookup,   lookup,   lookupLink,   lookupLink,   rebind,   rebind,   removeFromEnvironment,   rename,   rename,   unbind,   unbind
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from javax.naming.InitialContext Detail:
 public Object addToEnvironment(String propName,
    Object propVal) throws NamingException 
 public  void bind(Name name,
    Object obj) throws NamingException 
 public  void bind(String name,
    Object obj) throws NamingException 
 public  void close() throws NamingException 
 public Name composeName(Name name,
    Name prefix) throws NamingException 
    Combines two names into a composite name according to the syntax for this context. The name prefix is expected to be the name of one or more of the immediate parent contexts of this context, so should be an empty name for an InitialContext. name is a name relative to this context. Neither prefix nor name may be null.
 public String composeName(String name,
    String prefix) throws NamingException 
    Combines two names into a composite name according to the syntax for this context. The name prefix is expected to be the name of one or more of the immediate parent contexts of this context, so should be an empty string for an InitialContext. name is a name relative to this context.
 public Context createSubcontext(Name name) throws NamingException 
 public Context createSubcontext(String name) throws NamingException 
 public  void destroySubcontext(Name name) throws NamingException 
 public  void destroySubcontext(String name) throws NamingException 
 public static T doLookup(Name name) throws NamingException 
    A shortcut method for retrieving the named object by Name. It is equivalent to
       InitialContext icxt = new InitialContext();
       T obj = icxt.lookup();
    

    Returns a new instance of this context when name is empty. The new instance represents the same naming context as this context, but may be accessed/modified independently and concurrently.

 public static T doLookup(String name) throws NamingException 
    A static method that retrieves the named object by String.
 protected Context getDefaultInitCtx() throws NamingException 
    Gets the default underlying Context implementation. If gotDefault is true, returns the value of defaultInitCtx. Otherwise, calls NamingManager.getInitialContext to return an initial context for the current environment into defaultInitCtx, then gotDefault is set true. If the resulting context object is null, a NoInitialContextException is thrown, otherwise the value of defaultInitCtx is returned.
 public Hashtable<?, ?> getEnvironment() throws NamingException 
 public String getNameInNamespace() throws NamingException 
 public NameParser getNameParser(Name name) throws NamingException 
 public NameParser getNameParser(String name) throws NamingException 
 protected Context getURLOrDefaultInitCtx(Name name) throws NamingException 
    Returns a non-null context for the specified name of Name representation.

    If an initial context factory builder has been defined, then the specified Name parameter is ignored and the result of getDefaultInitCtx is returned. Otherwise, if the first component of the name is not a URL string, then it returns the result of invoking getDefaultInitCtx. Otherwise, it attempts to return a URL context javax.naming.spi.NamingManager#getURLContext(String, Hashtable) , but if unsuccessful, returns the result of invoking getDefaultInitCtx.

 protected Context getURLOrDefaultInitCtx(String name) throws NamingException 
    Returns a non-null context for the specified name of string representation.

    If an initial context factory builder has been defined, then the specified name parameter is ignored and the result of getDefaultInitCtx is returned. Otherwise, if the name is not a URL string, then it returns the result of invoking getDefaultInitCtx . Otherwise, it attempts to return a URL context javax.naming.spi.NamingManager#getURLContext(String, Hashtable) , but if unsuccessful, returns the result of invoking getDefaultInitCtx.

 protected  void init(Hashtable<?, ?> env) throws NamingException 
    Uses the specified environment parameter together with other JNDI properties to initialize this InitialContext object. The myProps field will be filled with found JNDI properties. If JNDI standard property "java.naming.factory.initial" has a non-null value, then getDefaultInitCtx is invoked to try to initialize fields gotDefault and defaultInitCtx of the InitialContext object.
 public NamingEnumeration<NameClassPair> list(Name name) throws NamingException 
 public NamingEnumeration<NameClassPair> list(String name) throws NamingException 
 public NamingEnumeration<Binding> listBindings(Name name) throws NamingException 
 public NamingEnumeration<Binding> listBindings(String name) throws NamingException 
 public Object lookup(Name name) throws NamingException 
 public Object lookup(String name) throws NamingException 
 public Object lookupLink(Name name) throws NamingException 
 public Object lookupLink(String name) throws NamingException 
 public  void rebind(Name name,
    Object obj) throws NamingException 
 public  void rebind(String name,
    Object obj) throws NamingException 
 public Object removeFromEnvironment(String propName) throws NamingException 
 public  void rename(Name oldName,
    Name newName) throws NamingException 
 public  void rename(String oldName,
    String newName) throws NamingException 
 public  void unbind(Name name) throws NamingException 
 public  void unbind(String name) throws NamingException