Context
InitialDirContext
public class InitialContext extends Object implements Context
All naming operations are relative to a context. The initial context implements the Context interface and provides the starting point for resolution of names.
When the initial context is constructed, its environment is initialized with properties defined in the environment parameter passed to the constructor, and in any application resource files.
JNDI determines each property's value by merging the values from the following two sources, in order:
jndi.properties
). Context
), all of the values are concatenated into a single colon-separated list. For other properties, only the first value found is used. The initial context implementation is determined at runtime. The default policy uses the environment property "java.naming.factory.initial
", which contains the class name of the initial context factory. An exception to this policy is made when resolving URL strings, as described below.
When a URL string (a String
of the form scheme_id:rest_of_name) is passed as a name parameter to any method, a URL context factory for handling that scheme is located and used to resolve the URL. If no such factory is found, the initial context specified by "java.naming.factory.initial"
is used. Similarly, when a CompositeName
object whose first component is a URL string is passed as a name parameter to any method, a URL context factory is located and used to resolve the first name component. See NamingManager.getURLContext()
for a description of how URL context factories are located.
This default policy of locating the initial context and URL context factories may be overridden by calling NamingManager.setInitialContextFactoryBuilder()
.
NoInitialContextException is thrown when an initial context cannot be instantiated. This exception can be thrown during any interaction with the InitialContext, not only when the InitialContext is constructed. For example, the implementation of the initial context might lazily retrieve the context only when actual methods are invoked on it. The application should not have any dependency on when the existence of an initial context is determined.
When the environment property "java.naming.factory.initial" is non-null, the InitialContext constructor will attempt to create the initial context specified therein. At that time, the initial context factory involved might throw an exception if a problem is encountered. However, it is provider implementation-dependent when it verifies and indicates to the users of the initial context any environment property- or connection- related problems. It can do so lazily--delaying until an operation is performed on the context, or eagerly, at the time the context is constructed.
An InitialContext instance is not synchronized against concurrent access by multiple threads. Multiple threads each manipulating a different InitialContext instance need not synchronize. Threads that need to access a single InitialContext instance concurrently should synchronize amongst themselves and provide the necessary locking.
Modifier and Type | Field | Description |
---|---|---|
protected Context |
defaultInitCtx |
Field holding the result of calling NamingManager.getInitialContext(). |
protected boolean |
gotDefault |
Field indicating whether the initial context has been obtained by calling NamingManager.getInitialContext(). |
protected Hashtable |
myProps |
The environment associated with this InitialContext. |
APPLET, AUTHORITATIVE, BATCHSIZE, DNS_URL, INITIAL_CONTEXT_FACTORY, LANGUAGE, OBJECT_FACTORIES, PROVIDER_URL, REFERRAL, SECURITY_AUTHENTICATION, SECURITY_CREDENTIALS, SECURITY_PRINCIPAL, SECURITY_PROTOCOL, STATE_FACTORIES, URL_PKG_PREFIXES
Modifier | Constructor | Description |
---|---|---|
Constructs an initial context. |
||
protected |
Constructs an initial context with the option of not initializing it. |
|
Constructs an initial context using the supplied environment. |
Modifier and Type | Method | Description |
---|---|---|
Object |
addToEnvironment |
Adds a new environment property to the environment of this context. |
void |
bind |
Binds a name to an object. |
void |
bind |
Binds a name to an object. |
void |
close() |
Closes this context. |
String |
composeName |
Composes the name of this context with a name relative to this context. |
Name |
composeName |
Composes the name of this context with a name relative to this context. |
Context |
createSubcontext |
Creates and binds a new context. |
Context |
createSubcontext |
Creates and binds a new context. |
void |
destroySubcontext |
Destroys the named context and removes it from the namespace. |
void |
destroySubcontext |
Destroys the named context and removes it from the namespace. |
static <T> T |
doLookup |
A static method to retrieve the named object. |
static <T> T |
doLookup |
A static method to retrieve the named object. |
protected Context |
getDefaultInitCtx() |
Retrieves the initial context by calling NamingManager.getInitialContext() and cache it in defaultInitCtx. |
Hashtable |
getEnvironment() |
Retrieves the environment in effect for this context. |
String |
getNameInNamespace() |
Retrieves the full name of this context within its own namespace. |
NameParser |
getNameParser |
Retrieves the parser associated with the named context. |
NameParser |
getNameParser |
Retrieves the parser associated with the named context. |
protected Context |
getURLOrDefaultInitCtx |
Retrieves a context for resolving the string name name . |
protected Context |
getURLOrDefaultInitCtx |
Retrieves a context for resolving name . |
protected void |
init |
Initializes the initial context using the supplied environment. |
NamingEnumeration |
list |
Enumerates the names bound in the named context, along with the class names of objects bound to them. |
NamingEnumeration |
list |
Enumerates the names bound in the named context, along with the class names of objects bound to them. |
NamingEnumeration |
listBindings |
Enumerates the names bound in the named context, along with the objects bound to them. |
NamingEnumeration |
listBindings |
Enumerates the names bound in the named context, along with the objects bound to them. |
Object |
lookup |
Retrieves the named object. |
Object |
lookup |
Retrieves the named object. |
Object |
lookupLink |
Retrieves the named object, following links except for the terminal atomic component of the name. |
Object |
lookupLink |
Retrieves the named object, following links except for the terminal atomic component of the name. |
void |
rebind |
Binds a name to an object, overwriting any existing binding. |
void |
rebind |
Binds a name to an object, overwriting any existing binding. |
Object |
removeFromEnvironment |
Removes an environment property from the environment of this context. |
void |
rename |
Binds a new name to the object bound to an old name, and unbinds the old name. |
void |
rename |
Binds a new name to the object bound to an old name, and unbinds the old name. |
void |
unbind |
Unbinds the named object. |
void |
unbind |
Unbinds the named object. |
protected Hashtable<Object,Object> myProps
init()
method.protected Context defaultInitCtx
protected boolean gotDefault
defaultInitCtx
.protected InitialContext(boolean lazy) throws NamingException
InitialContext
constructor is called. The subclass's constructor will call this constructor, compute the value of the environment, and then call init()
before returning.lazy
- true means do not initialize the initial context; false is equivalent to calling new InitialContext()
NamingException
- if a naming exception is encounteredpublic InitialContext() throws NamingException
new InitialContext(null)
.NamingException
- if a naming exception is encounteredpublic InitialContext(Hashtable<?,?> environment) throws NamingException
This constructor will not modify environment
or save a reference to it, but may save a clone. Caller should not modify mutable keys and values in environment
after it has been passed to the constructor.
environment
- environment used to create the initial context. Null indicates an empty environment.NamingException
- if a naming exception is encounteredprotected void init(Hashtable<?,?> environment) throws NamingException
This method will modify environment
and save a reference to it. The caller may no longer modify it.
environment
- environment used to create the initial context. Null indicates an empty environment.NamingException
- if a naming exception is encounteredpublic static <T> T doLookup(Name name) throws NamingException
InitialContext ic = new InitialContext();
Object obj = ic.lookup();
If name
is empty, returns a new instance of this context (which represents the same naming context as this context, but its environment may be modified independently and it may be accessed concurrently).
T
- the type of the returned objectname
- the name of the object to look upname
NamingException
- if a naming exception is encounteredpublic static <T> T doLookup(String name) throws NamingException
doLookup(Name)
for details.T
- the type of the returned objectname
- the name of the object to look upname
NamingException
- if a naming exception is encounteredprotected Context getDefaultInitCtx() throws NamingException
NamingManager.getInitialContext()
and cache it in defaultInitCtx. Set gotDefault
so that we know we've tried this before.NoInitialContextException
- If cannot find an initial context.NamingException
- If a naming exception was encountered.protected Context getURLOrDefaultInitCtx(String name) throws NamingException
name
. If name
name is a URL string, then attempt to find a URL context for it. If none is found, or if name
is not a URL string, then return getDefaultInitCtx()
. See getURLOrDefaultInitCtx(Name) for description of how a subclass should use this method.
name
- The non-null name for which to get the context.name
or the cached initial context. The result cannot be null.NoInitialContextException
- If cannot find an initial context.NamingException
- In a naming exception is encountered.protected Context getURLOrDefaultInitCtx(Name name) throws NamingException
name
. If the first component of name
name is a URL string, then attempt to find a URL context for it. If none is found, or if the first component of name
is not a URL string, then return getDefaultInitCtx()
. When creating a subclass of InitialContext, use this method as follows. Define a new method that uses this method to get an initial context of the desired subclass.
When providing implementations for the new methods in the subclass, use this newly defined method to get the initial context.protected XXXContext getURLOrDefaultInitXXXCtx(Name name) throws NamingException { Context answer = getURLOrDefaultInitCtx(name); if (!(answer instanceof XXXContext)) { if (answer == null) { throw new NoInitialContextException(); } else { throw new NotContextException("Not an XXXContext"); } } return (XXXContext)answer; }
public Object XXXMethod1(Name name, ...) { throws NamingException { return getURLOrDefaultInitXXXCtx(name).XXXMethod1(name, ...); }
name
- The non-null name for which to get the context.name
or the cached initial context. The result cannot be null.NoInitialContextException
- If cannot find an initial context.NamingException
- In a naming exception is encountered.public Object lookup(String name) throws NamingException
Context
Context.lookup(Name)
for details.lookup
in interface Context
name
- the name of the object to look upname
NamingException
- if a naming exception is encounteredpublic Object lookup(Name name) throws NamingException
Context
name
is empty, returns a new instance of this context (which represents the same naming context as this context, but its environment may be modified independently and it may be accessed concurrently).lookup
in interface Context
name
- the name of the object to look upname
NamingException
- if a naming exception is encounteredpublic void bind(String name, Object obj) throws NamingException
Context
Context.bind(Name, Object)
for details.bind
in interface Context
name
- the name to bind; may not be emptyobj
- the object to bind; possibly nullNameAlreadyBoundException
- if name is already boundInvalidAttributesException
- if object did not supply all mandatory attributesNamingException
- if a naming exception is encounteredpublic void bind(Name name, Object obj) throws NamingException
Context
bind
in interface Context
name
- the name to bind; may not be emptyobj
- the object to bind; possibly nullNameAlreadyBoundException
- if name is already boundInvalidAttributesException
- if object did not supply all mandatory attributesNamingException
- if a naming exception is encounteredpublic void rebind(String name, Object obj) throws NamingException
Context
Context.rebind(Name, Object)
for details.rebind
in interface Context
name
- the name to bind; may not be emptyobj
- the object to bind; possibly nullInvalidAttributesException
- if object did not supply all mandatory attributesNamingException
- if a naming exception is encounteredpublic void rebind(Name name, Object obj) throws NamingException
Context
If the object is a DirContext
, any existing attributes associated with the name are replaced with those of the object. Otherwise, any existing attributes associated with the name remain unchanged.
rebind
in interface Context
name
- the name to bind; may not be emptyobj
- the object to bind; possibly nullInvalidAttributesException
- if object did not supply all mandatory attributesNamingException
- if a naming exception is encounteredpublic void unbind(String name) throws NamingException
Context
Context.unbind(Name)
for details.unbind
in interface Context
name
- the name to unbind; may not be emptyNameNotFoundException
- if an intermediate context does not existNamingException
- if a naming exception is encounteredpublic void unbind(Name name) throws NamingException
Context
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 is not bound in the target context, but throws NameNotFoundException
if any of the intermediate contexts do not exist.
Any attributes associated with the name are removed. Intermediate contexts are not changed.
unbind
in interface Context
name
- the name to unbind; may not be emptyNameNotFoundException
- if an intermediate context does not existNamingException
- if a naming exception is encounteredpublic void rename(String oldName, String newName) throws NamingException
Context
Context.rename(Name, Name)
for details.rename
in interface Context
oldName
- the name of the existing binding; may not be emptynewName
- the name of the new binding; may not be emptyNameAlreadyBoundException
- if newName
is already boundNamingException
- if a naming exception is encounteredpublic void rename(Name oldName, Name newName) throws NamingException
Context
rename
in interface Context
oldName
- the name of the existing binding; may not be emptynewName
- the name of the new binding; may not be emptyNameAlreadyBoundException
- if newName
is already boundNamingException
- if a naming exception is encounteredpublic NamingEnumeration<NameClassPair> list(String name) throws NamingException
Context
Context.list(Name)
for details.list
in interface Context
name
- the name of the context to listNameClassPair
.NamingException
- if a naming exception is encounteredpublic NamingEnumeration<NameClassPair> list(Name name) throws NamingException
Context
If a binding is added to or removed from this context, its effect on an enumeration previously returned is undefined.
list
in interface Context
name
- the name of the context to listNameClassPair
.NamingException
- if a naming exception is encounteredpublic NamingEnumeration<Binding> listBindings(String name) throws NamingException
Context
Context.listBindings(Name)
for details.listBindings
in interface Context
name
- the name of the context to listBinding
.NamingException
- if a naming exception is encounteredpublic NamingEnumeration<Binding> listBindings(Name name) throws NamingException
Context
If a binding is added to or removed from this context, its effect on an enumeration previously returned is undefined.
listBindings
in interface Context
name
- the name of the context to listBinding
.NamingException
- if a naming exception is encounteredpublic void destroySubcontext(String name) throws NamingException
Context
Context.destroySubcontext(Name)
for details.destroySubcontext
in interface Context
name
- the name of the context to be destroyed; may not be emptyNameNotFoundException
- if an intermediate context does not existNotContextException
- if the name is bound but does not name a context, or does not name a context of the appropriate typeContextNotEmptyException
- if the named context is not emptyNamingException
- if a naming exception is encounteredpublic void destroySubcontext(Name name) throws NamingException
Context
This method is idempotent. It succeeds even if the terminal atomic name is not bound in the target context, but throws NameNotFoundException
if any of the intermediate contexts do not exist.
In a federated naming system, a context from one naming system may be bound to a name in another. One can subsequently look up and perform operations on the foreign context using a composite name. However, an attempt destroy the context using this composite name 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 the binding of the foreign context. Destroying the foreign context requires that the destroySubcontext()
be performed on a context from the foreign context's "native" naming system.
destroySubcontext
in interface Context
name
- the name of the context to be destroyed; may not be emptyNameNotFoundException
- if an intermediate context does not existNotContextException
- if the name is bound but does not name a context, or does not name a context of the appropriate typeContextNotEmptyException
- if the named context is not emptyNamingException
- if a naming exception is encounteredpublic Context createSubcontext(String name) throws NamingException
Context
Context.createSubcontext(Name)
for details.createSubcontext
in interface Context
name
- the name of the context to create; may not be emptyNameAlreadyBoundException
- if name is already boundInvalidAttributesException
- if creation of the subcontext requires specification of mandatory attributesNamingException
- if a naming exception is encounteredpublic Context createSubcontext(Name name) throws NamingException
Context
createSubcontext
in interface Context
name
- the name of the context to create; may not be emptyNameAlreadyBoundException
- if name is already boundInvalidAttributesException
- if creation of the subcontext requires specification of mandatory attributesNamingException
- if a naming exception is encounteredpublic Object lookupLink(String name) throws NamingException
Context
Context.lookupLink(Name)
for details.lookupLink
in interface Context
name
- the name of the object to look upname
, not following the terminal link (if any)NamingException
- if a naming exception is encounteredpublic Object lookupLink(Name name) throws NamingException
Context
name
is not a link, returns the object itself.lookupLink
in interface Context
name
- the name of the object to look upname
, not following the terminal link (if any).NamingException
- if a naming exception is encounteredpublic NameParser getNameParser(String name) throws NamingException
Context
Context.getNameParser(Name)
for details.getNameParser
in interface Context
name
- the name of the context from which to get the parserNamingException
- if a naming exception is encounteredpublic NameParser getNameParser(Name name) throws NamingException
Context
NameParser
objects returned by this method must be equal (using the equals()
test).getNameParser
in interface Context
name
- the name of the context from which to get the parserNamingException
- if a naming exception is encounteredpublic String composeName(String name, String prefix) throws NamingException
prefix
parameter must be an empty name (""
).composeName
in interface Context
name
- a name relative to this contextprefix
- the name of this context relative to one of its ancestorsprefix
and name
NamingException
- if a naming exception is encounteredpublic Name composeName(Name name, Name prefix) throws NamingException
prefix
parameter must be an empty name.composeName
in interface Context
name
- a name relative to this contextprefix
- the name of this context relative to one of its ancestorsprefix
and name
NamingException
- if a naming exception is encounteredpublic Object addToEnvironment(String propName, Object propVal) throws NamingException
Context
addToEnvironment
in interface Context
propName
- the name of the environment property to add; may not be nullpropVal
- the value of the property to add; may not be nullNamingException
- if a naming exception is encounteredpublic Object removeFromEnvironment(String propName) throws NamingException
Context
removeFromEnvironment
in interface Context
propName
- the name of the environment property to remove; may not be nullNamingException
- if a naming exception is encounteredpublic Hashtable<?,?> getEnvironment() throws NamingException
Context
The caller should not make any changes to the object returned: their effect on the context is undefined. The environment of this context may be changed using addToEnvironment()
and removeFromEnvironment()
.
getEnvironment
in interface Context
NamingException
- if a naming exception is encounteredpublic void close() throws NamingException
Context
This method is idempotent: invoking it on a context that has already been closed has no effect. Invoking any other method on a closed context is not allowed, and results in undefined behaviour.
close
in interface Context
NamingException
- if a naming exception is encounteredpublic String getNameInNamespace() throws NamingException
Context
Many naming services have a notion of a "full name" for objects in their respective namespaces. For example, an LDAP entry has a distinguished name, and a DNS record has a fully qualified name. This method allows the client application to retrieve this name. The string returned by this method is not a JNDI composite name and should not be passed directly to context methods. In naming systems for which the notion of full name does not make sense, OperationNotSupportedException
is thrown.
getNameInNamespace
in interface Context
OperationNotSupportedException
- if the naming system does not have the notion of a full nameNamingException
- if a naming exception is encountered
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.naming/javax/naming/InitialContext.html