/*
|
* CDDL HEADER START
|
*
|
* The contents of this file are subject to the terms of the
|
* Common Development and Distribution License, Version 1.0 only
|
* (the "License"). You may not use this file except in compliance
|
* with the License.
|
*
|
* You can obtain a copy of the license at
|
* trunk/opends/resource/legal-notices/OpenDS.LICENSE
|
* or https://OpenDS.dev.java.net/OpenDS.LICENSE.
|
* See the License for the specific language governing permissions
|
* and limitations under the License.
|
*
|
* When distributing Covered Code, include this CDDL HEADER in each
|
* file and include the License file at
|
* trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable,
|
* add the following below this CDDL HEADER, with the fields enclosed
|
* by brackets "[]" replaced with your own identifying information:
|
* Portions Copyright [yyyy] [name of copyright owner]
|
*
|
* CDDL HEADER END
|
*
|
*
|
* Copyright 2009 Sun Microsystems, Inc.
|
*/
|
|
package org.opends.sdk.controls;
|
|
|
|
import static com.sun.opends.sdk.messages.Messages.*;
|
import static com.sun.opends.sdk.util.StaticUtils.getExceptionMessage;
|
|
import java.io.IOException;
|
import java.util.*;
|
|
import org.opends.sdk.*;
|
import org.opends.sdk.asn1.ASN1;
|
import org.opends.sdk.asn1.ASN1Reader;
|
import org.opends.sdk.asn1.ASN1Writer;
|
|
import com.sun.opends.sdk.ldap.LDAPUtils;
|
import com.sun.opends.sdk.util.StaticUtils;
|
import com.sun.opends.sdk.util.Validator;
|
|
|
|
/**
|
* 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.
|
* <p>
|
* The matched values request control supports a subset of the LDAP filter type
|
* defined in RFC 4511, and is defined as follows:
|
*
|
* <pre>
|
* 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}
|
* </pre>
|
*
|
* @see <a href="http://tools.ietf.org/html/rfc3876">RFC 3876 - Returning
|
* Matched Values with the Lightweight Directory Access Protocol version 3
|
* (LDAPv3) </a>
|
*/
|
public final class MatchedValuesRequestControl implements Control
|
{
|
/**
|
* Visitor for validating matched values filters.
|
*/
|
private static final class FilterValidator extends
|
AbstractFilterVisitor<LocalizedIllegalArgumentException, Filter>
|
{
|
|
@Override
|
public LocalizedIllegalArgumentException visitAndFilter(final Filter p,
|
final List<Filter> subFilters)
|
{
|
final LocalizableMessage message = ERR_MVFILTER_BAD_FILTER_AND.get(p
|
.toString());
|
return new LocalizedIllegalArgumentException(message);
|
}
|
|
|
|
@Override
|
public LocalizedIllegalArgumentException visitExtensibleMatchFilter(
|
final Filter p, final String matchingRule,
|
final String attributeDescription, final ByteString assertionValue,
|
final boolean dnAttributes)
|
{
|
if (dnAttributes)
|
{
|
final LocalizableMessage message = ERR_MVFILTER_BAD_FILTER_EXT.get(p
|
.toString());
|
return new LocalizedIllegalArgumentException(message);
|
}
|
else
|
{
|
return null;
|
}
|
}
|
|
|
|
@Override
|
public LocalizedIllegalArgumentException visitNotFilter(final Filter p,
|
final Filter subFilter)
|
{
|
final LocalizableMessage message = ERR_MVFILTER_BAD_FILTER_NOT.get(p
|
.toString());
|
return new LocalizedIllegalArgumentException(message);
|
}
|
|
|
|
@Override
|
public LocalizedIllegalArgumentException visitOrFilter(final Filter p,
|
final List<Filter> subFilters)
|
{
|
final LocalizableMessage message = ERR_MVFILTER_BAD_FILTER_OR.get(p
|
.toString());
|
return new LocalizedIllegalArgumentException(message);
|
}
|
|
|
|
@Override
|
public LocalizedIllegalArgumentException visitUnrecognizedFilter(
|
final Filter p, final byte filterTag, final ByteString filterBytes)
|
{
|
final LocalizableMessage message = ERR_MVFILTER_BAD_FILTER_UNRECOGNIZED
|
.get(p.toString(), filterTag);
|
return new LocalizedIllegalArgumentException(message);
|
}
|
}
|
|
|
|
/**
|
* The OID for the matched values request control used to specify which
|
* particular attribute values should be returned in a search result entry.
|
*/
|
public static final String OID = "1.2.826.0.1.3344810.2.3";
|
|
/**
|
* A decoder which can be used for decoding the matched values request
|
* control.
|
*/
|
public static final ControlDecoder<MatchedValuesRequestControl> DECODER =
|
new ControlDecoder<MatchedValuesRequestControl>()
|
{
|
|
public MatchedValuesRequestControl decodeControl(final Control control,
|
final DecodeOptions options) throws DecodeException
|
{
|
Validator.ensureNotNull(control);
|
|
if (control instanceof MatchedValuesRequestControl)
|
{
|
return (MatchedValuesRequestControl) control;
|
}
|
|
if (!control.getOID().equals(OID))
|
{
|
final LocalizableMessage message = ERR_MATCHEDVALUES_CONTROL_BAD_OID
|
.get(control.getOID(), OID);
|
throw DecodeException.error(message);
|
}
|
|
if (!control.hasValue())
|
{
|
// The response control must always have a value.
|
final LocalizableMessage message = ERR_MATCHEDVALUES_NO_CONTROL_VALUE
|
.get();
|
throw DecodeException.error(message);
|
}
|
|
final ASN1Reader reader = ASN1.getReader(control.getValue());
|
try
|
{
|
reader.readStartSequence();
|
if (!reader.hasNextElement())
|
{
|
final LocalizableMessage message = ERR_MATCHEDVALUES_NO_FILTERS.get();
|
throw DecodeException.error(message);
|
}
|
|
final LinkedList<Filter> filters = new LinkedList<Filter>();
|
do
|
{
|
final Filter filter = LDAPUtils.decodeFilter(reader);
|
|
try
|
{
|
validateFilter(filter);
|
}
|
catch (final LocalizedIllegalArgumentException e)
|
{
|
throw DecodeException.error(e.getMessageObject());
|
}
|
|
filters.add(filter);
|
}
|
while (reader.hasNextElement());
|
|
reader.readEndSequence();
|
|
return new MatchedValuesRequestControl(control.isCritical(),
|
Collections.unmodifiableList(filters));
|
}
|
catch (final IOException e)
|
{
|
StaticUtils.DEBUG_LOG.throwing("MatchedValuesControl.Decoder",
|
"decode", e);
|
|
final LocalizableMessage message = ERR_MATCHEDVALUES_CANNOT_DECODE_VALUE_AS_SEQUENCE
|
.get(getExceptionMessage(e));
|
throw DecodeException.error(message);
|
}
|
}
|
|
|
|
public String getOID()
|
{
|
return OID;
|
}
|
};
|
|
private static final FilterValidator FILTER_VALIDATOR = new FilterValidator();
|
|
|
|
/**
|
* Creates a new matched values request control with the provided criticality
|
* and list of filters.
|
*
|
* @param isCritical
|
* {@code true} if it is unacceptable to perform the operation
|
* without applying the semantics of this control, or {@code false}
|
* if it can be ignored.
|
* @param 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.
|
* @return The new control.
|
* @throws LocalizedIllegalArgumentException
|
* If one or more filters failed to conform to the filter
|
* constraints defined in RFC 3876.
|
* @throws IllegalArgumentException
|
* If {@code filters} was empty.
|
* @throws NullPointerException
|
* If {@code filters} was {@code null}.
|
*/
|
public static MatchedValuesRequestControl newControl(
|
final boolean isCritical, final Collection<Filter> filters)
|
throws LocalizedIllegalArgumentException, IllegalArgumentException,
|
NullPointerException
|
{
|
Validator.ensureNotNull(filters);
|
Validator.ensureTrue(filters.size() > 0, "filters is empty");
|
|
List<Filter> copyOfFilters;
|
if (filters.size() == 1)
|
{
|
copyOfFilters = Collections.singletonList(validateFilter(filters
|
.iterator().next()));
|
}
|
else
|
{
|
copyOfFilters = new ArrayList<Filter>(filters.size());
|
for (final Filter filter : filters)
|
{
|
copyOfFilters.add(validateFilter(filter));
|
}
|
copyOfFilters = Collections.unmodifiableList(copyOfFilters);
|
}
|
|
return new MatchedValuesRequestControl(isCritical, copyOfFilters);
|
}
|
|
|
|
/**
|
* Creates a new matched values request control with the provided criticality
|
* and list of filters.
|
*
|
* @param isCritical
|
* {@code true} if it is unacceptable to perform the operation
|
* without applying the semantics of this control, or {@code false}
|
* if it can be ignored.
|
* @param firstFilter
|
* The first matched values filter.
|
* @param remainingFilters
|
* The remaining matched values filter, may be {@code null} or empty.
|
* @return 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.
|
* @throws NullPointerException
|
* If {@code firstFilter} was {@code null}.
|
*/
|
public static MatchedValuesRequestControl newControl(
|
final boolean isCritical, final String firstFilter,
|
final String... remainingFilters)
|
throws LocalizedIllegalArgumentException, NullPointerException
|
{
|
Validator.ensureNotNull(firstFilter);
|
|
List<Filter> filters;
|
if (remainingFilters == null || remainingFilters.length == 0)
|
{
|
filters = Collections.singletonList(validateFilter(Filter
|
.valueOf(firstFilter)));
|
}
|
else
|
{
|
filters = new ArrayList<Filter>(1 + remainingFilters.length);
|
filters.add(validateFilter(Filter.valueOf(firstFilter)));
|
for (final String filter : remainingFilters)
|
{
|
filters.add(validateFilter(Filter.valueOf(filter)));
|
}
|
filters = Collections.unmodifiableList(filters);
|
}
|
|
return new MatchedValuesRequestControl(isCritical, filters);
|
}
|
|
|
|
private static Filter validateFilter(final Filter filter)
|
throws LocalizedIllegalArgumentException
|
{
|
final LocalizedIllegalArgumentException e = filter.accept(FILTER_VALIDATOR,
|
filter);
|
if (e != null)
|
{
|
throw e;
|
}
|
return filter;
|
}
|
|
|
|
private final Collection<Filter> filters;
|
|
private final boolean isCritical;
|
|
|
|
private MatchedValuesRequestControl(final boolean isCritical,
|
final Collection<Filter> filters)
|
{
|
this.isCritical = isCritical;
|
this.filters = filters;
|
}
|
|
|
|
/**
|
* Returns an unmodifiable collection containing the list of filters
|
* associated with this matched values control.
|
*
|
* @return An unmodifiable collection containing the list of filters
|
* associated with this matched values control.
|
*/
|
public Collection<Filter> getFilters()
|
{
|
return filters;
|
}
|
|
|
|
/**
|
* {@inheritDoc}
|
*/
|
public String getOID()
|
{
|
return OID;
|
}
|
|
|
|
/**
|
* {@inheritDoc}
|
*/
|
@Override
|
public ByteString getValue()
|
{
|
final ByteStringBuilder buffer = new ByteStringBuilder();
|
final ASN1Writer writer = ASN1.getWriter(buffer);
|
try
|
{
|
writer.writeStartSequence();
|
for (final Filter f : filters)
|
{
|
LDAPUtils.encodeFilter(writer, f);
|
}
|
writer.writeEndSequence();
|
return buffer.toByteString();
|
}
|
catch (final IOException ioe)
|
{
|
// This should never happen unless there is a bug somewhere.
|
throw new RuntimeException(ioe);
|
}
|
}
|
|
|
|
/**
|
* {@inheritDoc}
|
*/
|
public boolean hasValue()
|
{
|
return true;
|
}
|
|
|
|
/**
|
* {@inheritDoc}
|
*/
|
public boolean isCritical()
|
{
|
return isCritical;
|
}
|
|
|
|
/**
|
* {@inheritDoc}
|
*/
|
@Override
|
public String toString()
|
{
|
final StringBuilder builder = new StringBuilder();
|
builder.append("MatchedValuesRequestControl(oid=");
|
builder.append(getOID());
|
builder.append(", criticality=");
|
builder.append(isCritical());
|
builder.append(")");
|
return builder.toString();
|
}
|
}
|
