There are two types of request controls:
Unless explicitly qualified, the term "request controls" refers to context request controls.
Unlike environment properties, request controls of a context instance are not inherited by context instances that are derived from it. Derived context instances have null as their context request controls. You must set the request controls of a derived context instance explicitly using setRequestControls().
A context instance's request controls are retrieved using the method getRequestControls().
Like environment properties, connection request controls of a context are inherited by contexts that are derived from it. Typically, you initialize the connection request controls using the InitialLdapContext constructor or LdapReferralContext.getReferralContext(). These connection request controls are inherited by contexts that share the same connection--that is, contexts derived from the initial or referral contexts.
Use reconnect() to change the connection request controls of a context. Invoking ldapContext.reconnect() affects only the connection used by ldapContext and any new contexts instances that are derived form ldapContext. Contexts that previously shared the connection with ldapContext remain unchanged. That is, a context's connection request controls must be explicitly changed and is not affected by changes to another context's connection request controls.
A context instance's connection request controls are retrieved using the method getConnectControls().
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
InvalidAttributeValueException if the attribute must have
at least one value. For a single-valued attribute where that attribute
already exists, throws AttributeInUseException.
If attempting to add more than one value to a single-valued attribute,
throws InvalidAttributeValueException.
The value of this constant is 1.
The value of this constant is "java.naming.factory.control".
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 3.
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 InvalidAttributeValueException.
The value of this constant is 2.
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.
These response controls might have been generated by a successful or failed operation.
When a context method that may return response controls is invoked, response controls from the previous method invocation are cleared. getResponseControls() returns all of the response controls generated by LDAP operations used by the context method in the order received from the LDAP server. Invoking getResponseControls() does not clear the response controls. You can call it many times (and get back the same controls) until the next context method that may return controls is invoked.
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.
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.
The new context has the same environment properties and connection request controls as this context. See the class description for details. Implementations might also allow this context and the new context to share the same network connection or other resources if doing so does not impede the independence of either context.
This method is a way to explicitly initiate an LDAP "bind" operation. For example, you can use this method to set request controls for the LDAP "bind" operation, or to explicitly connect to the server to get response controls returned by the LDAP "bind" operation.
This method sets this context's connCtls to be its new connection request controls. This context's context request controls are not affected. After this method has been invoked, any subsequent implicit reconnections will be done using connCtls. connCtls are also used as connection request controls for new context instances derived from this context. These connection request controls are not affected by setRequestControls().
Service provider implementors should read the "Service Provider" section in the class description for implementation details.
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.
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.
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 SearchResults.
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.
This removes any previous request controls and adds requestControls for use by subsequent methods invoked on this context. This method does not affect this context's connection request controls.
Note that requestControls will be in effect until the next invocation of setRequestControls(). You need to explicitly invoke setRequestControls() with null or an empty array to clear the controls if you don't want them to affect the context methods any more. To check what request controls are in effect for this context, use getRequestControls().