Module jakarta.data
Package jakarta.data

Record Class Sort<T>

java.lang.Object
java.lang.Record
jakarta.data.Sort<T>
Type Parameters:
T - entity class of the entity attribute upon which to sort.
Record Components:
property - name of the entity attribute to order by.
isAscending - whether ordering for this attribute is ascending (true) or descending (false).
ignoreCase - whether or not to request case insensitive ordering from a database with case sensitive collation.
public record Sort<T>(String property, boolean isAscending, boolean ignoreCase) extends Record

Requests sorting on a given entity attribute.

An instance of Sort specifies a sorting criterion based on an entity attribute, with a sorting direction and well-defined case sensitivity.

A query method of a repository may have a parameter or parameters of type Sort if its return type indicates that it may return multiple entities. Parameters of type Sort must occur after the method parameters representing regular parameters of the query itself.

A repository method parameter of type Order allows a variable number of Sort criteria. For example,


 Employee[] findByYearHired(int yearHired, Limit maxResults, Order<Employee> sortBy);

 ...
 highestPaidNewHires = employees.findByYearHired(Year.now().getValue(),
                                                 Limit.of(10),
                                                 Order.by(Sort.desc("salary"),
                                                          Sort.asc("lastName"),
                                                          Sort.asc("firstName")));

Alternatively, Order may be used in combination with the static metamodel to allow a variable number of typed Sort criteria. For example,


 highestPaidNewHires = employees.findByYearHired(Year.now().getValue(),
                                                 Limit.of(10),
                                                 Order.by(_Employee.salary.desc(),
                                                          _Employee.lastName.asc(),
                                                          _Employee.firstName.asc()));

When multiple sorting criteria are provided, sorting is lexicographic, with the precedence of a criterion depending on its position with the list of criteria.

A repository method may declare static sorting criteria using the OrderBy keyword or @OrderBy annotation, and also accept dynamic sorting criteria via its parameters. In this situation, the static sorting criteria are applied first, followed by any dynamic sorting criteria specified by instances of Sort.

In the example above, the matching employees are sorted first by salary from highest to lowest. Employees with the same salary are then sorted alphabetically by last name. Employees with the same salary and last name are then sorted alphabetically by first name.

A repository method throws DataException if the database is incapable of ordering the query results using the given sort criteria.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Sort(String property, boolean isAscending, boolean ignoreCase)
    Defines sort criteria for an entity attribute.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> Sort<T>
    asc(String attribute)
    Create a Sort instance with ascending direction that does not request case insensitive ordering.
    static <T> Sort<T>
    ascIgnoreCase(String attribute)
    Create a Sort instance with ascending direction and case insensitive ordering.
    static <T> Sort<T>
    desc(String attribute)
    Create a Sort instance with descending direction that does not request case insensitive ordering.
    static <T> Sort<T>
    descIgnoreCase(String attribute)
    Create a Sort instance with descending direction and case insensitive ordering.
    final boolean
    equals(Object o)
    Indicates whether some other object is "equal to" this one.
    final int
    hashCode()
    Returns a hash code value for this object.
    boolean
    ignoreCase()
    Indicates whether or not to request case insensitive ordering from a database with case sensitive collation.
    boolean
    isAscending()
    Indicates whether to sort the entity attribute in ascending order (true) or descending order (false).
    boolean
    isDescending()
    Indicates whether to sort the entity attribute in descending order (true) or ascending order (false).
    static <T> Sort<T>
    of(String attribute, Direction direction, boolean ignoreCase)
    Create a Sort instance
    String
    property()
    Name of the entity attribute to order by.
    final String
    toString()
    Returns a string representation of this record class.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Sort

      public Sort(String property, boolean isAscending, boolean ignoreCase)

      Defines sort criteria for an entity attribute. For more descriptive code, use:

      Parameters:
      property - name of the entity attribute to order by.
      isAscending - whether ordering for this attribute is ascending (true) or descending (false).
      ignoreCase - whether or not to request case insensitive ordering from a database with case sensitive collation.

  • Method Details

    • property

      public String property()
      Name of the entity attribute to order by.
      Returns:
      The attribute name to order by; will never be null.

    • ignoreCase

      public boolean ignoreCase()

      Indicates whether or not to request case insensitive ordering from a database with case sensitive collation. A database with case insensitive collation performs case insensitive ordering regardless of the requested ignoreCase value.

      Returns:
      Returns whether or not to request case insensitive sorting for the entity attribute.

    • isAscending

      public boolean isAscending()
      Indicates whether to sort the entity attribute in ascending order (true) or descending order (false).
      Returns:
      Returns whether sorting for this attribute shall be ascending.

    • isDescending

      public boolean isDescending()
      Indicates whether to sort the entity attribute in descending order (true) or ascending order (false).
      Returns:
      Returns whether sorting for this attribute shall be descending.

    • of

      public static <T> Sort<T> of(String attribute, Direction direction, boolean ignoreCase)
      Create a Sort instance
      Type Parameters:
      T - entity class of the sortable entity attribute.
      Parameters:
      attribute - name of the entity attribute to order by
      direction - the direction in which to order.
      ignoreCase - whether to request a case insensitive ordering.
      Returns:
      a Sort instance. Never null.
      Throws:
      NullPointerException - when there is a null parameter

    • asc

      public static <T> Sort<T> asc(String attribute)
      Create a Sort instance with ascending direction that does not request case insensitive ordering.
      Type Parameters:
      T - entity class of the sortable entity attribute.
      Parameters:
      attribute - name of the entity attribute to order by
      Returns:
      a Sort instance. Never null.
      Throws:
      NullPointerException - when the attribute name is null

    • ascIgnoreCase

      public static <T> Sort<T> ascIgnoreCase(String attribute)
      Create a Sort instance with ascending direction and case insensitive ordering.
      Type Parameters:
      T - entity class of the sortable entity attribute.
      Parameters:
      attribute - name of the entity attribute to order by.
      Returns:
      a Sort instance. Never null.
      Throws:
      NullPointerException - when the attribute name is null.

    • desc

      public static <T> Sort<T> desc(String attribute)
      Create a Sort instance with descending direction that does not request case insensitive ordering.
      Type Parameters:
      T - entity class of the sortable entity attribute.
      Parameters:
      attribute - name of the entity attribute to order by
      Returns:
      a Sort instance. Never null.
      Throws:
      NullPointerException - when the attribute name is null

    • descIgnoreCase

      public static <T> Sort<T> descIgnoreCase(String attribute)
      Create a Sort instance with descending direction and case insensitive ordering.
      Type Parameters:
      T - entity class of the sortable entity attribute.
      Parameters:
      attribute - name of the entity attribute to order by.
      Returns:
      a Sort instance. Never null.
      Throws:
      NullPointerException - when the attribute name is null.

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.