Jakarta EE 11.0.0 · jakarta.data.Sort · APIdia, the JavaDoc alternative

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 jakarta.data.exceptions.DataException if the database is incapable of ordering the query results using the given sort criteria.

Modifier and Type	Field and Description
private final boolean	ignoreCase Record Component accessed by ignoreCase(). whether or not to request case insensitive ordering from a database with case sensitive collation.
private final boolean	isAscending Record Component accessed by isAscending(). whether ordering for this property is ascending (true) or descending (false).
private final String	property Record Component accessed by property(). name of the property to order by.

Constructor Summary

Access	Constructor and Description
public	Sort(String name of the property to order by. property, boolean whether ordering for this property is ascending (true) or descending (false). isAscending, boolean whether or not to request case insensitive ordering from a database with case sensitive collation. ignoreCase) Defines sort criteria for an entity property.

Method Summary

Modifier and Type	Method and Description
public static < entity class of the sortable property. T> Sort<T>	Returns: a `Sort` instance. Never `null`. asc(String the property name to order by property) Create a `Sort` instance with `ascending direction` that does not request case insensitive ordering.
public static < entity class of the sortable property. T> Sort<T>	Returns: a `Sort` instance. Never `null`. ascIgnoreCase(String the property name to order by. property) Create a `Sort` instance with `ascending direction` and case insensitive ordering.
public static < entity class of the sortable property. T> Sort<T>	Returns: a `Sort` instance. Never `null`. desc(String the property name to order by property) Create a `Sort` instance with `descending direction` that does not request case insensitive ordering.
public static < entity class of the sortable property. T> Sort<T>	Returns: a `Sort` instance. Never `null`. descIgnoreCase(String the property name to order by. property) Create a `Sort` instance with `descending direction` and case insensitive ordering.
public final boolean	equals(Object the reference object with which to compare. o) Implements abstract java.lang.Record.equals. Indicates whether some other object is "equal to" this one.
public final int	hashCode() Implements abstract java.lang.Record.hashCode. Returns a hash code value for the record.
public boolean	Returns: Returns whether or not to request case insensitive sorting for the property. ignoreCase() Record Component getter of ignoreCase. Indicates whether or not to request case insensitive ordering from a database with case sensitive collation. Record Component whether or not to request case insensitive ordering from a database with case sensitive collation.
public boolean	Returns: Returns whether sorting for this property shall be ascending. isAscending() Record Component getter of isAscending. Indicates whether to sort the property in ascending order (true) or descending order (false). Record Component whether ordering for this property is ascending (true) or descending (false).
public boolean	Returns: Returns whether sorting for this property shall be descending. isDescending() Indicates whether to sort the property in descending order (true) or ascending order (false).
public static < entity class of the sortable property. T> Sort<T>	Returns: a `Sort` instance. Never `null`. of(String the property name to order by property, Direction the direction in which to order. direction, boolean whether to request a case insensitive ordering. ignoreCase) Create a `Sort` instance
public String	Returns: The property name to order by; will never be `null`. property() Record Component getter of property. Name of the property to order by. Record Component name of the property to order by.
public final String	toString() Implements abstract java.lang.Record.toString. Returns a string representation of the record.

Field Detail

ignoreCase	back to summary
private final boolean ignoreCase Record Component accessed by ignoreCase(). whether or not to request case insensitive ordering from a database with case sensitive collation.

ignoreCase

back to summary

private final boolean ignoreCase

Record Component accessed by ignoreCase().

whether or not to request case insensitive ordering from a database with case sensitive collation.

isAscending	back to summary
private final boolean isAscending Record Component accessed by isAscending(). whether ordering for this property is ascending (true) or descending (false).

isAscending

back to summary

private final boolean isAscending

Record Component accessed by isAscending().

whether ordering for this property is ascending (true) or descending (false).

property	back to summary
private final String property Record Component accessed by property(). name of the property to order by.

property

back to summary

private final String property

Record Component accessed by property().

name of the property to order by.

Constructor Detail

Sort back to summary

Sort	back to summary
public Sort(String property, boolean isAscending, boolean ignoreCase) Defines sort criteria for an entity property. For more descriptive code, use: `Sort.asc(propertyName)` for ascending sort on a property. `Sort.ascIgnoreCase(propertyName)` for case insensitive ascending sort on a property. `Sort.desc(propertyName)` for descending sort on a property. `Sort.descIgnoreCase(propertyName)` for case insensitive descending sort on a property. Parameters property:String name of the property to order by. isAscending:boolean whether ordering for this property is ascending (true) or descending (false). ignoreCase:boolean whether or not to request case insensitive ordering from a database with case sensitive collation.

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

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

Sort.asc(propertyName) for ascending sort on a property.
Sort.ascIgnoreCase(propertyName) for case insensitive ascending sort on a property.
Sort.desc(propertyName) for descending sort on a property.
Sort.descIgnoreCase(propertyName) for case insensitive descending sort on a property.

Parameters

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

Method Detail

asc back to summary

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

public static <T> Sort<T> asc(String property)

Create a Sort instance with ascending direction that does not request case insensitive ordering.

Parameters

<T>: entity class of the sortable property.
property:String: the property name to order by

Returns:Sort<T>

a Sort instance. Never null.

Exceptions

NullPointerException:: when the property is null

ascIgnoreCase back to summary

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

public static <T> Sort<T> ascIgnoreCase(String property)

Create a Sort instance with ascending direction and case insensitive ordering.

Parameters

<T>: entity class of the sortable property.
property:String: the property name to order by.

Returns:Sort<T>

a Sort instance. Never null.

Exceptions

NullPointerException:: when the property is null.

desc back to summary

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

public static <T> Sort<T> desc(String property)

Create a Sort instance with descending direction that does not request case insensitive ordering.

Parameters

<T>: entity class of the sortable property.
property:String: the property name to order by

Returns:Sort<T>

a Sort instance. Never null.

Exceptions

NullPointerException:: when the property is null

descIgnoreCase back to summary

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

public static <T> Sort<T> descIgnoreCase(String property)

Create a Sort instance with descending direction and case insensitive ordering.

Parameters

<T>: entity class of the sortable property.
property:String: the property name to order by.

Returns:Sort<T>

a Sort instance. Never null.

Exceptions

NullPointerException:: when the property is null.

equals back to summary

equals	back to summary
public final boolean equals(Object o) Implements abstract java.lang.Record.equals. Doc from java.lang.Record.equals. Indicates whether some other object is "equal to" this one. In addition to the general contract of `Object.equals`, record classes must further obey the invariant that when a record instance is "copied" by passing the result of the record component accessor methods to the canonical constructor, as follows: R copy = new R(r.c1(), r.c2(), ..., r.cn()); then it must be the case that `r.equals(copy)`. Parameters o:Object the reference object with which to compare. Returns:boolean `true` if this record is equal to the argument; `false` otherwise.

public final boolean equals(Object o)

Implements abstract java.lang.Record.equals.

Doc from java.lang.Record.equals.

Indicates whether some other object is "equal to" this one. In addition to the general contract of Object.equals, record classes must further obey the invariant that when a record instance is "copied" by passing the result of the record component accessor methods to the canonical constructor, as follows:

    R copy = new R(r.c1(), r.c2(), ..., r.cn());

then it must be the case that r.equals(copy).

Parameters

o:Object: the reference object with which to compare.

Returns:boolean

true if this record is equal to the argument; false otherwise.

hashCode back to summary

hashCode	back to summary
public final int hashCode() Implements abstract java.lang.Record.hashCode. Doc from java.lang.Record.hashCode. Returns a hash code value for the record. Obeys the general contract of `Object.hashCode`. For records, hashing behavior is constrained by the refined contract of `Record.equals`, so that any two records created from the same components must have the same hash code. Returns:int a hash code value for this record.

public final int hashCode()

Implements abstract java.lang.Record.hashCode.

Doc from java.lang.Record.hashCode.

Returns a hash code value for the record. Obeys the general contract of Object.hashCode. For records, hashing behavior is constrained by the refined contract of Record.equals, so that any two records created from the same components must have the same hash code.

Returns:int: a hash code value for this record.

ignoreCase back to summary

ignoreCase	back to summary
public boolean ignoreCase() Record Component getter of 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. Record Component whether or not to request case insensitive ordering from a database with case sensitive collation. Returns:boolean Returns whether or not to request case insensitive sorting for the property.

public boolean ignoreCase()

Record Component getter of 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.

Record Component: whether or not to request case insensitive ordering from a database with case sensitive collation.
Returns:boolean: Returns whether or not to request case insensitive sorting for the property.

isAscending	back to summary
public boolean isAscending() Record Component getter of isAscending. Indicates whether to sort the property in ascending order (true) or descending order (false). Record Component whether ordering for this property is ascending (true) or descending (false). Returns:boolean Returns whether sorting for this property shall be ascending.

isAscending

back to summary

public boolean isAscending()

Record Component getter of isAscending.

Indicates whether to sort the property in ascending order (true) or descending order (false).

Record Component: whether ordering for this property is ascending (true) or descending (false).
Returns:boolean: Returns whether sorting for this property shall be ascending.

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

isDescending

back to summary

public boolean isDescending()

Indicates whether to sort the property in descending order (true) or ascending order (false).

Returns:boolean: Returns whether sorting for this property shall be descending.

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

property back to summary

property	back to summary
public String property() Record Component getter of property. Name of the property to order by. Record Component name of the property to order by. Returns:String The property name to order by; will never be `null`.

public String property()

Record Component getter of property.

Name of the property to order by.

Record Component: name of the property to order by.
Returns:String: The property name to order by; will never be null.

toString back to summary

toString	back to summary
public final String toString() Implements abstract java.lang.Record.toString. Doc from java.lang.Record.toString. Returns a string representation of the record. In accordance with the general contract of `Object#toString()`, the `toString` method returns a string that "textually represents" this record. The result should be a concise but informative representation that is easy for a person to read. In addition to this general contract, record classes must further participate in the invariant that any two records which are equal must produce equal strings. This invariant is necessarily relaxed in the rare case where corresponding equal component values might fail to produce equal strings for themselves. Returns:String a string representation of the object.

public final String toString()

Implements abstract java.lang.Record.toString.

Doc from java.lang.Record.toString.

Returns a string representation of the record. In accordance with the general contract of Object#toString(), the toString method returns a string that "textually represents" this record. The result should be a concise but informative representation that is easy for a person to read.

In addition to this general contract, record classes must further participate in the invariant that any two records which are equal must produce equal strings. This invariant is necessarily relaxed in the rare case where corresponding equal component values might fail to produce equal strings for themselves.

Returns:String: a string representation of the object.

public final Record Sort<T>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail