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