Package org.forgerock.opendj.ldap.controls

Class MatchedValuesRequestControl

java.lang.Object
org.forgerock.opendj.ldap.controls.MatchedValuesRequestControl
All Implemented Interfaces:
Control
public final class MatchedValuesRequestControl extends Object implements Control
The matched values request control as defined in RFC 3876. The matched values control may be included in a search request to indicate that only attribute values matching one or more filters contained in the matched values control should be returned to the client.

The matched values request control supports a subset of the LDAP filter type defined in RFC 4511, and is defined as follows: 

 ValuesReturnFilter ::= SEQUENCE OF SimpleFilterItem

 SimpleFilterItem ::= CHOICE {
        equalityMatch   [3] AttributeValueAssertion,
        substrings      [4] SubstringFilter,
        greaterOrEqual  [5] AttributeValueAssertion,
        lessOrEqual     [6] AttributeValueAssertion,
        present         [7] AttributeDescription,
        approxMatch     [8] AttributeValueAssertion,
        extensibleMatch [9] SimpleMatchingAssertion }

 SimpleMatchingAssertion ::= SEQUENCE {
        matchingRule    [1] MatchingRuleId OPTIONAL,
        type            [2] AttributeDescription OPTIONAL,
 --- at least one of the above must be present
        matchValue      [3] AssertionValue}
For example Barbara Jensen's entry contains two common name values, Barbara Jensen and Babs Jensen. The following code retrieves only the latter. 
 String DN = "uid=bjensen,ou=People,dc=example,dc=com";
 SearchRequest request = Requests.newSearchRequest(DN,
          SearchScope.BASE_OBJECT, "(objectclass=*)", "cn")
          .addControl(MatchedValuesRequestControl
                  .newControl(true, "(cn=Babs Jensen)"));

 // Get the entry, retrieving cn: Babs Jensen, not cn: Barbara Jensen
 SearchResultEntry entry = connection.searchSingleEntry(request);
See Also:

  • Field Details

  • Method Details

    • newControl

      public static MatchedValuesRequestControl newControl(boolean isCritical, Collection<Filter> filters)
      Creates a new matched values request control with the provided criticality and list of filters.
      Parameters:
      isCritical - true if it is unacceptable to perform the operation without applying the semantics of this control, or false if it can be ignored.
      filters - The list of filters of which at least one must match an attribute value in order for the attribute value to be returned to the client. The list must not be empty.
      Returns:
      The new control.
      Throws:
      LocalizedIllegalArgumentException - If one or more filters failed to conform to the filter constraints defined in RFC 3876.
      IllegalArgumentException - If filters was empty.
      NullPointerException - If filters was null.

    • newControl

      public static MatchedValuesRequestControl newControl(boolean isCritical, String... filters)
      Creates a new matched values request control with the provided criticality and list of filters.
      Parameters:
      isCritical - true if it is unacceptable to perform the operation without applying the semantics of this control, or false if it can be ignored.
      filters - The list of filters of which at least one must match an attribute value in order for the attribute value to be returned to the client. The list must not be empty.
      Returns:
      The new control.
      Throws:
      LocalizedIllegalArgumentException - If one or more filters could not be parsed, or if one or more filters failed to conform to the filter constraints defined in RFC 3876.
      NullPointerException - If filters was null.

    • getFilters

      public Collection<Filter> getFilters()
      Returns an unmodifiable collection containing the list of filters associated with this matched values control.
      Returns:
      An unmodifiable collection containing the list of filters associated with this matched values control.

    • getOid

      public String getOid()
      Description copied from interface: Control
      Returns the numeric OID associated with this control.
      Specified by:
      getOid in interface Control
      Returns:
      The numeric OID associated with this control.

    • getValue

      public ByteString getValue()
      Description copied from interface: Control
      Returns the value, if any, associated with this control. Its format is defined by the specification of this control.
      Specified by:
      getValue in interface Control
      Returns:
      The value associated with this control, or null if there is no value.

    • keepMatchedValues

      public AttributeFilter keepMatchedValues(AttributeFilter filter, Schema schema)
      Register a mapping function in the provided AttributeFilter which will only retain attribute values matching at least one filter defined in this control.
      Parameters:
      filter - The attribute filter where the mapping function will be registered into.
      schema - The schema which will be used for comparisons.
      Returns:
      A reference to the provided attribute filter.

    • keepMatchedValues

      public Function<Attribute,Attribute> keepMatchedValues(Schema schema)
      Returns a mapping function which, given an attribute, returns a new attribute containing only the values matching the filters defined in this control, or an empty attribute if none of the values match.
      Parameters:
      schema - The schema which will be used for comparisons.
      Returns:
      An attribute mapping function

    • hasValue

      public boolean hasValue()
      Description copied from interface: Control
      Returns true if this control has a value. In some circumstances it may be useful to determine if a control has a value, without actually calculating the value and incurring any performance costs.
      Specified by:
      hasValue in interface Control
      Returns:
      true if this control has a value, or false if there is no value.

    • isCritical

      public boolean isCritical()
      Description copied from interface: Control
      Returns true if it is unacceptable to perform the operation without applying the semantics of this control.

      The criticality field only has meaning in controls attached to request messages (except UnbindRequest). For controls attached to response messages and the UnbindRequest, the criticality field SHOULD be false, and MUST be ignored by the receiving protocol peer. A value of true indicates that it is unacceptable to perform the operation without applying the semantics of the control.

      Specified by:
      isCritical in interface Control
      Returns:
      true if this control must be processed by the Directory Server, or false if it can be ignored.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getAlias

      public String getAlias()
      Description copied from interface: Control
      Returns the control "friendly name" alias for the control.
      Specified by:
      getAlias in interface Control
      Returns:
      "Friendly name" alias for the control.