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.


Method Index

 o addToEnvironment(String, Object)
Adds a new environment property to the environment of this context.
 o bind(Name, Object)
Binds 'name' to the object 'obj'.
 o bind(String, Object)
Binds 'name' to the object 'obj' using its string name.
 o close()
Closes this context.
 o composeName(Name, Name)
Composes the name of this context with a name relative to this context.
 o composeName(String, String)
Composes the string name of this context with a string name relative to this context.
 o createSubcontext(Name)
Creates and binds a new context.
 o createSubcontext(String)
Creates and binds a new context using a string name.
 o destroySubcontext(Name)
Destroys the named context and removes it from the namespace.
 o destroySubcontext(String)
Destroys the (string-) named context and removes it from the namespace.
 o getEnvironment()
Retrieves the environment in effect for this context.
 o getNameParser(Name)
Retrieves the parser associated with the named context.
 o getNameParser(String)
Retrieves the parser associated with the (string-) named context.
 o list(Name)
Enumerates the names and the class names of their bound objects in the named context.
 o list(String)
Enumerates the names and the class names of their bound objects in the (string-) named context.
 o listBindings(Name)
Enumerates the names and their bound objects in the named context.
 o listBindings(String)
Enumerates the names and their bound objects in the (string-) named context.
 o lookup(Name)
Retrieves the named object.
 o lookup(String)
Retrieves the named object using its string name.
 o lookupLink(Name)
Retrieves the named object, following links except for the terminal atomic component of name.
 o lookupLink(String)
Retrieves the (string-) named object, following links except for the terminal atomic component of name.
 o rebind(Name, Object)
Binds 'name' to the object 'obj', overwriting any existing binding.
 o rebind(String, Object)
Binds 'name' to the object 'obj' using its string name, overwriting any existing binding.
 o removeFromEnvironment(String)
Removes an environment property from the environment of this context.
 o rename(Name, Name)
Binds 'newName' to the object bound to 'oldName', and unbinds 'oldName'.
 o rename(String, String)
Binds 'newName' to the object bound to 'oldName', and unbinds 'oldName' using string names.
 o unbind(Name)
Unbinds the named object from the namespace using its string name.
 o unbind(String)
Unbinds the named object from the namespace using its string name.

Methods

 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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
 o 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