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 property upon which to sort.
Record Components:
property - name of the property to order by.
isAscending - whether ordering for this property 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 field, 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.

The parameter type Sort<?>... allows a variable number of generic Sort criteria. For example,

 Employee[] findByYearHired(int yearHired, Limit maxResults, Sort<?>... sortBy);
 ...
 highestPaidNewHires = employees.findByYearHired(Year.now().getValue(),
                                                 Limit.of(10),
                                                 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,

 Employee[] findByYearHired(int yearHired, Limit maxResults, Order<Employee> sortBy);
 ...
 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 property.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> Sort<T>
    asc(String property)
    Create a Sort instance with ascending direction that does not request case insensitive ordering.
    static <T> Sort<T>
    ascIgnoreCase(String property)
    Create a Sort instance with ascending direction and case insensitive ordering.
    static <T> Sort<T>
    desc(String property)
    Create a Sort instance with descending direction that does not request case insensitive ordering.
    static <T> Sort<T>
    descIgnoreCase(String property)
    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 property in ascending order (true) or descending order (false).
    boolean
    isDescending()
    Indicates whether to sort the property in descending order (true) or ascending order (false).
    static <T> Sort<T>
    of(String property, Direction direction, boolean ignoreCase)
    Create a Sort instance
    String
    property()
    Name of the property 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 property. For more descriptive code, use:

      Parameters:
      property - name of the property to order by.
      isAscending - whether ordering for this property 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 property to order by.
      Returns:
      The property 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 property.

    • isAscending

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

    • isDescending

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

    • of

      public static <T> Sort<T> of(String property, Direction direction, boolean ignoreCase)
      Create a Sort instance
      Type Parameters:
      T - entity class of the sortable property.
      Parameters:
      property - the property name 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 property)
      Create a Sort instance with ascending direction that does not request case insensitive ordering.
      Type Parameters:
      T - entity class of the sortable property.
      Parameters:
      property - the property name to order by
      Returns:
      a Sort instance. Never null.
      Throws:
      NullPointerException - when the property is null

    • ascIgnoreCase

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

    • desc

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

    • descIgnoreCase

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