Package org.forgerock.opendj.ldap.controls

Class 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:
    RFC 3876 - Returning Matched Values with the Lightweight Directory Access Protocol version 3 (LDAPv3)

    • Field Detail

      • OID

        public static final String OID
        The OID for the matched values request control used to specify which particular attribute values should be returned in a search result entry.
        See Also:
        Constant Field Values

    • Method Detail

      • 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.