All Packages Class Hierarchy This Package Previous Next Index
Class javax.naming.InitialContext
java.lang.Object
|
+----javax.naming.InitialContext
- public class InitialContext
- extends Object
- implements Context
All naming operations are relative to a context.
The initial context implements the Context interface and
provides the starting point for resolution of names.
The initial context implementation is determined at runtime.
The default policy uses the environment or system property
"java.naming.factory.initial"
,
which contains the class name of the initial context factory.
(If both are present, the environment property takes precedence).
If a URL string (with syntax scheme_id:rest_of_name) is passed
to methods in InitialContext
, either as a String
argument or as the first component of Name
, the URL's
scheme id is used to locate the context factory for handling that
scheme. If none is found, the initial context specified by
"java.naming.factory.initial"
is used.
See jndi.naming.spi.NamingManager.getURLContext()
for
details on how URL context factories are located.
This default policy of locating the initial context can be overridden
by calling
javax.naming.spi.NamingManager.setInitialContextFactoryBuilder()
.
NoInitialContextException is thrown when an initial context cannot
be instantiated. This exception can be thrown during any interaction
with the InitialContext, not only when the InitialContext is constructed.
For example, the implementation of the initial context might lazily
retrieve the context only when actual methods are invoked on it.
The application should not have any dependency on when the existence
of an initial context is determined.
An InitialContext instance is not synchronized against concurrent
access by multiple threads. Multiple threads each manipulating their
own InitialContext instances need not synchronize.
Threads that need to access a single InitialContext instance
concurrently should synchronize amongst themselves and provide the
necessary locking.
- See Also:
- Context, setInitialContextFactoryBuilder
-
defaultInitCtx
- Field holding the result of calling NamingManager.getInitialContext().
-
gotDefault
- Field indicating whether the initial context has been obtained
by calling NamingManager.getInitialContext().
-
myProps
- The environment associated with this InitialContext.
-
InitialContext()
- Constructs an initial context.
-
InitialContext(Hashtable)
- Constructs an initial context using information supplied in
'environment'.
-
addToEnvironment(String, Object)
- Adds a new environment property to the environment of this
context.
-
bind(Name, Object)
- Binds 'name' to the object 'obj'.
-
bind(String, Object)
- Binds the string name 'name' to the object 'obj'.
-
close()
- Closes this initial context.
-
composeName(Name, Name)
- Composes the name of this context with a name relative to
this context.
-
composeName(String, String)
- Composes the name of this context with a name relative to
this context.
-
createSubcontext(Name)
- Creates and binds a new context.
-
createSubcontext(String)
- Creates and binds a new context.
-
destroySubcontext(Name)
- Destroys the named context and removes it from the namespace.
-
destroySubcontext(String)
- Destroys the named context and removes it from the namespace.
-
getDefaultInitCtx()
- Retrieves the initial context by calling
NamingManager.getInitialContext()
and cache it in defaultInitCtx.
-
getEnvironment()
- Retrieves the environment in effect for the
initial context.
-
getNameParser(Name)
- Retrieves the parser associated with the named context.
-
getNameParser(String)
- Retrieves the parser associated with the named context.
-
getURLOrDefaultInitCtx(Name)
- Retrieves a context for resolving
name
.
-
getURLOrDefaultInitCtx(String)
- Retrieves a context for resolving the string name
name
.
-
list(Name)
- Enumerates the names and the class names of their
bound objects in the context named relative to this initial context.
-
list(String)
- Enumerates the names and the class names of their
bound objects in the context named relative to this initial context.
-
listBindings(Name)
- Enumerates the names and their bound objects in
the context named relative to this initial context.
-
listBindings(String)
- Enumerates the names and their bound objects in
the context named relative to this initial context.
-
lookup(Name)
- Retrieves the object bound to
name
resolved relative to the
initial context.
-
lookup(String)
- Retrieves the object bound to
name
resolved relative to the
initial context.
-
lookupLink(Name)
- Retrieve the object named relative to this initial context,
following links except for the terminal atomic component of name.
-
lookupLink(String)
- Retrieve the object named relative to this initial context,
following links except for the terminal atomic component of name.
-
rebind(Name, Object)
- Binds 'name' to the object 'obj', overwrite any existing binding.
-
rebind(String, Object)
- Binds the string name 'name' to the object 'obj', overwrite any
existing binding.
-
removeFromEnvironment(String)
- Removes an environment property from the environment of this
context.
-
rename(Name, Name)
- Binds 'newName' to the object bound to 'oldName', and unbinds
'oldName'.
-
rename(String, String)
- Binds 'newName' to the object bound to 'oldName', and unbinds
'oldName'.
-
unbind(Name)
- Unbinds 'name' resolved relative to this initial context.
-
unbind(String)
- Unbinds 'name' resolved relative to this initial context.
myProps
protected Hashtable myProps
- The environment associated with this InitialContext.
It is initialized to null and is updated by the constructor
that accepts an environment.
- See Also:
- addToEnvironment, removeFromEnvironment, getEnvironment
defaultInitCtx
protected Context defaultInitCtx
- Field holding the result of calling NamingManager.getInitialContext().
It is set by getDefaultInitCtx() the first time getDefaultInitCtx()
is called. Subsequent invocations of getDefaultInitCtx() return
the value of defaultInitCtx.
- See Also:
- getDefaultInitCtx
gotDefault
protected boolean gotDefault
- Field indicating whether the initial context has been obtained
by calling NamingManager.getInitialContext().
If true, its result is in
defaultInitCtx
.
InitialContext
public InitialContext()
- Constructs an initial context.
The environment of the new context are set to null.
InitialContext
public InitialContext(Hashtable environment)
- Constructs an initial context using information supplied in
'environment'. See the Context class description for more
details about environment.
- Parameters:
- environment - The possibly null environment
used for creating the initial context
(such as user name, password, etc.)
getDefaultInitCtx
protected Context getDefaultInitCtx() throws NamingException
- Retrieves the initial context by calling
NamingManager.getInitialContext()
and cache it in defaultInitCtx.
Set gotDefault
so that we know we've tried this before.
- Returns:
- The non-null cached initial context.
- Throws: NoInitialContextException
- If cannot find an initial context.
- Throws: NamingException
- If a naming exception was encountered.
getURLOrDefaultInitCtx
protected Context getURLOrDefaultInitCtx(String name) throws NamingException
- Retrieves a context for resolving the string name
name
.
If name
name is a URL string, then attempt
to find a URL context for it. If none is found, or if
name
is not a URL string, then return
getDefaultInitCtx()
.
See getURLOrDefaultInitCtx(javax.naming.Name) for description
of how a subclass should use this method.
- Parameters:
- name - The non-null name for which to get the context.
- Returns:
- A URL context for
name
or the cached
initial context. The result cannot be null.
- Throws: NoInitialContextException
- If cannot find an initial context.
- Throws: NamingException
- In a naming exception is encountered.
- See Also:
- getURLContext
getURLOrDefaultInitCtx
protected Context getURLOrDefaultInitCtx(Name name) throws NamingException
- Retrieves a context for resolving
name
.
If the first component of name
name is a URL string,
then attempt to find a URL context for it. If none is found, or if
the first component of name
is not a URL string,
then return getDefaultInitCtx()
.
When creating a subclass of InitialContext, use this method as
follows.
Define a new method that uses this method to get an initial
context of the desired subclass.
protected XXXContext getURLOrDefaultInitXXXCtx(Name name)
throws NamingException {
Context answer = getURLOrDefaultInitCtx(name);
if (!(answer instanceof XXXContext)) {
throw new NoInitialContextException("Not an XXXContext");
}
return (XXXContext)answer;
}
When providing implementations for the new methods in the subclass,
use this newly defined method to get the initial context.
public Object XXXMethod1(Name name, ...) {
throws NamingException {
return getURLOrDefaultInitXXXCtx(name).XXXMethod1(name, ...);
}
- Parameters:
- name - The non-null name for which to get the context.
- Returns:
- A URL context for
name
or the cached
initial context. The result cannot be null.
- Throws: NoInitialContextException
- If cannot find an initial context.
- Throws: NamingException
- In a naming exception is encountered.
- See Also:
- getURLContext
lookup
public Object lookup(String name) throws NamingException
- Retrieves the object bound to
name
resolved relative to the
initial context.
- Parameters:
- name - The non-null string name of the object to lookup.
- Returns:
- The non-null object to which name is bound.
- Throws: NamingException
- If a naming exception was encountered during the lookup.
- See Also:
- lookup
lookup
public Object lookup(Name name) throws NamingException
- Retrieves the object bound to
name
resolved relative to the
initial context.
- Parameters:
- name - The non-null name of the object to lookup.
- Returns:
- The non-null object to which name is bound.
- Throws: NamingException
- If a naming exception was encountered during the lookup.
- See Also:
- lookup
bind
public void bind(String name,
Object obj) throws NamingException
- Binds the string name 'name' to the object 'obj'.
- Parameters:
- name - The non-null name to bind. It cannot be empty.
- obj - The non-null object to bind.
- Throws: NameAlreadyBoundException
- If name is already bound.
- Throws: InvalidAttributesException
- If obj did not supply
all mandatory attributes.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- bind
bind
public void bind(Name name,
Object obj) throws NamingException
- Binds 'name' to the object 'obj'.
- Parameters:
- name - The non-null name to bind. It cannot be empty.
- obj - The non-null object to bind.
- Throws: NameAlreadyBoundException
- If name is already bound.
- Throws: InvalidAttributesException
- If obj did not supply
all mandatory attributes.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- bind
rebind
public void rebind(String name,
Object obj) throws NamingException
- Binds the string name 'name' to the object 'obj', overwrite any
existing binding.
- Parameters:
- name - The non-null name to bind. It cannot be empty.
- obj - The non-null object to bind. If obj is a DirContext,
- Throws: InvalidAttributesException
- If obj did not supply
all mandatory attributes.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- rebind
rebind
public void rebind(Name name,
Object obj) throws NamingException
- Binds 'name' to the object 'obj', overwrite any existing binding.
- Parameters:
- name - The non-null name to bind. It cannot be empty.
- obj - The non-null object to bind. If obj is a DirContext,
- Throws: InvalidAttributesException
- If obj did not supply
all mandatory attributes.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- rebind
unbind
public void unbind(String name) throws NamingException
- Unbinds 'name' resolved relative to this initial context.
- Parameters:
- name - The non-null name to unbind. It cannot be empty.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- unbind
unbind
public void unbind(Name name) throws NamingException
- Unbinds 'name' resolved relative to this initial context.
- Parameters:
- name - The non-null name to unbind. It cannot be empty.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- unbind
rename
public void rename(String oldName,
String newName) throws NamingException
- Binds 'newName' to the object bound to 'oldName', and unbinds
'oldName'.
- Parameters:
- oldName - The non-null name of the existing binding,
- newName - The non-null name of the new binding,
- Throws: NameAlreadyBoundException
- If newName is already bound.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- rename
rename
public void rename(Name oldName,
Name newName) throws NamingException
- Binds 'newName' to the object bound to 'oldName', and unbinds
'oldName'.
- Parameters:
- oldName - The non-null name of the existing binding,
- newName - The non-null name of the new binding,
- Throws: NameAlreadyBoundException
- If newName is already bound.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- rename
list
public NamingEnumeration list(String name) throws NamingException
- Enumerates the names and the class names of their
bound objects in the context named relative to this initial context.
- Parameters:
- name - The non-null name of the context to list.
- Returns:
- A non-null enumeration of the names and class names
(NameClassPair) of the bindings in this context.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- list
list
public NamingEnumeration list(Name name) throws NamingException
- Enumerates the names and the class names of their
bound objects in the context named relative to this initial context.
- Parameters:
- name - The non-null name of the context to list.
- Returns:
- A non-null enumeration of the names and class names
of the bindings (NameClassPair) in this context.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- list
listBindings
public NamingEnumeration listBindings(String name) throws NamingException
- Enumerates the names and their bound objects in
the context named relative to this initial context.
- Parameters:
- name - The non-null name of the context to list.
- Returns:
- A non-null enumeration of the names and their
bound objects (Binding).
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- listBindings
listBindings
public NamingEnumeration listBindings(Name name) throws NamingException
- Enumerates the names and their bound objects in
the context named relative to this initial context.
- Parameters:
- name - The non-null name of the context to list.
- Returns:
- A non-null enumeration of the names and their
bound objects (Binding).
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- listBindings
destroySubcontext
public void destroySubcontext(String name) throws NamingException
- Destroys the named context and removes it from the namespace.
- Parameters:
- name - The non-null name of the context to be destroyed.
- Throws: NameNotFoundException
- If intermediate names not bound.
- Throws: NotContextException
- If name is bound but does not name a context.
- Throws: ContextNotEmptyException
- If named context is not empty.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- destroySubcontext
destroySubcontext
public void destroySubcontext(Name name) throws NamingException
- Destroys the named context and removes it from the namespace.
- Parameters:
- name - The non-null name of the context to be destroyed.
- Throws: NameNotFoundException
- If intermediate names not bound.
- Throws: NotContextException
- If name is bound but does not name a context.
- Throws: ContextNotEmptyException
- If named context is not empty.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- destroySubcontext
createSubcontext
public Context createSubcontext(String name) throws NamingException
- Creates and binds a new context.
- Parameters:
- name - The non-null name of the context to create.
It cannot be empty.
- Returns:
- The non-null newly created context.
- Throws: NameAlreadyBoundException
- If name is already bound.
- Throws: InvalidAttributesException
- If creation of the
subcontext requires specification of mandatory attributes.
- Throws: NamingException
- if a naming exception was encountered.
- See Also:
- createSubcontext
createSubcontext
public Context createSubcontext(Name name) throws NamingException
- Creates and binds a new context.
- Parameters:
- name - The non-null name of the context to create.
It cannot be empty.
- Returns:
- The non-null newly created context.
- Throws: NameAlreadyBoundException
- If name is already bound.
- Throws: InvalidAttributesException
- If creation of the
subcontext requires specification of mandatory attributes.
- Throws: NamingException
- if a naming exception was encountered.
- See Also:
- createSubcontext
lookupLink
public Object lookupLink(String name) throws NamingException
- Retrieve the object named relative to this initial context,
following links except for the terminal atomic component of name.
- Parameters:
- name - The non-null name to look up.
- Returns:
- The non-null object bound to the name by not following the
terminal link (if any). If the object bound to name
is not a link, return the object itself.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- lookupLink
lookupLink
public Object lookupLink(Name name) throws NamingException
- Retrieve the object named relative to this initial context,
following links except for the terminal atomic component of name.
- Parameters:
- name - The non-null name to look up.
- Returns:
- The non-null object bound to the name by not following the
terminal link (if any). If the object bound to name
is not a link, return the object itself.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- lookupLink
getNameParser
public NameParser getNameParser(String name) throws NamingException
- Retrieves the parser associated with the named context.
- Parameters:
- name - The non-null name of the context from which to
get the parser.
- Returns:
- A non-null name parser that will parse names into their atomic
components.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- getNameParser
getNameParser
public NameParser getNameParser(Name name) throws NamingException
- Retrieves the parser associated with the named context.
- Parameters:
- name - The non-null name of the context from which to
get the parser.
- Returns:
- A non-null name parser that will parse names into their atomic
components.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- getNameParser
composeName
public String composeName(String name,
String prefix) throws NamingException
- Composes the name of this context with a name relative to
this context.
- Parameters:
- name - A non-null name relative to this context.
- prefix - The non-null name of this context relative to one of
its ancestors.
- Returns:
- The non-null composition of
prefix
and
name
.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- composeName
composeName
public Name composeName(Name name,
Name prefix) throws NamingException
- Composes the name of this context with a name relative to
this context.
- Parameters:
- name - A non-null name relative to this context.
- prefix - The non-null name of this context relative to one of
its ancestors.
- Returns:
- The non-null composition of
prefix
and
name
.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- composeName
addToEnvironment
public Object addToEnvironment(String propName,
Object propVal) throws NamingException
- Adds a new environment property to the environment of this
context.
- Parameters:
- propName - The non-null name of the environment property to add.
If already exists in environment, overwrite and return old value.
- propVal - The non-null value.
- Returns:
- The value that propName used to have in the
environment; null if not there before.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- addToEnvironment
removeFromEnvironment
public Object removeFromEnvironment(String propName) throws NamingException
- Removes an environment property from the environment of this
context.
- Parameters:
- propName - The non-null name of the environment property to remove.
- Returns:
- The value associated with propName. null if
propName was not in the environment.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- removeFromEnvironment
getEnvironment
public Hashtable getEnvironment() throws NamingException
- Retrieves the environment in effect for the
initial context.
- Returns:
- The non-null (possibly empty) environment for
this context.
Caller should not make changes to this object:
their effect on the context is undefined.
To change the environment of the context,
use addToEnvironment() and removeFromEnvironment().
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- getEnvironment
close
public void close() throws NamingException
- Closes this initial context.
This method is idempotent. Invoking close() on an already closed
context does not do anything. However, invoking any other method
on a closed context results in undefined behavior.
- Throws: NamingException
- If a naming exception was encountered.
All Packages Class Hierarchy This Package Previous Next Index