All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface javax.naming.Context

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

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.


Variable Index

 o AUTHORITATIVE
Constant that holds the name of the environment property for specifying the authoritativeness of the service requested.
 o 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.
 o 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").
 o INITIAL_CONTEXT_FACTORY
Constant that holds the name of the environment property for specifying the initial context factory to use.
 o LANGUAGE
Constant that holds the name of the environment property for specifying the preferred language to use with the service.
 o OBJECT_FACTORIES
Constant that holds the name of the environment property for specifying the list of object factories to use.
 o PROVIDER_URL
Constant that holds the name of the environment property for specifying configuration information for the service provider to use.
 o REFERRAL
Constant that holds the name of the environment property for specifying how referrals encountered by the service provider are to be processed.
 o SECURITY_AUTHENTICATION
Constant that holds the name of the environment property for specifying the security level to use.
 o 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.
 o 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.
 o SECURITY_PROTOCOL
Constant that holds the name of the environment property for specifying the security protocol to use.
 o 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 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.

Variables

 o INITIAL_CONTEXT_FACTORY
 public static final 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, getInitialContext, InitialContextFactory, NoInitialContextException, addToEnvironment, removeFromEnvironment
 o OBJECT_FACTORIES
 public static final 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:
getObjectInstance, ObjectFactory, addToEnvironment, removeFromEnvironment
 o URL_PKG_PREFIXES
 public static final 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:
getObjectInstance, getURLContext, ObjectFactory, addToEnvironment, removeFromEnvironment
 o PROVIDER_URL
 public static final 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, removeFromEnvironment
 o DNS_URL
 public static final 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, removeFromEnvironment
 o AUTHORITATIVE
 public static final 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, removeFromEnvironment
 o BATCHSIZE
 public static final 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, removeFromEnvironment
 o REFERRAL
 public static final 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, removeFromEnvironment
 o SECURITY_PROTOCOL
 public static final 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, removeFromEnvironment
 o SECURITY_AUTHENTICATION
 public static final 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, removeFromEnvironment
 o SECURITY_PRINCIPAL
 public static final 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, removeFromEnvironment
 o SECURITY_CREDENTIALS
 public static final 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, removeFromEnvironment
 o LANGUAGE
 public static final 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, removeFromEnvironment

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