DirContext method is relative
to that context. The empty name is used to name the context itself.
The name parameter may never be null.
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 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.
See Context for a discussion on the interpretation of the
name argument to the Context methods. These same rules
apply to the name argument to the DirContext methods.
The second model is that attributes are associated with a name (typically an atomic name) in a DirContext. In this model, an attribute operation on the named object is roughly equivalent to a lookup on the name of the parent DirContext of the named object, followed by the attribute operation invoked on the parent in which the caller supplies the terminal atomic name. The attributes can be viewed as being stored in the parent DirContext (again, this does not imply that the implementation must do so). Objects that are not DirContexts can have attributes, as long as their parents are DirContexts.
JNDI support both of these models. It is up to the individual service providers to decide where to "store" attributes. JNDI clients are safest when they do not make assumptions about whether an object's attributes are stored as part of the object, or stored within the parent object and associated with the object's name.
getAttributes() and search() methods,
you can supply the attributes to return by supplying a list of
attribute names (strings).
The attributes that you get back might not have the same names as the
attribute names you have specified. This is because some directories
support features that cause them to return other attributes. Such
features include attribute subclassing, attribute name synonyms, and
attribute language codes.
In attribute subclassing, attributes are defined in a class hierarchy. In some directories, for example, the "name" attribute might be the superclass of all name-related attributes, including "commonName" and "surName". Asking for the "name" attribute might return both the "commonName" and "surName" attributes.
With attribute type synonyms, a directory can assign multiple names to the same attribute. For example, "cn" and "commonName" might both refer to the same attribute. Asking for "cn" might return the "commonName" attribute.
Some directories support the language codes for attributes. Asking such a directory for the "description" attribute, for example, might return all of the following attributes:
Some directories have the notion of "operational attributes" which are attributes associated with a directory object for administrative purposes. An example of operational attributes is the access control list for an object.
In the getAttributes() and search() methods,
you can specify that all attributes associated with the requested objects
be returned by supply null as the list of attributes to return.
The attributes returned do not include operational attributes.
In order to retrieve operational attributes, you must name them explicitly.
There are certain methods in which the name must resolve to a context
(for example, when searching a single level context). The documentation
of such methods
use the term named context to describe their name parameter.
For these methods, if the named object is not a DirContext,
NotContextException is thrown.
Aside from these methods, there is no requirement that the
named object be a DirContext.
An Attributes, SearchControls, or array object
passed as a parameter to any method will not be modified by the
service provider. The service provider may keep a reference to it
for the duration of the operation, including any enumeration of the
method's results and the processing of any referrals generated.
The caller should not modify the object during this time.
An Attributes object returned by any method is owned by
the caller. The caller may subsequently modify it; the service
provider will not.
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.
javax.naming.Context
| Modifier and Type | Field and Description |
|---|---|
| public static final int | ADD_ATTRIBUTE
This constant specifies to add an attribute with the specified values. |
| public static final int | REMOVE_ATTRIBUTE
This constant specifies to delete the specified attribute values from the attribute. |
| public static final int | REPLACE_ATTRIBUTE
This constant specifies to replace an attribute with specified values. |
| Modifier and Type | Method and Description |
|---|---|
| public void | bind(Name
the name to bind; may not be empty name, Object the object to bind; possibly null obj, Attributes the attributes to associate with the binding attrs)Binds a name to an object, along with associated attributes. |
| public void | bind(String
the name to bind; may not be empty name, Object the object to bind; possibly null obj, Attributes the attributes to associate with the binding attrs)Binds a name to an object, along with associated attributes. |
| public DirContext | Returns: the newly created contextthe name of the context to create; may not be empty name, Attributes the attributes to associate with the newly created context attrs)Creates and binds a new context, along with associated attributes. |
| public DirContext | Returns: the newly created contextthe name of the context to create; may not be empty name, Attributes the attributes to associate with the newly created context attrs)Creates and binds a new context, along with associated attributes. |
| public Attributes | Returns: the set of attributes associated withname.
Returns an empty attribute set if name has no attributes;
never null.the name of the object from which to retrieve attributes name)Retrieves all of the attributes associated with a named object. |
| public Attributes | Returns: the set of attributes associated withnamethe name of the object from which to retrieve attributes name)Retrieves all of the attributes associated with a named object. |
| public Attributes | Returns: the requested attributes; never nullthe name of the object from which to retrieve attributes name, String[] the identifiers of the attributes to retrieve.
null indicates that all attributes should be retrieved;
an empty array indicates that none should be retrieved. attrIds)Retrieves selected attributes associated with a named object. |
| public Attributes | Returns: the requested attributes; never nullThe name of the object from which to retrieve attributes name, String[] the identifiers of the attributes to retrieve.
null indicates that all attributes should be retrieved;
an empty array indicates that none should be retrieved. attrIds)Retrieves selected attributes associated with a named object. |
| public DirContext | |
| public DirContext | |
| public DirContext | Returns: theDirContext containing the named
object's class definitions; never nullthe name of the object whose object class
definition is to be retrieved name)Retrieves a context containing the schema objects of the named object's class definitions. |
| public DirContext | Returns: theDirContext containing the named
object's class definitions; never nullthe name of the object whose object class
definition is to be retrieved name)Retrieves a context containing the schema objects of the named object's class definitions. |
| public void | modifyAttributes(Name
the name of the object whose attributes will be updated name, int the modification operation, one of:
mod_op, Attributes ADD_ATTRIBUTE,
REPLACE_ATTRIBUTE,
REMOVE_ATTRIBUTE.the attributes to be used for the modification; may not be null attrs)Modifies the attributes associated with a named object. |
| public void | modifyAttributes(String
the name of the object whose attributes will be updated name, int the modification operation, one of:
mod_op, Attributes ADD_ATTRIBUTE,
REPLACE_ATTRIBUTE,
REMOVE_ATTRIBUTE.the attributes to be used for the modification; may not be null attrs)Modifies the attributes associated with a named object. |
| public void | modifyAttributes(Name
the name of the object whose attributes will be updated name, ModificationItem[] an ordered sequence of modifications to be performed;
may not be null mods)Modifies the attributes associated with a named object using an ordered list of modifications. |
| public void | modifyAttributes(String
the name of the object whose attributes will be updated name, ModificationItem[] an ordered sequence of modifications to be performed;
may not be null mods)Modifies the attributes associated with a named object using an ordered list of modifications. |
| public void | rebind(Name
the name to bind; may not be empty name, Object the object to bind; possibly null obj, Attributes the attributes to associate with the binding attrs)Binds a name to an object, along with associated attributes, overwriting any existing binding. |
| public void | rebind(String
the name to bind; may not be empty name, Object the object to bind; possibly null obj, Attributes the attributes to associate with the binding attrs)Binds a name to an object, along with associated attributes, overwriting any existing binding. |
| public NamingEnumeration | Returns: a non-null enumeration ofSearchResult objects.
Each SearchResult contains the attributes
identified by attributesToReturn
and the name of the corresponding object, named relative
to the context named by name.the name of the context to search name, Attributes the attributes to search for. If empty or null,
all objects in the target context are returned. matchingAttributes, String[] the attributes to return. null indicates that
all attributes are to be returned;
an empty array indicates that none are to be returned. attributesToReturn)Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes. |
| public NamingEnumeration | Returns: a non-null enumeration ofSearchResult objectsthe name of the context to search name, Attributes the attributes to search for matchingAttributes, String[] the attributes to return attributesToReturn)Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes. |
| public NamingEnumeration | Returns: an enumeration ofSearchResult objectsthe name of the context to search name, Attributes the attributes to search for matchingAttributes)Searches in a single context for objects that contain a specified set of attributes. |
| public NamingEnumeration | Returns: an enumeration ofSearchResult objectsthe name of the context to search name, Attributes the attributes to search for matchingAttributes)Searches in a single context for objects that contain a specified set of attributes. |
| public NamingEnumeration | Returns: an enumeration ofSearchResults of
the objects that satisfy the filter; never nullthe name of the context or object to search name, String the filter expression to use for the search; may not be null filter, SearchControls the search controls that control the search. If null,
the default search controls are used (equivalent
to cons)(new SearchControls())).Searches in the named context or object for entries that satisfy the given search filter. |
| public NamingEnumeration | Returns: an enumeration ofSearchResults for
the objects that satisfy the filter.the name of the context or object to search name, String the filter expression to use for the search; may not be null filter, SearchControls the search controls that control the search. If null,
the default search controls are used (equivalent
to cons)(new SearchControls())).Searches in the named context or object for entries that satisfy the given search filter. |
| public NamingEnumeration | Returns: an enumeration ofSearchResults of the objects
that satisfy the filter; never nullthe name of the context or object to search name, String the filter expression to use for the search.
The expression may contain variables of the
form " filterExpr, Object[] {i}" where i
is a nonnegative integer. May not be null.the array of arguments to substitute for the variables
in filterArgs, SearchControls filterExpr. The value of
filterArgs[i] will replace each
occurrence of "{i}".
If null, equivalent to an empty array.the search controls that control the search. If null,
the default search controls are used (equivalent
to cons)(new SearchControls())).Searches in the named context or object for entries that satisfy the given search filter. |
| public NamingEnumeration | Returns: an enumeration ofSearchResults of the objects
that satisfy the filter; never nullthe name of the context or object to search name, String the filter expression to use for the search.
The expression may contain variables of the
form " filterExpr, Object[] {i}" where i
is a nonnegative integer. May not be null.the array of arguments to substitute for the variables
in filterArgs, SearchControls filterExpr. The value of
filterArgs[i] will replace each
occurrence of "{i}".
If null, equivalent to an empty array.the search controls that control the search. If null,
the default search controls are used (equivalent
to cons)(new SearchControls())).Searches in the named context or object for entries that satisfy the given search filter. |
| ADD_ATTRIBUTE | back to summary |
|---|---|
| public static final int ADD_ATTRIBUTE This constant specifies to add an attribute with the specified values.
If attribute does not exist,
create the attribute. The resulting attribute has a union of the
specified value set and the prior value set.
Adding an attribute with no value will throw
The value of this constant is
| |
| REMOVE_ATTRIBUTE | back to summary |
|---|---|
| public static final int REMOVE_ATTRIBUTE This constant specifies to delete the specified attribute values from the attribute. The resulting attribute has the set difference of its prior value set and the specified value set. If no values are specified, deletes the entire attribute. If the attribute does not exist, or if some or all members of the specified value set do not exist, this absence may be ignored and the operation succeeds, or a NamingException may be thrown to indicate the absence. Removal of the last value will remove the attribute if the attribute is required to have at least one value.
The value of this constant is
| |
| REPLACE_ATTRIBUTE | back to summary |
|---|---|
| public static final int REPLACE_ATTRIBUTE This constant specifies to replace an attribute with specified values.
If attribute already exists,
replaces all existing values with new specified values. If the
attribute does not exist, creates it. If no value is specified,
deletes all the values of the attribute.
Removal of the last value will remove the attribute if the attribute
is required to have at least one value. If
attempting to add more than one value to a single-valued attribute,
throws
The value of this constant is
| |
| bind | back to summary |
|---|---|
| public void bind(Name name, Object obj, Attributes attrs) throws NamingException Binds a name to an object, along with associated attributes.
If
| |
| bind | back to summary |
|---|---|
| public void bind(String name, Object obj, Attributes attrs) throws NamingException Binds a name to an object, along with associated attributes.
See
| |
| createSubcontext | back to summary |
|---|---|
| public DirContext createSubcontext(Name name, Attributes attrs) throws NamingException Creates and binds a new context, along with associated attributes.
This method creates a new subcontext with the given name, binds it in
the target context (that named by all but terminal atomic
component of the name), and associates the supplied attributes
with the newly created object.
All intermediate and target contexts must already exist.
If
| |
| createSubcontext | back to summary |
|---|---|
| public DirContext createSubcontext(String name, Attributes attrs) throws NamingException Creates and binds a new context, along with associated attributes.
See
| |
| getAttributes | back to summary |
|---|---|
| public Attributes getAttributes(Name name) throws NamingException Retrieves all of the attributes associated with a named object. See the class description regarding attribute models, attribute type names, and operational attributes.
| |
| getAttributes | back to summary |
|---|---|
| public Attributes getAttributes(String name) throws NamingException Retrieves all of the attributes associated with a named object.
See
| |
| getAttributes | back to summary |
|---|---|
| public Attributes getAttributes(Name name, String[] attrIds) throws NamingException Retrieves selected attributes associated with a named object. See the class description regarding attribute models, attribute type names, and operational attributes. 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 | back to summary |
|---|---|
| public Attributes getAttributes(String name, String[] attrIds) throws NamingException Retrieves selected attributes associated with a named object.
See
| |
| getSchema | back to summary |
|---|---|
| public DirContext getSchema(Name name) throws NamingException Retrieves the schema associated with the named object. The schema describes rules regarding the structure of the namespace and the attributes stored within it. The schema specifies what types of objects can be added to the directory and where they can be added; what mandatory and optional attributes an object can have. The range of support for schemas is directory-specific. 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 | back to summary |
|---|---|
| public DirContext getSchema(String name) throws NamingException Retrieves the schema associated with the named object.
See
| |
| getSchemaClassDefinition | back to summary |
|---|---|
| public DirContext getSchemaClassDefinition(Name name) throws NamingException Retrieves a context containing the schema objects of the named object's class definitions.
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, 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
| |
| getSchemaClassDefinition | back to summary |
|---|---|
| public DirContext getSchemaClassDefinition(String name) throws NamingException Retrieves a context containing the schema objects of the
named object's class definitions.
See
| |
| modifyAttributes | back to summary |
|---|---|
| public void modifyAttributes(Name name, int mod_op, Attributes attrs) throws NamingException Modifies the attributes associated with a named object. The order of the modifications is not specified. Where possible, the modifications are performed atomically.
| |
| modifyAttributes | back to summary |
|---|---|
| public void modifyAttributes(String name, int mod_op, Attributes attrs) throws NamingException Modifies the attributes associated with a named object.
See
| |
| modifyAttributes | back to summary |
|---|---|
| public void modifyAttributes(Name name, ModificationItem[] mods) throws NamingException Modifies the attributes associated with a named object using an ordered list of modifications. The modifications are performed in the order specified. Each modification specifies a modification operation code and an attribute on which to operate. Where possible, the modifications are performed atomically.
| |
| modifyAttributes | back to summary |
|---|---|
| public void modifyAttributes(String name, ModificationItem[] mods) throws NamingException Modifies the attributes associated with a named object using
an ordered list of modifications.
See
| |
| rebind | back to summary |
|---|---|
| public void rebind(Name name, Object obj, Attributes attrs) throws NamingException Binds a name to an object, along with associated attributes,
overwriting any existing binding.
If
| |
| rebind | back to summary |
|---|---|
| public void rebind(String name, Object obj, Attributes attrs) throws NamingException Binds a name to an object, along with associated attributes,
overwriting any existing binding.
See
| |
| search | back to summary |
|---|---|
| public NamingEnumeration Searches in a single context for objects that contain a
specified set of attributes, and retrieves selected attributes.
The search is performed using the default
For an object to be selected, each attribute in
An attribute A1 in
The precise definition of "equality" used in comparing attribute values
is defined by the underlying directory service. It might use the
When changes are made to this 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 | back to summary |
|---|---|
| public NamingEnumeration Searches in a single context for objects that contain a
specified set of attributes, and retrieves selected attributes.
See
| |
| search | back to summary |
|---|---|
| public NamingEnumeration Searches in a single context for objects that contain a
specified set of attributes.
This method returns all the attributes of such objects.
It is equivalent to supplying null as
the
| |
| search | back to summary |
|---|---|
| public NamingEnumeration Searches in a single context for objects that contain a
specified set of attributes.
See
| |
| search | back to summary |
|---|---|
| public NamingEnumeration Searches in the named context or object for entries that satisfy the given search filter. Performs the search as specified by the search controls.
The format and interpretation of
For the assertion "someCount=127", for example, 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 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
The result is returned in an enumeration of 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 | back to summary |
|---|---|
| public NamingEnumeration Searches in the named context or object for entries that satisfy the
given search filter. Performs the search as specified by
the search controls.
See
| |
| search | back to summary |
|---|---|
| public NamingEnumeration Searches in the named context or object for entries that satisfy the given search filter. Performs the search as specified by the search controls.
The interpretation of
When a variable 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
The 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 | back to summary |
|---|---|
| public NamingEnumeration Searches in the named context or object for entries that satisfy the
given search filter. Performs the search as specified by
the search controls.
See
| |