javax.naming
Interface Context

All Known Subinterfaces:

DirContext

All Known Implementing Classes:

InitialContext

public abstract interface Context

This interface represents a naming context, which consists of a set of name-to-object bindings. It contains methods for examining and updating these bindings.

Names

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

For systems that support federation, all name arguments to Context methods are composite names, regardless of whether they are represented as Strings or Names. Furthermore, for such systems, all names returned in NamingEnumeration from list() & listBindings() are composite names, even though they are represented as Strings. See CompositeName for the string syntax of names.

For systems that do not support federation, the name arguments (in either Name or String forms) and the names returned in NamingEnumeration may be names in their own namespace rather than names in a composite namespace, at the discretion of the service provider.

Exceptions

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.

Environment Properties

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.

It is implementation-dependent when environment properties are used and/or verified for validity. For example, some of the security-related properties are used by service providers to "login" to the directory. This login process might occur at the time the context is created, or the first time a method is invoked on the context. When, and whether this occurs at all, is implementation-dependent. When environment properties are added or removed from the context, verifying the validity of the changes is again implementation-dependent. For example, verification of some properties might occur at the time the change is made, or at the time the next operation is performed on the context, or, not at all.

Field Summary

static java.lang.String	AUTHORITATIVE Constant that holds the name of the environment property for specifying the authoritativeness of the service requested.
static java.lang.String	BATCHSIZE Constant that holds the name of the environment property for specifying the batch size to use when returning data via the service's protocol.
static java.lang.String	DNS_URL Constant that holds the name of the environment property for specifying the DNS host and domain names to use for the JNDI URL context (for example, "dns://somehost/wiz.com").
static java.lang.String	INITIAL_CONTEXT_FACTORY Constant that holds the name of the environment property for specifying the initial context factory to use.
static java.lang.String	LANGUAGE Constant that holds the name of the environment property for specifying the preferred language to use with the service.
static java.lang.String	OBJECT_FACTORIES Constant that holds the name of the environment property for specifying the list of object factories to use.
static java.lang.String	PROVIDER_URL Constant that holds the name of the environment property for specifying configuration information for the service provider to use.
static java.lang.String	REFERRAL Constant that holds the name of the environment property for specifying how referrals encountered by the service provider are to be processed.
static java.lang.String	SECURITY_AUTHENTICATION Constant that holds the name of the environment property for specifying the security level to use.
static java.lang.String	SECURITY_CREDENTIALS Constant that holds the name of the environment property for specifying the credentials of the principal for authenticating the caller to the service.
static java.lang.String	SECURITY_PRINCIPAL Constant that holds the name of the environment property for specifying the identity of the principal for authenticating the caller to the service.
static java.lang.String	SECURITY_PROTOCOL Constant that holds the name of the environment property for specifying the security protocol to use.
static java.lang.String	URL_PKG_PREFIXES Constant that holds the name of the environment property for specifying the list of package prefixes to use when loading in URL context factories.

Method Summary

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

Field Detail

INITIAL_CONTEXT_FACTORY

public static final java.lang.String INITIAL_CONTEXT_FACTORY

Constant that holds the name of the environment property for specifying the initial context factory to use. The value of the property should be the fully qualified class name of the factory class that will create an initial context. If the property is not specified in the environment, the system property by the same name is used. If not specified as a system property either, a NoInitialContextException is thrown when an initial context is required to complete the operation.

The value of this constant is "java.naming.factory.initial".

See Also:

InitialContext, InitialDirContext, NamingManager.getInitialContext(java.util.Hashtable), InitialContextFactory, NoInitialContextException, addToEnvironment(java.lang.String, java.lang.Object), removeFromEnvironment(java.lang.String)

OBJECT_FACTORIES

public static final java.lang.String OBJECT_FACTORIES

Constant that holds the name of the environment property for specifying the list of object factories to use. The value of the property should be a colon-separated list of the fully qualified class names of factory classes that will create an object given information about the object. If the property is not specified in the environment, the system property by the same name is used. If not specified as a system property either, NamingManager.getObjectInstance() will use means to attempt to create the object. See NamingManager.getObjectInstance() for details.

The value of this constant is "java.naming.factory.object".

See Also:

NamingManager.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), ObjectFactory, addToEnvironment(java.lang.String, java.lang.Object), removeFromEnvironment(java.lang.String)

URL_PKG_PREFIXES

public static final java.lang.String URL_PKG_PREFIXES

Constant that holds the name of the environment property for specifying the list of package prefixes to use when loading in URL context factories. The value of the property should be a colon-separated list of package prefixes for the class name of the factory class that will create a URL context factory. If the property is not specified in the environment, the system property by the same name is used. The prefix com.sun.jndi.url is always added to the end of the possibly empty list of package prefixes.

The value of this constant is "java.naming.factory.url.pkgs".

See Also:

NamingManager.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), NamingManager.getURLContext(java.lang.String, java.util.Hashtable), ObjectFactory, addToEnvironment(java.lang.String, java.lang.Object), removeFromEnvironment(java.lang.String)

PROVIDER_URL

public static final java.lang.String PROVIDER_URL

Constant that holds the name of the environment property for specifying configuration information for the service provider to use. The value of the property should contain a URL string (e.g. "ldap://somehost:389"). If the property is not specified in the environment, the system property by the same name is used. If not specified as a system property either, the default configuration is determined by the service provider.

The value of this constant is "java.naming.provider.url".

See Also:

addToEnvironment(java.lang.String, java.lang.Object), removeFromEnvironment(java.lang.String)

DNS_URL

public static final java.lang.String DNS_URL

Constant that holds the name of the environment property for specifying the DNS host and domain names to use for the JNDI URL context (for example, "dns://somehost/wiz.com"). If the property is not specified in the environment, the system property by the same name is used. If not specified as a system property either and the program attempts to use a JNDI URL containing a DNS name, ConfigurationException is thrown.

The value of this constant is "java.naming.dns.url".

See Also:

addToEnvironment(java.lang.String, java.lang.Object), removeFromEnvironment(java.lang.String)

AUTHORITATIVE

public static final java.lang.String AUTHORITATIVE

Constant that holds the name of the environment property for specifying the authoritativeness of the service requested. If the value of the property is the string "true", it means that the access the most authoritative source (i.e. bypass any cache or replicas). If the value is anything else, the source need not be (but can be) authoritative. If unspecified, this property defaults to "false".

The value of this constant is "java.naming.authoritative".

See Also:

addToEnvironment(java.lang.String, java.lang.Object), removeFromEnvironment(java.lang.String)

BATCHSIZE

public static final java.lang.String BATCHSIZE

Constant that holds the name of the environment property for specifying the batch size to use when returning data via the service's protocol. This is a hint to the provider to return the results of operations in batches of the specified size, so the provider can optimize its performance and usage of resources. The value of the property is the string representation of an integer. If unspecified, the batch size is determined by the provider.

The value of this constant is "java.naming.batchsize".

See Also:

addToEnvironment(java.lang.String, java.lang.Object), removeFromEnvironment(java.lang.String)

REFERRAL

public static final java.lang.String REFERRAL

Constant that holds the name of the environment property for specifying how referrals encountered by the service provider are to be processed. The value of the property is one of the following strings:

follow

follow referrals automatically

ignore

ignore referrals

throw

throw ReferralException when a referral is encountered.

If unspecified, the default is determined by the provider.

The value of this constant is "java.naming.referral".

See Also:

addToEnvironment(java.lang.String, java.lang.Object), removeFromEnvironment(java.lang.String)

SECURITY_PROTOCOL

public static final java.lang.String SECURITY_PROTOCOL

Constant that holds the name of the environment property for specifying the security protocol to use. Its value is a string determined by the service provider (e.g. "ssl"). If unspecified, the behaviour is determined by the service provider.

The value of this constant is "java.naming.security.protocol".

See Also:

addToEnvironment(java.lang.String, java.lang.Object), removeFromEnvironment(java.lang.String)

SECURITY_AUTHENTICATION

public static final java.lang.String SECURITY_AUTHENTICATION

Constant that holds the name of the environment property for specifying the security level to use. Its value is one of the following strings: "none", "simple", "strong". If unspecified, the behaviour is determined by the service provider.

The value of this constant is "java.naming.security.authentication".

See Also:

addToEnvironment(java.lang.String, java.lang.Object), removeFromEnvironment(java.lang.String)

SECURITY_PRINCIPAL

public static final java.lang.String SECURITY_PRINCIPAL

Constant that holds the name of the environment property for specifying the identity of the principal for authenticating the caller to the service. The value of the property depends on the authentication scheme . If unspecified, the behaviour is determined by the service provider.

The value of this constant is "java.naming.security.principal".

See Also:

addToEnvironment(java.lang.String, java.lang.Object), removeFromEnvironment(java.lang.String)

SECURITY_CREDENTIALS

public static final java.lang.String SECURITY_CREDENTIALS

Constant that holds the name of the environment property for specifying the credentials of the principal for authenticating the caller to the service. The value of the property depends on the authentication scheme. For example, it could be a hashed password, clear-text password, key, certificate, and so on. If unspecified, the behaviour is determined by the service provider.

The value of this constant is "java.naming.security.credentials".

See Also:

addToEnvironment(java.lang.String, java.lang.Object), removeFromEnvironment(java.lang.String)

LANGUAGE

public static final java.lang.String LANGUAGE

Constant that holds the name of the environment property for specifying the preferred language to use with the service. The value of the property is a colon-separated list of language tags defined in RFC 1766. If unspecified, the language preference is determined by the service provider.

The value of this constant is "java.naming.language".

See Also:

addToEnvironment(java.lang.String, java.lang.Object), removeFromEnvironment(java.lang.String)

Method Detail

lookup

public java.lang.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(java.lang.String), lookupLink(java.lang.String)

lookup

public java.lang.Object lookup(java.lang.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(Name)

bind

public void bind(Name name,
                 java.lang.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.

InvalidAttributesException - If obj did not supply all mandatory attributes.

NamingException - If a naming exception was encountered.

See Also:

bind(java.lang.String, java.lang.Object), rename(java.lang.String, java.lang.String), DirContext.bind(javax.naming.Name, java.lang.Object, javax.naming.directory.Attributes)

bind

public void bind(java.lang.String name,
                 java.lang.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.

InvalidAttributesException - If obj did not supply all mandatory attributes.

NamingException - If a naming exception was encountered.

See Also:

bind(Name, java.lang.Object)

rebind

public void rebind(Name name,
                   java.lang.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.

NamingException - If a naming exception was encountered.

See Also:

rebind(java.lang.String, java.lang.Object), bind(java.lang.String, java.lang.Object), rename(java.lang.String, java.lang.String), DirContext

rebind

public void rebind(java.lang.String name,
                   java.lang.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.

NamingException - If a naming exception was encountered.

See Also:

rebind(Name, java.lang.Object)

unbind

public 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(java.lang.String)

unbind

public void unbind(java.lang.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(Name)

rename

public 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.

NamingException - If a naming exception was encountered.

See Also:

rename(java.lang.String, java.lang.String), bind(java.lang.String, java.lang.Object), rebind(java.lang.String, java.lang.Object)

rename

public void rename(java.lang.String oldName,
                   java.lang.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.

NamingException - If a naming exception was encountered.

See Also:

rename(Name, Name)

list

public 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(java.lang.String), listBindings(java.lang.String), NameClassPair

list

public NamingEnumeration list(java.lang.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(Name)

listBindings

public 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(java.lang.String), list(java.lang.String), Binding

listBindings

public NamingEnumeration listBindings(java.lang.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(Name), Binding

destroySubcontext

public 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.

In a federated naming system, you can bind a context from one naming system to a context in another naming system. You can subsequently look up and perform operations on the foreign context using a composite name. However, if you attempt to destroy the context using destroySubcontext() using this composite name, it will fail with NotContextException because the foreign context is not a "subcontext" of the context in which it is bound. Instead, use unbind() to remove binding of the foreign context. To destroy the foreign context, you need to get a reference for the context in its "native" naming system and perform the destroySubcontext() in that naming system.

Parameters:

name - The non-null name of the context to be destroyed. It cannot be empty.

Throws:

NameNotFoundException - If intermediate names not bound.

NotContextException - If name is bound but does not name a context.

ContextNotEmptyException - If named context is not empty.

NamingException - If a naming exception was encountered.

See Also:

destroySubcontext(java.lang.String)

destroySubcontext

public void destroySubcontext(java.lang.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.

NotContextException - If name is bound but does not name a context.

ContextNotEmptyException - If named context is not empty.

NamingException - If a naming exception was encountered.

See Also:

destroySubcontext(Name)

createSubcontext

public 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.

InvalidAttributesException - If creation of the subcontext requires specification of mandatory attributes.

NamingException - if a naming exception was encountered.

See Also:

createSubcontext(java.lang.String), DirContext

createSubcontext

public Context createSubcontext(java.lang.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.

InvalidAttributesException - If creation of the subcontext requires specification of mandatory attributes.

NamingException - if a naming exception was encountered.

See Also:

createSubcontext(Name)

lookupLink

public java.lang.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(java.lang.String)

lookupLink

public java.lang.Object lookupLink(java.lang.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(Name)

getNameParser

public 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(java.lang.String), CompoundName

getNameParser

public NameParser getNameParser(java.lang.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(Name)

composeName

public 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(java.lang.String, java.lang.String)

composeName

public java.lang.String composeName(java.lang.String name,
                                    java.lang.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(Name, Name)

addToEnvironment

public java.lang.Object addToEnvironment(java.lang.String propName,
                                         java.lang.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(java.lang.String)

removeFromEnvironment

public java.lang.Object removeFromEnvironment(java.lang.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(java.lang.String, java.lang.Object)

getEnvironment

public java.util.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(java.lang.String, java.lang.Object), removeFromEnvironment(java.lang.String)

close

public 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.