MatchedValuesRequestControl (OpenDJ Public API Javadoc 6.5.6 Documentation)

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

Field Summary

Fields
Modifier and Type	Field and Description
`static ControlDecoder<MatchedValuesRequestControl>`	`DECODER` A decoder which can be used for decoding the matched values request control.
`static 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.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Collection<Filter>`	`getFilters()` Returns an unmodifiable collection containing the list of filters associated with this matched values control.
`String`	`getOid()` Returns the numeric OID associated with this control.
`ByteString`	`getValue()` Returns the value, if any, associated with this control.
`boolean`	`hasValue()` Returns `true` if this control has a value.
`boolean`	`isCritical()` Returns `true` if it is unacceptable to perform the operation without applying the semantics of this control.
`static MatchedValuesRequestControl`	`newControl(boolean isCritical, Collection<Filter> filters)` Creates a new matched values request control with the provided criticality and list of filters.
`static MatchedValuesRequestControl`	`newControl(boolean isCritical, String... filters)` Creates a new matched values request control with the provided criticality and list of filters.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- 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
  - DECODER
```
public static final ControlDecoder<MatchedValuesRequestControl> DECODER
```
    A decoder which can be used for decoding the matched values request control.
- 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.
  - 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

Class MatchedValuesRequestControl

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

OID

DECODER

Method Detail

newControl

newControl

getFilters

getOid

getValue

hasValue

isCritical

toString