Package org.forgerock.opendj.ldap

Class SortKey

java.lang.Object
org.forgerock.opendj.ldap.SortKey
public final class SortKey extends Object
A search result sort key as defined in RFC 2891 is used to specify how search result entries should be ordered. Sort keys are used with the server side sort request control ServerSideSortRequestControl, but could also be used for performing client side sorting as well.

The following example illustrates how a single sort key may be used to sort entries as they are returned from a search operation using the cn attribute as the sort key: 

 
 Connection connection = ...;
 SearchRequest request = ...;

 Comparator<Entry> comparator = SortKey.comparator("cn");
 Set<SearchResultEntry>; results = new TreeSet<>(comparator);

 connection.search(request, results);
A sort key includes an attribute description and a boolean value that indicates whether the sort should be ascending or descending. It may also contain a specific ordering matching rule that should be used for the sorting process, although if none is provided it will use the default ordering matching rule for the attribute type.
See Also:

  • Constructor Details

    • SortKey

      public SortKey(AttributeDescription attributeDescription, boolean isReverseOrder, MatchingRule orderingMatchingRule)
      Creates a new sort key using the provided attribute description. The returned sort key will compare attributes in the order specified using the named ordering matching rule.
      Parameters:
      attributeDescription - The name of the attribute to be sorted using this sort key.
      isReverseOrder - true if this sort key should be evaluated in reverse (descending) order.
      orderingMatchingRule - The name or OID of the ordering matching rule, which should be used when comparing attributes using this sort key, or null if the default ordering matching rule associated with the attribute should be used.
      Throws:
      NullPointerException - If AttributeDescription was null.

    • SortKey

      public SortKey(String attributeDescription)
      Creates a new sort key using the provided attribute description. The returned sort key will compare attributes in ascending order using the default ordering matching rule associated with the attribute.
      Parameters:
      attributeDescription - The name of the attribute to be sorted using this sort key.
      Throws:
      NullPointerException - If AttributeDescription was null.

    • SortKey

      public SortKey(String attributeDescription, boolean isReverseOrder)
      Creates a new sort key using the provided attribute description. The returned sort key will compare attributes in the order specified using the default ordering matching rule associated with the attribute.
      Parameters:
      attributeDescription - The name of the attribute to be sorted using this sort key.
      isReverseOrder - true if this sort key should be evaluated in reverse (descending) order.
      Throws:
      NullPointerException - If AttributeDescription was null.

    • SortKey

      public SortKey(String attributeDescription, boolean isReverseOrder, String orderingMatchingRule)
      Creates a new sort key using the provided attribute description. The returned sort key will compare attributes in the order specified using the named ordering matching rule.
      Parameters:
      attributeDescription - The name of the attribute to be sorted using this sort key.
      isReverseOrder - true if this sort key should be evaluated in reverse (descending) order.
      orderingMatchingRule - The name or OID of the ordering matching rule, which should be used when comparing attributes using this sort key, or null if the default ordering matching rule associated with the attribute should be used.
      Throws:
      NullPointerException - If AttributeDescription was null.

  • Method Details

    • comparator

      public static Comparator<Entry> comparator(Collection<SortKey> keys) throws LdapException
      Returns a Comparator which can be used to compare entries using the provided list of sort keys. The sort keys will be decoded using the default schema.
      Parameters:
      keys - The list of sort keys.
      Returns:
      The Comparator.
      Throws:
      LdapException - If one of the sort keys could not be converted to a comparator.
      IllegalArgumentException - If keys was empty.
      NullPointerException - If keys was null.

    • comparator

      public static Comparator<Entry> comparator(Schema schema, Collection<SortKey> keys) throws LdapException
      Returns a Comparator which can be used to compare entries using the provided list of sort keys. The sort keys will be decoded using the provided schema.
      Parameters:
      schema - The schema which should be used for decoding the sort keys.
      keys - The list of sort keys.
      Returns:
      The Comparator.
      Throws:
      LdapException - If one of the sort keys could not be converted to a comparator.
      IllegalArgumentException - If keys was empty.
      NullPointerException - If schema or keys was null.

    • comparator

      public static Comparator<Entry> comparator(Schema schema, SortKey... keys) throws LdapException
      Returns a Comparator which can be used to compare entries using the provided list of sort keys. The sort keys will be decoded using the provided schema.
      Parameters:
      schema - The schema which should be used for decoding the sort keys.
      keys - The list of sort keys.
      Returns:
      The Comparator.
      Throws:
      LdapException - If one of the sort keys could not be converted to a comparator.
      IllegalArgumentException - If keys was empty.
      NullPointerException - If schema or keys was null.

    • comparator

      public static Comparator<Entry> comparator(SortKey... keys) throws LdapException
      Returns a Comparator which can be used to compare entries using the provided list of sort keys. The sort keys will be decoded using the default schema.
      Parameters:
      keys - The list of sort keys.
      Returns:
      The Comparator.
      Throws:
      LdapException - If one of the sort keys could not be converted to a comparator.
      IllegalArgumentException - If keys was empty.
      NullPointerException - If keys was null.

    • comparator

      public static Comparator<Entry> comparator(String sortKeys) throws LdapException
      Returns a Comparator which can be used to compare entries using the provided string representation of a list of sort keys. The sort keys will be decoded using the default schema. The string representation consists of a comma-separated list of sort keys as defined in valueOf(String). There must be at least one sort key present in the string representation.
      Parameters:
      sortKeys - The list of sort keys.
      Returns:
      The Comparator.
      Throws:
      LdapException - If sortKeys is not a valid string representation of a list of sort keys, or if one of the sort keys could not be converted to a comparator.
      NullPointerException - If sortKeys was null.

    • valueOf

      public static SortKey valueOf(String sortKey)
      Parses the provided string representation of a sort key as a SortKey. The string representation has the following ABNF (see RFC 4512 for definitions of the elements below): 
         SortKey = [ PLUS / HYPHEN ]    ; order specifier
             attributedescription ; attribute description
             [ COLON oid ]        ; ordering matching rule OID
      Examples: 
         cn                           ; case ignore ascending sort on "cn"
   -cn                          ; case ignore descending sort on "cn"
   +cn;lang-fr                  ; case ignore ascending sort on "cn;lang-fr"
   -cn;lang-fr:caseExactMatch   ; case exact ascending sort on "cn;lang-fr"
      Parameters:
      sortKey - The string representation of a sort key.
      Returns:
      The parsed SortKey.
      Throws:
      LocalizedIllegalArgumentException - If sortKey is not a valid string representation of a sort key.
      NullPointerException - If sortKey was null.

    • comparator

      public Comparator<Entry> comparator() throws LdapException
      Returns a Comparator which can be used to compare entries using this sort key. The attribute description and matching rule, if present, will be decoded using the default schema.
      Returns:
      The Comparator.
      Throws:
      LdapException - If attributeDescription is not a valid LDAP string representation of an attribute description, or if no ordering matching rule was found.

    • comparator

      public SortKey.SortComparator comparator(Schema schema) throws LdapException
      Returns a Comparator which can be used to compare entries using this sort key. The attribute description and matching rule, if present, will be decoded using the provided schema.
      Parameters:
      schema - The schema which should be used for decoding the attribute description and matching rule.
      Returns:
      The Comparator.
      Throws:
      LdapException - If attributeDescription is not a valid LDAP string representation of an attribute description, or if no ordering matching rule was found.
      NullPointerException - If schema was null.

    • getAttributeDescription

      public String getAttributeDescription()
      Returns the name of the attribute to be sorted using this sort key.
      Returns:
      The name of the attribute to be sorted using this sort key.

    • getOrderingMatchingRule

      public String getOrderingMatchingRule()
      Returns the name or OID of the ordering matching rule, if specified, which should be used when comparing attributes using this sort key.
      Returns:
      The name or OID of the ordering matching rule, if specified, which should be used when comparing attributes using this sort key, or null if the default ordering matching rule associated with the attribute should be used.

    • isReverseOrder

      public boolean isReverseOrder()
      Returns true if this sort key should be evaluated in reverse (descending) order. More specifically, comparisons performed using the ordering matching rule associated with this sort key will have their results inverted.
      Returns:
      true if this sort key should be evaluated in reverse (descending) order.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • toString

      public String toString()
      Returns a string representation of this sort key using the format defined in valueOf(String).
      Overrides:
      toString in class Object
      Returns:
      A string representation of this sort key.