|
JNDI 1.1.1 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
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.
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 |
public static final java.lang.String INITIAL_CONTEXT_FACTORY
The value of this constant is "java.naming.factory.initial".
InitialContext
,
InitialDirContext
,
NamingManager.getInitialContext(java.util.Hashtable)
,
InitialContextFactory
,
NoInitialContextException
,
addToEnvironment(java.lang.String, java.lang.Object)
,
removeFromEnvironment(java.lang.String)
public static final java.lang.String OBJECT_FACTORIES
The value of this constant is "java.naming.factory.object".
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)
public static final java.lang.String URL_PKG_PREFIXES
The value of this constant is "java.naming.factory.url.pkgs".
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)
public static final java.lang.String PROVIDER_URL
The value of this constant is "java.naming.provider.url".
addToEnvironment(java.lang.String, java.lang.Object)
,
removeFromEnvironment(java.lang.String)
public static final java.lang.String DNS_URL
The value of this constant is "java.naming.dns.url".
addToEnvironment(java.lang.String, java.lang.Object)
,
removeFromEnvironment(java.lang.String)
public static final java.lang.String AUTHORITATIVE
The value of this constant is "java.naming.authoritative".
addToEnvironment(java.lang.String, java.lang.Object)
,
removeFromEnvironment(java.lang.String)
public static final java.lang.String BATCHSIZE
The value of this constant is "java.naming.batchsize".
addToEnvironment(java.lang.String, java.lang.Object)
,
removeFromEnvironment(java.lang.String)
public static final java.lang.String REFERRAL
The value of this constant is "java.naming.referral".
addToEnvironment(java.lang.String, java.lang.Object)
,
removeFromEnvironment(java.lang.String)
public static final java.lang.String SECURITY_PROTOCOL
The value of this constant is "java.naming.security.protocol".
addToEnvironment(java.lang.String, java.lang.Object)
,
removeFromEnvironment(java.lang.String)
public static final java.lang.String SECURITY_AUTHENTICATION
The value of this constant is "java.naming.security.authentication".
addToEnvironment(java.lang.String, java.lang.Object)
,
removeFromEnvironment(java.lang.String)
public static final java.lang.String SECURITY_PRINCIPAL
The value of this constant is "java.naming.security.principal".
addToEnvironment(java.lang.String, java.lang.Object)
,
removeFromEnvironment(java.lang.String)
public static final java.lang.String SECURITY_CREDENTIALS
The value of this constant is "java.naming.security.credentials".
addToEnvironment(java.lang.String, java.lang.Object)
,
removeFromEnvironment(java.lang.String)
public static final java.lang.String LANGUAGE
The value of this constant is "java.naming.language".
addToEnvironment(java.lang.String, java.lang.Object)
,
removeFromEnvironment(java.lang.String)
Method Detail |
public java.lang.Object lookup(Name name) throws NamingException
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.lookup(java.lang.String)
,
lookupLink(java.lang.String)
public java.lang.Object lookup(java.lang.String name) throws NamingException
name
- The non-null string name of the object to lookup.lookup(Name)
public void bind(Name name, java.lang.Object obj) throws NamingException
name
- The non-null name to bind. It cannot be empty.obj
- The possibly null object to bind.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)
public void bind(java.lang.String name, java.lang.Object obj) throws NamingException
name
- The non-null name to bind. It cannot be empty.obj
- The possibly null object to bind.bind(Name, java.lang.Object)
public void rebind(Name name, java.lang.Object obj) throws NamingException
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.rebind(java.lang.String, java.lang.Object)
,
bind(java.lang.String, java.lang.Object)
,
rename(java.lang.String, java.lang.String)
,
DirContext
public void rebind(java.lang.String name, java.lang.Object obj) throws NamingException
name
- The non-null name to bind. It cannot be empty.obj
- The possibly null object to bind. If obj is a DirContext,rebind(Name, java.lang.Object)
public void unbind(Name name) throws NamingException
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.
name
- The non-null name to unbind. It cannot be empty.unbind(java.lang.String)
public void unbind(java.lang.String name) throws NamingException
name
- The non-null name to unbind. It cannot be empty.unbind(Name)
public void rename(Name oldName, Name newName) throws NamingException
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.rename(java.lang.String, java.lang.String)
,
bind(java.lang.String, java.lang.Object)
,
rebind(java.lang.String, java.lang.Object)
public void rename(java.lang.String oldName, java.lang.String newName) throws NamingException
oldName
- The non-null name of the existing binding,newName
- The non-null name of the new binding,rename(Name, Name)
public NamingEnumeration list(Name name) throws NamingException
name
- The non-null name of the context to list.list(java.lang.String)
,
listBindings(java.lang.String)
,
NameClassPair
public NamingEnumeration list(java.lang.String name) throws NamingException
name
- The non-null name of the context to list.list(Name)
public NamingEnumeration listBindings(Name name) throws NamingException
name
- The non-null name of the context to list.listBindings(java.lang.String)
,
list(java.lang.String)
,
Binding
public NamingEnumeration listBindings(java.lang.String name) throws NamingException
name
- The non-null name of the context to list.listBindings(Name)
,
Binding
public void destroySubcontext(Name name) throws NamingException
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.
name
- The non-null name of the context to be destroyed.
It cannot be empty.destroySubcontext(java.lang.String)
public void destroySubcontext(java.lang.String name) throws NamingException
name
- The non-null name of the context to be destroyed.destroySubcontext(Name)
public Context createSubcontext(Name name) throws NamingException
name
- The non-null name of the context to create.
It cannot be empty.createSubcontext(java.lang.String)
,
DirContext
public Context createSubcontext(java.lang.String name) throws NamingException
name
- The non-null name of the context to create.
It cannot be empty.createSubcontext(Name)
public java.lang.Object lookupLink(Name name) throws NamingException
name
- The non-null name to look up.lookupLink(java.lang.String)
public java.lang.Object lookupLink(java.lang.String name) throws NamingException
name
- The non-null name to look up.lookupLink(Name)
public NameParser getNameParser(Name name) throws NamingException
name
- The non-null name of the context from which to
get the parser.getNameParser(java.lang.String)
,
CompoundName
public NameParser getNameParser(java.lang.String name) throws NamingException
name
- The non-null name of the context from which to
get the parser.getNameParser(Name)
public Name composeName(Name name, Name prefix) throws NamingException
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"
.name
- A non-null name relative to this context.prefix
- The non-null name of this context relative to one of
its ancestors.prefix
and
name
.composeName(java.lang.String, java.lang.String)
public java.lang.String composeName(java.lang.String name, java.lang.String prefix) throws NamingException
name
- A non-null name relative to this context.prefix
- The non-null name of this context relative to one of
its ancestors.prefix
and
name
.composeName(Name, Name)
public java.lang.Object addToEnvironment(java.lang.String propName, java.lang.Object propVal) throws NamingException
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.getEnvironment()
,
removeFromEnvironment(java.lang.String)
public java.lang.Object removeFromEnvironment(java.lang.String propName) throws NamingException
propName
- The non-null name of the environment property to remove.getEnvironment()
,
addToEnvironment(java.lang.String, java.lang.Object)
public java.util.Hashtable getEnvironment() throws NamingException
addToEnvironment(java.lang.String, java.lang.Object)
,
removeFromEnvironment(java.lang.String)
public void close() throws NamingException
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.
|
JNDI 1.1.1 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |