Context
, DirContext
InitialLdapContext
public class InitialDirContext extends InitialContext implements DirContext
defaultInitCtx, gotDefault, myProps
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
ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE
Modifier | Constructor | Description |
---|---|---|
Constructs an initial DirContext. |
||
protected |
Constructs an initial DirContext with the option of not initializing it. |
|
Constructs an initial DirContext using the supplied environment. |
Modifier and Type | Method | Description |
---|---|---|
void |
bind |
Binds a name to an object, along with associated attributes. |
void |
bind |
Binds a name to an object, along with associated attributes. |
DirContext |
createSubcontext |
Creates and binds a new context, along with associated attributes. |
DirContext |
createSubcontext |
Creates and binds a new context, along with associated attributes. |
Attributes |
getAttributes |
Retrieves all of the attributes associated with a named object. |
Attributes |
getAttributes |
Retrieves selected attributes associated with a named object. |
Attributes |
getAttributes |
Retrieves all of the attributes associated with a named object. |
Attributes |
getAttributes |
Retrieves selected attributes associated with a named object. |
DirContext |
getSchema |
Retrieves the schema associated with the named object. |
DirContext |
getSchema |
Retrieves the schema associated with the named object. |
DirContext |
getSchemaClassDefinition |
Retrieves a context containing the schema objects of the named object's class definitions. |
DirContext |
getSchemaClassDefinition |
Retrieves a context containing the schema objects of the named object's class definitions. |
void |
modifyAttributes |
Modifies the attributes associated with a named object. |
void |
modifyAttributes |
Modifies the attributes associated with a named object using an ordered list of modifications. |
void |
modifyAttributes |
Modifies the attributes associated with a named object. |
void |
modifyAttributes |
Modifies the attributes associated with a named object using an ordered list of modifications. |
void |
rebind |
Binds a name to an object, along with associated attributes, overwriting any existing binding. |
void |
rebind |
Binds a name to an object, along with associated attributes, overwriting any existing binding. |
NamingEnumeration |
search |
Searches in the named context or object for entries that satisfy the given search filter. |
NamingEnumeration |
search |
Searches in the named context or object for entries that satisfy the given search filter. |
NamingEnumeration |
search |
Searches in a single context for objects that contain a specified set of attributes. |
NamingEnumeration |
search |
Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes. |
NamingEnumeration |
search |
Searches in the named context or object for entries that satisfy the given search filter. |
NamingEnumeration |
search |
Searches in the named context or object for entries that satisfy the given search filter. |
NamingEnumeration |
search |
Searches in a single context for objects that contain a specified set of attributes. |
NamingEnumeration |
search |
Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes. |
addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, doLookup, doLookup, getDefaultInitCtx, getEnvironment, getNameInNamespace, getNameParser, getNameParser, getURLOrDefaultInitCtx, getURLOrDefaultInitCtx, init, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getEnvironment, getNameInNamespace, getNameParser, getNameParser, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind
protected InitialDirContext(boolean lazy) throws NamingException
InitialDirContext
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 DirContext; false is equivalent to calling new InitialDirContext()
NamingException
- if a naming exception is encounteredpublic InitialDirContext() throws NamingException
new InitialDirContext(null)
.NamingException
- if a naming exception is encounteredpublic InitialDirContext(Hashtable<?,?> environment) throws NamingException
javax.naming.InitialContext
class description. If the java.naming.provider.url
property of the supplied environment consists of a URL (or a list of URLs) using the ldap protocol the resulting LdapContext
will use an LDAP server resolved by the configured LdapDnsProviders
:
InitialDirContext
created with a java.naming.provider.url
using the ldap protocol then the ServiceLoader mechanism is used to locate LdapDnsProvider implementations using the system class loader. The order that providers are located is implementation specific and an implementation is free to cache the located providers. lookupEndpoints
method of each provider, if instantiated, is invoked once with a combination of each of the URLs in the java.naming.provider.url
property and the environment until a provider returns non-empty or all providers have been exhausted. If none of the LdapDnsProviders return a non-empty result then the implementation will make a best-effort attempt to determine an endpoint. A ServiceConfigurationError, Error
or RuntimeException
thrown when loading or calling an LdapDnsProvider, if encountered, will be propagated to the calling thread. 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 DirContext. Null indicates an empty environment.NamingException
- if a naming exception is encounteredpublic Attributes getAttributes(String name) throws NamingException
DirContext
DirContext.getAttributes(Name)
for details.getAttributes
in interface DirContext
name
- the name of the object from which to retrieve attributesname
NamingException
- if a naming exception is encounteredpublic Attributes getAttributes(String name, String[] attrIds) throws NamingException
DirContext
DirContext.getAttributes(Name, String[])
for details.getAttributes
in interface DirContext
name
- The name of the object from which to retrieve attributesattrIds
- the identifiers of the attributes to retrieve. null indicates that all attributes should be retrieved; an empty array indicates that none should be retrieved.NamingException
- if a naming exception is encounteredpublic Attributes getAttributes(Name name) throws NamingException
DirContext
getAttributes
in interface DirContext
name
- the name of the object from which to retrieve attributesname
. Returns an empty attribute set if name has no attributes; never null.NamingException
- if a naming exception is encounteredpublic Attributes getAttributes(Name name, String[] attrIds) throws NamingException
DirContext
If the object does not have an attribute specified, the directory will ignore the nonexistent attribute and return those requested attributes that the object does have.
A directory might return more attributes than was requested (see Attribute Type Names in the class description), but is not allowed to return arbitrary, unrelated attributes.
See also Operational Attributes in the class description.
getAttributes
in interface DirContext
name
- the name of the object from which to retrieve attributesattrIds
- the identifiers of the attributes to retrieve. null indicates that all attributes should be retrieved; an empty array indicates that none should be retrieved.NamingException
- if a naming exception is encounteredpublic void modifyAttributes(String name, int mod_op, Attributes attrs) throws NamingException
DirContext
DirContext.modifyAttributes(Name, int, Attributes)
for details.modifyAttributes
in interface DirContext
name
- the name of the object whose attributes will be updatedmod_op
- the modification operation, one of: ADD_ATTRIBUTE
, REPLACE_ATTRIBUTE
, REMOVE_ATTRIBUTE
.attrs
- the attributes to be used for the modification; may not be nullAttributeModificationException
- if the modification cannot be completed successfullyNamingException
- if a naming exception is encounteredpublic void modifyAttributes(Name name, int mod_op, Attributes attrs) throws NamingException
DirContext
modifyAttributes
in interface DirContext
name
- the name of the object whose attributes will be updatedmod_op
- the modification operation, one of: ADD_ATTRIBUTE
, REPLACE_ATTRIBUTE
, REMOVE_ATTRIBUTE
.attrs
- the attributes to be used for the modification; may not be nullAttributeModificationException
- if the modification cannot be completed successfullyNamingException
- if a naming exception is encounteredpublic void modifyAttributes(String name, ModificationItem[] mods) throws NamingException
DirContext
DirContext.modifyAttributes(Name, ModificationItem[])
for details.modifyAttributes
in interface DirContext
name
- the name of the object whose attributes will be updatedmods
- an ordered sequence of modifications to be performed; may not be nullAttributeModificationException
- if the modifications cannot be completed successfullyNamingException
- if a naming exception is encounteredpublic void modifyAttributes(Name name, ModificationItem[] mods) throws NamingException
DirContext
modifyAttributes
in interface DirContext
name
- the name of the object whose attributes will be updatedmods
- an ordered sequence of modifications to be performed; may not be nullAttributeModificationException
- if the modifications cannot be completed successfullyNamingException
- if a naming exception is encounteredpublic void bind(String name, Object obj, Attributes attrs) throws NamingException
DirContext
DirContext.bind(Name, Object, Attributes)
for details.bind
in interface DirContext
name
- the name to bind; may not be emptyobj
- the object to bind; possibly nullattrs
- the attributes to associate with the bindingNameAlreadyBoundException
- if name is already boundInvalidAttributesException
- if some "mandatory" attributes of the binding are not suppliedNamingException
- if a naming exception is encounteredpublic void bind(Name name, Object obj, Attributes attrs) throws NamingException
DirContext
attrs
is null, the resulting binding will have the attributes associated with obj
if obj
is a DirContext
, and no attributes otherwise. If attrs
is non-null, the resulting binding will have attrs
as its attributes; any attributes associated with obj
are ignored.bind
in interface DirContext
name
- the name to bind; may not be emptyobj
- the object to bind; possibly nullattrs
- the attributes to associate with the bindingNameAlreadyBoundException
- if name is already boundInvalidAttributesException
- if some "mandatory" attributes of the binding are not suppliedNamingException
- if a naming exception is encounteredpublic void rebind(String name, Object obj, Attributes attrs) throws NamingException
DirContext
DirContext.rebind(Name, Object, Attributes)
for details.rebind
in interface DirContext
name
- the name to bind; may not be emptyobj
- the object to bind; possibly nullattrs
- the attributes to associate with the bindingInvalidAttributesException
- if some "mandatory" attributes of the binding are not suppliedNamingException
- if a naming exception is encounteredpublic void rebind(Name name, Object obj, Attributes attrs) throws NamingException
DirContext
attrs
is null and obj
is a DirContext
, the attributes from obj
are used. If attrs
is null and obj
is not a DirContext
, any existing attributes associated with the object already bound in the directory remain unchanged. If attrs
is non-null, any existing attributes associated with the object already bound in the directory are removed and attrs
is associated with the named object. If obj
is a DirContext
and attrs
is non-null, the attributes of obj
are ignored.rebind
in interface DirContext
name
- the name to bind; may not be emptyobj
- the object to bind; possibly nullattrs
- the attributes to associate with the bindingInvalidAttributesException
- if some "mandatory" attributes of the binding are not suppliedNamingException
- if a naming exception is encounteredpublic DirContext createSubcontext(String name, Attributes attrs) throws NamingException
DirContext
DirContext.createSubcontext(Name, Attributes)
for details.createSubcontext
in interface DirContext
name
- the name of the context to create; may not be emptyattrs
- the attributes to associate with the newly created contextNameAlreadyBoundException
- if the name is already boundInvalidAttributesException
- if attrs
does not contain all the mandatory attributes required for creationNamingException
- if a naming exception is encounteredpublic DirContext createSubcontext(Name name, Attributes attrs) throws NamingException
DirContext
attrs
is null, this method is equivalent to Context.createSubcontext()
.createSubcontext
in interface DirContext
name
- the name of the context to create; may not be emptyattrs
- the attributes to associate with the newly created contextNameAlreadyBoundException
- if the name is already boundInvalidAttributesException
- if attrs
does not contain all the mandatory attributes required for creationNamingException
- if a naming exception is encounteredpublic DirContext getSchema(String name) throws NamingException
DirContext
DirContext.getSchema(Name)
for details.getSchema
in interface DirContext
name
- the name of the object whose schema is to be retrievedOperationNotSupportedException
- if schema not supportedNamingException
- if a naming exception is encounteredpublic DirContext getSchema(Name name) throws NamingException
DirContext
This method returns the root of the schema information tree that is applicable to the named object. Several named objects (or even an entire directory) might share the same schema.
Issues such as structure and contents of the schema tree, permission to modify to the contents of the schema tree, and the effect of such modifications on the directory are dependent on the underlying directory.
getSchema
in interface DirContext
name
- the name of the object whose schema is to be retrievedOperationNotSupportedException
- if schema not supportedNamingException
- if a naming exception is encounteredpublic DirContext getSchemaClassDefinition(String name) throws NamingException
DirContext
DirContext.getSchemaClassDefinition(Name)
for details.getSchemaClassDefinition
in interface DirContext
name
- the name of the object whose object class definition is to be retrievedDirContext
containing the named object's class definitions; never nullOperationNotSupportedException
- if schema not supportedNamingException
- if a naming exception is encounteredpublic DirContext getSchemaClassDefinition(Name name) throws NamingException
DirContext
One category of information found in directory schemas is class definitions. An "object class" definition specifies the object's type and what attributes (mandatory and optional) the object must/can have. Note that the term "object class" being referred to here is in the directory sense rather than in the Java sense. For example, if the named object is a directory object of "Person" class, getSchemaClassDefinition()
would return a DirContext
representing the (directory's) object class definition of "Person".
The information that can be retrieved from an object class definition is directory-dependent.
Prior to JNDI 1.2, this method returned a single schema object representing the class definition of the named object. Since JNDI 1.2, this method returns a DirContext
containing all of the named object's class definitions.
getSchemaClassDefinition
in interface DirContext
name
- the name of the object whose object class definition is to be retrievedDirContext
containing the named object's class definitions; never nullOperationNotSupportedException
- if schema not supportedNamingException
- if a naming exception is encounteredpublic NamingEnumeration<SearchResult> search(String name, Attributes matchingAttributes) throws NamingException
DirContext
DirContext.search(Name, Attributes)
for details.search
in interface DirContext
name
- the name of the context to searchmatchingAttributes
- the attributes to search forSearchResult
objectsNamingException
- if a naming exception is encounteredpublic NamingEnumeration<SearchResult> search(Name name, Attributes matchingAttributes) throws NamingException
DirContext
attributesToReturn
parameter to the method search(Name, Attributes, String[])
. DirContext.search(Name, Attributes, String[])
for a full description.search
in interface DirContext
name
- the name of the context to searchmatchingAttributes
- the attributes to search forSearchResult
objectsNamingException
- if a naming exception is encounteredpublic NamingEnumeration<SearchResult> search(String name, Attributes matchingAttributes, String[] attributesToReturn) throws NamingException
DirContext
DirContext.search(Name, Attributes, String[])
for details.search
in interface DirContext
name
- the name of the context to searchmatchingAttributes
- the attributes to search forattributesToReturn
- the attributes to returnSearchResult
objectsNamingException
- if a naming exception is encounteredpublic NamingEnumeration<SearchResult> search(Name name, Attributes matchingAttributes, String[] attributesToReturn) throws NamingException
DirContext
SearchControls
settings. For an object to be selected, each attribute in matchingAttributes
must match some attribute of the object. If matchingAttributes
is empty or null, all objects in the target context are returned.
An attribute A1 in matchingAttributes
is considered to match an attribute A2 of an object if A1 and A2 have the same identifier, and each value of A1 is equal to some value of A2. This implies that the order of values is not significant, and that A2 may contain "extra" values not found in A1 without affecting the comparison. It also implies that if A1 has no values, then testing for a match is equivalent to testing for the presence of an attribute A2 with the same identifier.
The precise definition of "equality" used in comparing attribute values is defined by the underlying directory service. It might use the Object.equals
method, for example, or might use a schema to specify a different equality operation. For matching based on operations other than equality (such as substring comparison) use the version of the search
method that takes a filter argument.
When changes are made to this DirContext
, the effect on enumerations returned by prior calls to this method is undefined.
If the object does not have the attribute specified, the directory will ignore the nonexistent attribute and return the requested attributes that the object does have.
A directory might return more attributes than was requested (see Attribute Type Names in the class description), but is not allowed to return arbitrary, unrelated attributes.
See also Operational Attributes in the class description.
search
in interface DirContext
name
- the name of the context to searchmatchingAttributes
- the attributes to search for. If empty or null, all objects in the target context are returned.attributesToReturn
- the attributes to return. null indicates that all attributes are to be returned; an empty array indicates that none are to be returned.SearchResult
objects. Each SearchResult
contains the attributes identified by attributesToReturn
and the name of the corresponding object, named relative to the context named by name
.NamingException
- if a naming exception is encounteredpublic NamingEnumeration<SearchResult> search(String name, String filter, SearchControls cons) throws NamingException
DirContext
DirContext.search(Name, String, SearchControls)
for details.search
in interface DirContext
name
- the name of the context or object to searchfilter
- the filter expression to use for the search; may not be nullcons
- the search controls that control the search. If null, the default search controls are used (equivalent to (new SearchControls())
).SearchResult
s for the objects that satisfy the filter.InvalidSearchFilterException
- if the search filter specified is not supported or understood by the underlying directoryInvalidSearchControlsException
- if the search controls contain invalid settingsNamingException
- if a naming exception is encounteredpublic NamingEnumeration<SearchResult> search(Name name, String filter, SearchControls cons) throws NamingException
DirContext
The format and interpretation of filter
follows RFC 2254 with the following interpretations for attr
and value
mentioned in the RFC.
attr
is the attribute's identifier.
value
is the string representation the attribute's value. The translation of this string representation into the attribute's value is directory-specific.
For the assertion "someCount=127", for example, attr
is "someCount" and value
is "127". The provider determines, based on the attribute ID ("someCount") (and possibly its schema), that the attribute's value is an integer. It then parses the string "127" appropriately.
Any non-ASCII characters in the filter string should be represented by the appropriate Java (Unicode) characters, and not encoded as UTF-8 octets. Alternately, the "backslash-hexcode" notation described in RFC 2254 may be used.
If the directory does not support a string representation of some or all of its attributes, the form of search
that accepts filter arguments in the form of Objects can be used instead. The service provider for such a directory would then translate the filter arguments to its service-specific representation for filter evaluation. See search(Name, String, Object[], SearchControls)
.
RFC 2254 defines certain operators for the filter, including substring matches, equality, approximate match, greater than, less than. These operators are mapped to operators with corresponding semantics in the underlying directory. For example, for the equals operator, suppose the directory has a matching rule defining "equality" of the attributes in the filter. This rule would be used for checking equality of the attributes specified in the filter with the attributes of objects in the directory. Similarly, if the directory has a matching rule for ordering, this rule would be used for making "greater than" and "less than" comparisons.
Not all of the operators defined in RFC 2254 are applicable to all attributes. When an operator is not applicable, the exception InvalidSearchFilterException
is thrown.
The result is returned in an enumeration of SearchResult
s. Each SearchResult
contains the name of the object and other information about the object (see SearchResult). The name is either relative to the target context of the search (which is named by the name
parameter), or it is a URL string. If the target context is included in the enumeration (as is possible when cons
specifies a search scope of SearchControls.OBJECT_SCOPE
or SearchControls.SUBSTREE_SCOPE
), its name is the empty string. The SearchResult
may also contain attributes of the matching object if the cons
argument specified that attributes be returned.
If the object does not have a requested attribute, that nonexistent attribute will be ignored. Those requested attributes that the object does have will be returned.
A directory might return more attributes than were requested (see Attribute Type Names in the class description) but is not allowed to return arbitrary, unrelated attributes.
See also Operational Attributes in the class description.
search
in interface DirContext
name
- the name of the context or object to searchfilter
- the filter expression to use for the search; may not be nullcons
- the search controls that control the search. If null, the default search controls are used (equivalent to (new SearchControls())
).SearchResult
s of the objects that satisfy the filter; never nullInvalidSearchFilterException
- if the search filter specified is not supported or understood by the underlying directoryInvalidSearchControlsException
- if the search controls contain invalid settingsNamingException
- if a naming exception is encounteredpublic NamingEnumeration<SearchResult> search(String name, String filterExpr, Object[] filterArgs, SearchControls cons) throws NamingException
DirContext
DirContext.search(Name, String, Object[], SearchControls)
for details.search
in interface DirContext
name
- the name of the context or object to searchfilterExpr
- the filter expression to use for the search. The expression may contain variables of the form "{i}
" where i
is a nonnegative integer. May not be null.filterArgs
- the array of arguments to substitute for the variables in filterExpr
. The value of filterArgs[i]
will replace each occurrence of "{i}
". If null, equivalent to an empty array.cons
- the search controls that control the search. If null, the default search controls are used (equivalent to (new SearchControls())
).SearchResult
s of the objects that satisfy the filter; never nullInvalidSearchControlsException
- if cons
contains invalid settingsInvalidSearchFilterException
- if filterExpr
with filterArgs
represents an invalid search filterNamingException
- if a naming exception is encounteredpublic NamingEnumeration<SearchResult> search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons) throws NamingException
DirContext
The interpretation of filterExpr
is based on RFC 2254. It may additionally contain variables of the form {i}
-- where i
is an integer -- that refer to objects in the filterArgs
array. The interpretation of filterExpr
is otherwise identical to that of the filter
parameter of the method search(Name, String, SearchControls)
.
When a variable {i}
appears in a search filter, it indicates that the filter argument filterArgs[i]
is to be used in that place. Such variables may be used wherever an attr, value, or matchingrule production appears in the filter grammar of RFC 2254, section 4. When a string-valued filter argument is substituted for a variable, the filter is interpreted as if the string were given in place of the variable, with any characters having special significance within filters (such as '*'
) having been escaped according to the rules of RFC 2254.
For directories that do not use a string representation for some or all of their attributes, the filter argument corresponding to an attribute value may be of a type other than String. Directories that support unstructured binary-valued attributes, for example, should accept byte arrays as filter arguments. The interpretation (if any) of filter arguments of any other type is determined by the service provider for that directory, which maps the filter operations onto operations with corresponding semantics in the underlying directory.
This method returns an enumeration of the results. Each element in the enumeration contains the name of the object and other information about the object (see SearchResult
). The name is either relative to the target context of the search (which is named by the name
parameter), or it is a URL string. If the target context is included in the enumeration (as is possible when cons
specifies a search scope of SearchControls.OBJECT_SCOPE
or SearchControls.SUBSTREE_SCOPE
), its name is the empty string.
The SearchResult
may also contain attributes of the matching object if the cons
argument specifies that attributes be returned.
If the object does not have a requested attribute, that nonexistent attribute will be ignored. Those requested attributes that the object does have will be returned.
A directory might return more attributes than were requested (see Attribute Type Names in the class description) but is not allowed to return arbitrary, unrelated attributes.
If a search filter with invalid variable substitutions is provided to this method, the result is undefined. When changes are made to this DirContext, the effect on enumerations returned by prior calls to this method is undefined.
See also Operational Attributes in the class description.
search
in interface DirContext
name
- the name of the context or object to searchfilterExpr
- the filter expression to use for the search. The expression may contain variables of the form "{i}
" where i
is a nonnegative integer. May not be null.filterArgs
- the array of arguments to substitute for the variables in filterExpr
. The value of filterArgs[i]
will replace each occurrence of "{i}
". If null, equivalent to an empty array.cons
- the search controls that control the search. If null, the default search controls are used (equivalent to (new SearchControls())
).SearchResult
s of the objects that satisfy the filter; never nullInvalidSearchControlsException
- if cons
contains invalid settingsInvalidSearchFilterException
- if filterExpr
with filterArgs
represents an invalid search filterNamingException
- 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/directory/InitialDirContext.html