com.unboundid.ldap.sdk.controls.SortKey Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of unboundid-ldapsdk Show documentation
Show all versions of unboundid-ldapsdk Show documentation
The UnboundID LDAP SDK for Java is a fast, comprehensive, and easy-to-use
Java API for communicating with LDAP directory servers and performing
related tasks like reading and writing LDIF, encoding and decoding data
using base64 and ASN.1 BER, and performing secure communication. This
package contains the Standard Edition of the LDAP SDK, which is a
complete, general-purpose library for communicating with LDAPv3 directory
servers.
/*
* Copyright 2007-2018 Ping Identity Corporation
* All Rights Reserved.
*/
/*
* Copyright (C) 2008-2018 Ping Identity Corporation
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License (GPLv2 only)
* or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
* as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see .
*/
package com.unboundid.ldap.sdk.controls;
import java.io.Serializable;
import java.util.ArrayList;
import com.unboundid.asn1.ASN1Boolean;
import com.unboundid.asn1.ASN1Element;
import com.unboundid.asn1.ASN1OctetString;
import com.unboundid.asn1.ASN1Sequence;
import com.unboundid.ldap.sdk.LDAPException;
import com.unboundid.ldap.sdk.ResultCode;
import com.unboundid.util.Debug;
import com.unboundid.util.NotMutable;
import com.unboundid.util.StaticUtils;
import com.unboundid.util.ThreadSafety;
import com.unboundid.util.ThreadSafetyLevel;
import com.unboundid.util.Validator;
import static com.unboundid.ldap.sdk.controls.ControlMessages.*;
/**
* This class provides a data structure for representing a sort key that is to
* be used in conjunction with the {@link ServerSideSortRequestControl} for
* requesting that the server sort the results before returning them to the
* client.
*
* A sort key includes the following elements:
*
* - The name of the attribute for which sorting is to be performed.
* - A {@code reverseOrder} flag that indicates whether the results should
* be sorted in ascending order (if the value is {@code false}) or
* descending order (if the value is {@code true}).
* - An optional matching rule ID, which specifies the ordering matching
* rule that should be used to perform the sorting. If this is not
* provided, then the default ordering matching rule for the specified
* attribute will be used.
*
*/
@NotMutable()
@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
public final class SortKey
implements Serializable
{
/**
* The BER type that should be used for the matching rule ID element.
*/
private static final byte TYPE_MATCHING_RULE_ID = (byte) 0x80;
/**
* The BER type that should be used for the reverse order element.
*/
private static final byte TYPE_REVERSE_ORDER = (byte) 0x81;
/**
* The serial version UID for this serializable class.
*/
private static final long serialVersionUID = -8631224188301402858L;
// Indicates whether the sort should be performed in reverse order.
private final boolean reverseOrder;
// The attribute name for this sort key.
private final String attributeName;
// The matching rule ID for this sort key.
private final String matchingRuleID;
/**
* Creates a new sort key with the specified attribute name. It will use the
* default ordering matching rule associated with that attribute, and it will
* not use reverse order.
*
* @param attributeName The attribute name for this sort key. It must not
* be {@code null}.
*/
public SortKey(final String attributeName)
{
this(attributeName, null, false);
}
/**
* Creates a new sort key with the specified attribute name. It will use the
* default ordering matching rule associated with that attribute.
*
* @param attributeName The attribute name for this sort key. It must not
* be {@code null}.
* @param reverseOrder Indicates whether the sort should be performed in
* reverse order.
*/
public SortKey(final String attributeName, final boolean reverseOrder)
{
this(attributeName, null, reverseOrder);
}
/**
* Creates a new sort key with the provided information.
*
* @param attributeName The attribute name for this sort key. It must not
* be {@code null}.
* @param matchingRuleID The name or OID of the ordering matching rule that
* should be used to perform the sort. It may be
* {@code null} if the default ordering matching rule
* for the specified attribute is to be used.
* @param reverseOrder Indicates whether the sort should be performed in
* reverse order.
*/
public SortKey(final String attributeName, final String matchingRuleID,
final boolean reverseOrder)
{
Validator.ensureNotNull(attributeName);
this.attributeName = attributeName;
this.matchingRuleID = matchingRuleID;
this.reverseOrder = reverseOrder;
}
/**
* Retrieves the attribute name for this sort key.
*
* @return The attribute name for this sort key.
*/
public String getAttributeName()
{
return attributeName;
}
/**
* Retrieves the name or OID of the ordering matching rule that should be used
* to perform the sort, if defined.
*
* @return The name or OID of the ordering matching rule that should be used
* to perform the sort, or {@code null} if the sort should use the
* default ordering matching rule associated with the specified
* attribute.
*/
public String getMatchingRuleID()
{
return matchingRuleID;
}
/**
* Indicates whether the sort should be performed in reverse order.
*
* @return {@code true} if the sort should be performed in reverse order, or
* {@code false} if it should be performed in the standard order for
* the associated ordering matching rule.
*/
public boolean reverseOrder()
{
return reverseOrder;
}
/**
* Encodes this sort key into an ASN.1 sequence suitable for use in the
* server-side sort control.
*
* @return An ASN.1 sequence containing the encoded representation of this
* sort key.
*/
ASN1Sequence encode()
{
final ArrayList elements = new ArrayList<>(3);
elements.add(new ASN1OctetString(attributeName));
if (matchingRuleID != null)
{
elements.add(new ASN1OctetString(TYPE_MATCHING_RULE_ID, matchingRuleID));
}
if (reverseOrder)
{
elements.add(new ASN1Boolean(TYPE_REVERSE_ORDER, reverseOrder));
}
return new ASN1Sequence(elements);
}
/**
* Decodes the provided ASN.1 element as a sort key.
*
* @param element The ASN.1 element to decode as a sort key.
*
* @return The decoded sort key.
*
* @throws LDAPException If the provided ASN.1 element cannot be decoded as
* a sort key.
*/
public static SortKey decode(final ASN1Element element)
throws LDAPException
{
final ASN1Element[] elements;
try
{
elements = ASN1Sequence.decodeAsSequence(element).elements();
}
catch (final Exception e)
{
Debug.debugException(e);
throw new LDAPException(ResultCode.DECODING_ERROR,
ERR_SORT_KEY_NOT_SEQUENCE.get(e), e);
}
if ((elements.length < 1) || (elements.length > 3))
{
throw new LDAPException(ResultCode.DECODING_ERROR,
ERR_SORT_KEY_INVALID_ELEMENT_COUNT.get(elements.length));
}
boolean reverseOrder = false;
String matchingRuleID = null;
final String attributeName =
ASN1OctetString.decodeAsOctetString(elements[0]).stringValue();
for (int i=1; i < elements.length; i++)
{
switch (elements[i].getType())
{
case TYPE_MATCHING_RULE_ID:
matchingRuleID =
ASN1OctetString.decodeAsOctetString(elements[i]).stringValue();
break;
case TYPE_REVERSE_ORDER:
try
{
reverseOrder =
ASN1Boolean.decodeAsBoolean(elements[i]).booleanValue();
}
catch (final Exception e)
{
Debug.debugException(e);
throw new LDAPException(ResultCode.DECODING_ERROR,
ERR_SORT_KEY_REVERSE_NOT_BOOLEAN.get(e), e);
}
break;
default:
throw new LDAPException(ResultCode.DECODING_ERROR,
ERR_SORT_KEY_ELEMENT_INVALID_TYPE.get(
StaticUtils.toHex(elements[i].getType())));
}
}
return new SortKey(attributeName, matchingRuleID, reverseOrder);
}
/**
* Retrieves a string representation of this sort key.
*
* @return A string representation of this sort key.
*/
@Override()
public String toString()
{
final StringBuilder buffer = new StringBuilder();
toString(buffer);
return buffer.toString();
}
/**
* Appends a string representation of this sort key to the provided buffer.
*
* @param buffer The buffer to which to append a string representation of
* this sort key.
*/
public void toString(final StringBuilder buffer)
{
buffer.append("SortKey(attributeName=");
buffer.append(attributeName);
if (matchingRuleID != null)
{
buffer.append(", matchingRuleID=");
buffer.append(matchingRuleID);
}
buffer.append(", reverseOrder=");
buffer.append(reverseOrder);
buffer.append(')');
}
}