@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class MatchedValuesRequestControl extends Control
MatchedValuesFilters should be included in matching entries. That
is, this control may be used to restrict the set of values included in the
entries that are returned. This is particularly useful for multivalued
attributes with a large number of values when only a small number of values
are of interest to the client.
description" attribute
to be returned in which those values start with the letter f:
// Ensure that a test user has multiple description values.
LDAPResult modifyResult = connection.modify(
"uid=test.user,ou=People,dc=example,dc=com",
new Modification(ModificationType.REPLACE,
"description", // Attribute name
"first", "second", "third", "fourth")); // Attribute values.
assertResultCodeEquals(modifyResult, ResultCode.SUCCESS);
// Perform a search to retrieve the test user entry without using the
// matched values request control. This should return all four description
// values.
SearchRequest searchRequest = new SearchRequest(
"uid=test.user,ou=People,dc=example,dc=com", // Base DN
SearchScope.BASE, // Scope
Filter.createPresenceFilter("objectClass"), // Filter
"description"); // Attributes to return.
SearchResultEntry entryRetrievedWithoutControl =
connection.searchForEntry(searchRequest);
Attribute fullDescriptionAttribute =
entryRetrievedWithoutControl.getAttribute("description");
int numFullDescriptionValues = fullDescriptionAttribute.size();
// Update the search request to include a matched values control that will
// only return values that start with the letter "f". In our test entry,
// this should just match two values ("first" and "fourth").
searchRequest.addControl(new MatchedValuesRequestControl(
MatchedValuesFilter.createSubstringFilter("description", // Attribute
"f", // subInitial component
null, // subAny components
null))); // subFinal component
SearchResultEntry entryRetrievedWithControl =
connection.searchForEntry(searchRequest);
Attribute partialDescriptionAttribute =
entryRetrievedWithControl.getAttribute("description");
int numPartialDescriptionValues = partialDescriptionAttribute.size();
| Modifier and Type | Field and Description |
|---|---|
static java.lang.String |
MATCHED_VALUES_REQUEST_OID
The OID (1.2.826.0.1.3344810.2.3) for the matched values request control.
|
| Constructor and Description |
|---|
MatchedValuesRequestControl(boolean isCritical,
java.util.List<MatchedValuesFilter> filters)
Creates a new matched values request control with the provided criticality
and set of filters.
|
MatchedValuesRequestControl(boolean isCritical,
MatchedValuesFilter... filters)
Creates a new matched values request control with the provided criticality
and set of filters.
|
MatchedValuesRequestControl(Control control)
Creates a new matched values request control which is decoded from the
provided generic control.
|
MatchedValuesRequestControl(java.util.List<MatchedValuesFilter> filters)
Creates a new matched values request control with the provided set of
filters.
|
MatchedValuesRequestControl(MatchedValuesFilter... filters)
Creates a new matched values request control with the provided set of
filters.
|
| Modifier and Type | Method and Description |
|---|---|
static MatchedValuesRequestControl |
decodeJSONControl(JSONObject controlObject,
boolean strict)
Attempts to decode the provided object as a JSON representation of a
matched values request control.
|
java.lang.String |
getControlName()
Retrieves the user-friendly name for this control, if available.
|
MatchedValuesFilter[] |
getFilters()
Retrieves the set of filters for this matched values request control.
|
JSONObject |
toJSONControl()
Retrieves a representation of this matched values request control as a JSON
object.
|
void |
toString(java.lang.StringBuilder buffer)
Appends a string representation of this LDAP control to the provided
buffer.
|
decode, decode, decodeControls, decodeJSONControl, deregisterDecodeableControl, encode, encodeControls, equals, getOID, getValue, hashCode, hasValue, isCritical, readFrom, registerDecodeableControl, registerDecodeableControl, toString, writeTo@NotNull public static final java.lang.String MATCHED_VALUES_REQUEST_OID
public MatchedValuesRequestControl(@NotNull MatchedValuesFilter... filters)
filters - The set of filters to use for this control. At least one
filter must be provided.public MatchedValuesRequestControl(@NotNull java.util.List<MatchedValuesFilter> filters)
filters - The set of filters to use for this control. At least one
filter must be provided.public MatchedValuesRequestControl(boolean isCritical, @NotNull MatchedValuesFilter... filters)
isCritical - Indicates whether this control should be marked
critical.filters - The set of filters to use for this control. At least
one filter must be provided.public MatchedValuesRequestControl(boolean isCritical, @NotNull java.util.List<MatchedValuesFilter> filters)
isCritical - Indicates whether this control should be marked
critical.filters - The set of filters to use for this control. At least
one filter must be provided.public MatchedValuesRequestControl(@NotNull Control control) throws LDAPException
control - The generic control to be decoded as a matched values
request control.LDAPException - If the provided control cannot be decoded as a
matched values request control.@NotNull public MatchedValuesFilter[] getFilters()
@NotNull public java.lang.String getControlName()
getControlName in class Control@NotNull public JSONObject toJSONControl()
oid -- A mandatory string field whose value is the object
identifier for this control. For the matched values request control,
the OID is "1.2.826.0.1.3344810.2.3".
control-name -- An optional string field whose value is a
human-readable name for this control. This field is only intended for
descriptive purposes, and when decoding a control, the oid
field should be used to identify the type of control.
criticality -- A mandatory Boolean field used to indicate
whether this control is considered critical.
value-base64 -- An optional string field whose value is a
base64-encoded representation of the raw value for this matched values
request control. Exactly one of the value-base64 and
value-json fields must be present.
value-json -- An optional JSON object field whose value is a
user-friendly representation of the value for this matched values
request control. Exactly one of the value-base64 and
value-json fields must be present, and if the
value-json field is used, then it will use the following
fields:
filters -- A mandatory, non-empty array field whose values
are the string representations of the matched values filters to
use.
toJSONControl in class Control@NotNull public static MatchedValuesRequestControl decodeJSONControl(@NotNull JSONObject controlObject, boolean strict) throws LDAPException
controlObject - The JSON object to be decoded. It must not be
null.strict - Indicates whether to use strict mode when decoding
the provided JSON object. If this is true,
then this method will throw an exception if the
provided JSON object contains any unrecognized
fields. If this is false, then unrecognized
fields will be ignored.LDAPException - If the provided JSON object cannot be parsed as a
valid matched values request control.