All Packages Class Hierarchy This Package Previous Next Index
Interface javax.naming.Context
- public interface Context
The Context interface represents a naming context, which
consists of a set of name-to-object bindings.
It contains methods for examining and updating these bindings.
Each name passed as an argument to a Context is relative to
that context. The empty name is used to name the context itself.
Most of the methods have overloaded versions with one taking a
Name
parameter and one taking a String
.
These overloaded versions are equivalent in that if
the Name
and String
parameters are just
different representations of the same name, then the overloaded
versions of the same methods should behave the same.
See CompositeName
for the string syntax of names.
In the method descriptions below, only one version is documented.
The second version instead has a link to the first: the same
documentation applies to both.
All the methods in this interface can throw a NamingException or
any of its subclasses. See NamingException and their subclasses
for details on each exception.
JNDI applications need a way to communicate various preferences
and properties that define the environment in which naming and
directory services are accessed. For example, a context might
require specification of security credentials in order to access
the service. Another context might require that server configuration
information be supplied. These are referred to as the environment
of a context. The Context interface provides
methods for retrieving and updating the environment of
a context.
The environment are inherited from the parent context as
context methods proceed from one context to the next. Changes to
the environment of one context does not affect those
of other contexts.
-
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 'name' to the object 'obj' using its string name.
-
close()
- Closes this context.
-
composeName(Name, Name)
- Composes the name of this context with a name relative to
this context.
-
composeName(String, String)
- Composes the string name of this context with a string name relative to
this context.
-
createSubcontext(Name)
- Creates and binds a new context.
-
createSubcontext(String)
- Creates and binds a new context using a string name.
-
destroySubcontext(Name)
- Destroys the named context and removes it from the namespace.
-
destroySubcontext(String)
- Destroys the (string-) named context and removes it from the namespace.
-
getEnvironment()
- Retrieves the environment in effect for this context.
-
getNameParser(Name)
- Retrieves the parser associated with the named context.
-
getNameParser(String)
- Retrieves the parser associated with the (string-) named context.
-
list(Name)
- Enumerates the names and the class names of their
bound objects in the named context.
-
list(String)
- Enumerates the names and the class names of their
bound objects in the (string-) named context.
-
listBindings(Name)
- Enumerates the names and their bound objects in
the named context.
-
listBindings(String)
- Enumerates the names and their bound objects in
the (string-) named context.
-
lookup(Name)
- Retrieves the named object.
-
lookup(String)
- Retrieves the named object using its string name.
-
lookupLink(Name)
- Retrieves the named object, following links except
for the terminal atomic component of name.
-
lookupLink(String)
- Retrieves the (string-) named object, following links except
for the terminal atomic component of name.
-
rebind(Name, Object)
- Binds 'name' to the object 'obj', overwriting any existing binding.
-
rebind(String, Object)
- Binds 'name' to the object 'obj' using its string name, overwriting
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' using string names.
-
unbind(Name)
- Unbinds the named object from the namespace using its string name.
-
unbind(String)
- Unbinds the named object from the namespace using its string name.
lookup
public abstract Object lookup(Name name) throws NamingException
- Retrieves the named object.
- Parameters:
- name - The non-null name to look up.
If empty, returns a new instance of this context
(this represents the same naming context as this
context, but its environment may be modified
independently). See class description for more
information on environment.
- Returns:
- The non-null object bound to 'name'.
- Throws: NamingException
- If a naming exception was encountered during the lookup.
- See Also:
- lookup, lookupLink
lookup
public abstract Object lookup(String name) throws NamingException
- Retrieves the named object using its string name.
- 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
bind
public abstract void bind(Name name,
Object obj) throws NamingException
- Binds 'name' to the object 'obj'.
All intermediate contexts and the target context (that named by all
but terminal atomic component of the name) must already exist.
- Parameters:
- name - The non-null name to bind. It cannot be empty.
- obj - The possibly 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, rename, bind
bind
public abstract void bind(String name,
Object obj) throws NamingException
- Binds 'name' to the object 'obj' using its string name.
- Parameters:
- name - The non-null name to bind. It cannot be empty.
- obj - The possibly 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 abstract void rebind(Name name,
Object obj) throws NamingException
- Binds 'name' to the object 'obj', overwriting any existing binding.
If name is already bound, overwrite the existing binding.
All intermediate contexts and the target context (that named by all
but terminal atomic component of the name) must already exist.
- Parameters:
- name - The non-null name to bind. It cannot be empty.
- obj - The possibly null object to bind. If obj is a DirContext,
the attributes associated with the name
already bound are replaced with the attributes
of obj. If obj is not a DirContext,
any existing attributes associated with the name
already bound remain unchanged.
- Throws: InvalidAttributesException
- If obj did not supply all mandatory attributes.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- rebind, bind, rename, DirContext
rebind
public abstract void rebind(String name,
Object obj) throws NamingException
- Binds 'name' to the object 'obj' using its string name, overwriting
any existing binding.
- Parameters:
- name - The non-null name to bind. It cannot be empty.
- obj - The possibly 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 abstract void unbind(Name name) throws NamingException
- Unbinds the named object from the namespace using its string name.
Removes the terminal atomic name in
name
from the target context--that named by all but the terminal
atomic part of name
.
This method is idempotent.
It succeeds even if the terminal atomic name
was not bound in the target context, but throws NameNotFoundException
if any of the intermediate names are not bound.
Any attributes associated with name are removed.
Intermediate contexts are not changed.
- 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 abstract void unbind(String name) throws NamingException
- Unbinds the named object from the namespace using its string name.
- 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 abstract void rename(Name oldName,
Name newName) throws NamingException
- Binds 'newName' to the object bound to 'oldName', and unbinds
'oldName'.
Any attributes associated with 'oldName' become associated
with 'newName'.
Intermediate contexts of 'oldName' are not changed.
- Parameters:
- oldName - The name of the existing binding,
relative to this context.
It cannot be empty.
- newName - The name of the new binding,
relative to this context.
It cannot be empty.
- Throws: NameAlreadyBoundException
- If newName is already bound.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- rename, bind, rebind
rename
public abstract void rename(String oldName,
String newName) throws NamingException
- Binds 'newName' to the object bound to 'oldName', and unbinds
'oldName' using string names.
- 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 abstract NamingEnumeration list(Name name) throws NamingException
- Enumerates the names and the class names of their
bound objects in the named context. The contents of any
subcontexts are not included.
When a name is added to or removed from this context,
its effects on this enumeration are undefined.
- 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, listBindings, NameClassPair
list
public abstract NamingEnumeration list(String name) throws NamingException
- Enumerates the names and the class names of their
bound objects in the (string-) named 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
listBindings
public abstract NamingEnumeration listBindings(Name name) throws NamingException
- Enumerates the names and their bound objects in
the named context. The contents of any subcontexts are not included.
When a name is added to or removed from this context,
its effects on this enumeration are undefined.
- 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, list, Binding
listBindings
public abstract NamingEnumeration listBindings(String name) throws NamingException
- Enumerates the names and their bound objects in
the (string-) named 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, Binding
destroySubcontext
public abstract void destroySubcontext(Name name) throws NamingException
- Destroys the named context and removes it from the namespace.
Any attributes associated with name are also removed.
Intermediate contexts are not destroyed.
This method is idempotent.
It succeeds even if the terminal atomic name
was not bound in the target context, but throws NameNotFoundException
if any of the intermediate names are not bound.
- Parameters:
- name - The non-null name of the context to be destroyed.
It cannot be empty.
- 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 abstract void destroySubcontext(String name) throws NamingException
- Destroys the (string-) 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 abstract Context createSubcontext(Name name) throws NamingException
- Creates and binds a new context.
Creates a new context with the given name and binds it in
the target context (that named by all but terminal atomic
component of the name). All intermediate contexts and the
target context must already exist.
- 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, DirContext
createSubcontext
public abstract Context createSubcontext(String name) throws NamingException
- Creates and binds a new context using a string name.
- 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 abstract Object lookupLink(Name name) throws NamingException
- Retrieves the named object, 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 abstract Object lookupLink(String name) throws NamingException
- Retrieves the (string-) named object, 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 abstract NameParser getNameParser(Name name) throws NamingException
- Retrieves the parser associated with the named context.
In a federation of namespaces, different naming systems will
parse names differently. This method allows an application
to get a parser for parsing names into their atomic components
using the naming convention of a particular naming system.
Within any single naming system, the NameParser object returned
by this method must be equal (using equals() test).
- 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, CompoundName
getNameParser
public abstract NameParser getNameParser(String name) throws NamingException
- Retrieves the parser associated with the (string-) 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 abstract Name composeName(Name name,
Name prefix) throws NamingException
- Composes the name of this context with a name relative to
this context.
Given a name (
name
) relative to this context, and
the name (prefix
) of this context relative to one
of its ancestors, this method returns the composition of the
two names using the syntax appropriate for the naming
system(s) involved. That is, if name
names an
object relative to this context, the result is the name of the
same object, but relative to the ancestor context.
For example, if this context is named "wiz.com" relative
to the initial context, then
composeName("east", "wiz.com")
might return "east.wiz.com"
.
If instead this context is named "org/research", then
composeName("user/jane", "org/research")
might return "org/research/user/jane"
while
composeName("user/jane", "research")
returns "research/user/jane"
.
- 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 abstract String composeName(String name,
String prefix) throws NamingException
- Composes the string name of this context with a string 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 abstract Object addToEnvironment(String propName,
Object propVal) throws NamingException
- Adds a new environment property to the environment of this
context. See class description for more details on environment
properties.
- 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:
- getEnvironment, removeFromEnvironment
removeFromEnvironment
public abstract Object removeFromEnvironment(String propName) throws NamingException
- Removes an environment property from the environment of this
context. See class description for more details on environment
properties.
- Parameters:
- propName - The non-null name of the environment property to remove.
- Returns:
- The value associated with propName;
null if propName was not in environment.
- Throws: NamingException
- If a naming exception was encountered.
- See Also:
- getEnvironment, addToEnvironment
getEnvironment
public abstract Hashtable getEnvironment() throws NamingException
- Retrieves the environment in effect for this context.
See class description for more details on environment.
- Returns:
- The non-null (but 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:
- addToEnvironment, removeFromEnvironment
close
public abstract void close() throws NamingException
- Closes this context.
This method releases a context's resources immediately instead of
waiting for them to be released automatically via the garbage
collector.
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 behaviour.
- Throws: NamingException
- If a naming exception was encountered.
All Packages Class Hierarchy This Package Previous Next Index