Interface Order<X>

Type Parameters:

X - The result type of the query to be sorted

@Incubating(since="6.3",
            group="query-specifications")
public interface Order<X>

A rule for sorting a query result set. This allows query result ordering rules to be passed around the system before being applied to a QuerySpecification by calling sort().

SelectionSpecification.create(Book.class,
            "from Book b join b.authors a where a.name = :name")
        .sort(asc(Book_.publicationDate))
        .createQuery(session)
        .setParameter("name", authorName)
        .getResultList();

Orders may be stacked using List.of() and resort().

SelectionSpecification.create(Book.class,
            "from Book b join b.authors a where a.name = :name")
        .sort(List.of(asc(Book_.publicationDate), desc(Book_.ssn)))
        .setParameter("name", authorName)
        .getResultList();

A parameter of a finder method or HQL query method may be declared with type Order<? super E>, List<Order<? super E>>, or Order<? super E>... (varargs) where E is the entity type returned by the query.

Since:

6.3

See Also:

• SelectionSpecification.sort(Order)
• SelectionSpecification.resort(List)
• Restriction

API Note:

This class is similar to jakarta.data.Sort, and is used by Hibernate Data Repositories to implement Jakarta Data query methods.

Method Summary

Modifier and Type	Method	Description
default void	apply(CriteriaQuery<?> query, Root<?> root, CriteriaBuilder builder)	Apply this order to the given root entity of the given criteria query.
static Order<Object[]>	asc(int element)	An order where the result set is sorted by the select item in the given position with smaller values first.
static <T> Order<T>	asc(SingularAttribute<T,?> attribute)	An order where an entity is sorted by the given attribute, with smaller values first.
static <T> Order<T>	asc(Class<T> entityClass, String attributeName)	An order where an entity of the given class is sorted by the attribute with the given name, with smaller values first.
SingularAttribute<X,?>	attribute()	For an order based on an entity attribute, the metamodel object representing the attribute.
String	attributeName()	For an order based on an entity attribute, the name of the attribute.
static Order<Object[]>	by(int element, SortDirection direction)	An order where the result set is sorted by the select item in the given position, in the given direction.
static Order<Object[]>	by(int element, SortDirection direction, boolean ignoreCase)	An order where the result set is sorted by the select item in the given position in the given direction, with the specified case-sensitivity.
static Order<Object[]>	by(int element, SortDirection direction, Nulls nullPrecedence)	An order where the result set is sorted by the select item in the given position in the given direction, with the specified precedence for null values.
static <T> Order<T>	by(SingularAttribute<T,?> attribute, SortDirection direction)	An order where an entity is sorted by the given attribute, in the given direction.
static <T> Order<T>	by(SingularAttribute<T,?> attribute, SortDirection direction, boolean ignoreCase)	An order where an entity is sorted by the given attribute, in the given direction, with the specified case-sensitivity.
static <T> Order<T>	by(SingularAttribute<T,?> attribute, SortDirection direction, Nulls nullPrecedence)	An order where an entity is sorted by the given attribute, in the given direction, with the specified precedence for null values.
static <T> Order<T>	by(Class<T> entityClass, String attributeName, SortDirection direction)	An order where an entity of the given class is sorted by the attribute with the given name, in the given direction.
static <T> Order<T>	by(Class<T> entityClass, String attributeName, SortDirection direction, boolean ignoreCase)	An order where an entity of the given class is sorted by the attribute with the given name, in the given direction, with the specified case-sensitivity.
static <T> Order<T>	by(Class<T> entityClass, String attributeName, SortDirection direction, Nulls nullPrecedence)	An order where an entity of the given class is sorted by the attribute with the given name, in the given direction.
boolean	caseSensitive()	For a lexicographic order based on textual values, whether case is significant.
static Order<Object[]>	desc(int element)	An order where the result set is sorted by the select item in the given position with larger values first.
static <T> Order<T>	desc(SingularAttribute<T,?> attribute)	An order where an entity is sorted by the given attribute, with larger values first.
static <T> Order<T>	desc(Class<T> entityClass, String attributeName)	An order where an entity of the given class is sorted by the attribute with the given name, with larger values first.
SortDirection	direction()	The direction, ascending or descending, in which results are sorted.
int	element()	For an order based on an indexed element of the select clause, the index of the element.
Class<X>	entityClass()	For an order based on an entity attribute, the entity class which declares the attribute.
default SingularAttribute<X,?>	getAttribute()	Deprecated, for removal: This API element is subject to removal in a future version.
default String	getAttributeName()	Deprecated, for removal: This API element is subject to removal in a future version.
default SortDirection	getDirection()	Deprecated, for removal: This API element is subject to removal in a future version.
default int	getElement()	Deprecated, for removal: This API element is subject to removal in a future version.
default Class<X>	getEntityClass()	Deprecated, for removal: This API element is subject to removal in a future version.
default Nulls	getNullPrecedence()	Deprecated, for removal: This API element is subject to removal in a future version.
Order<X>	ignoringCase()
default Order<X>	ignoringCaseIf(boolean ignoreCase)	An order based on this order, possibly without case-sensitivity.
default boolean	isCaseInsensitive()	Deprecated, for removal: This API element is subject to removal in a future version.
Nulls	nullPrecedence()	The ordering of null values.
Order<X>	reverse()
static <T> List<Order<? super T>>	reverse(List<Order<? super T>> ordering)	Reverse the direction of the given ordering list
default Order<X>	reversedIf(boolean reverse)	An order based on this order, possibly reversed.
Order<X>	withNullsFirst()
Order<X>	withNullsLast()

Method Details

asc

@Nonnull
static <T> Order<T> asc(@Nonnull
 SingularAttribute<T,?> attribute)

An order where an entity is sorted by the given attribute, with smaller values first. If the given attribute is of textual type, the ordering is case-sensitive.

desc

@Nonnull
static <T> Order<T> desc(@Nonnull
 SingularAttribute<T,?> attribute)

An order where an entity is sorted by the given attribute, with larger values first. If the given attribute is of textual type, the ordering is case-sensitive.

by

@Nonnull
static <T> Order<T> by(@Nonnull
 SingularAttribute<T,?> attribute,
 @Nonnull
 SortDirection direction)

An order where an entity is sorted by the given attribute, in the given direction. If the given attribute is of textual type, the ordering is case-sensitive.

by

@Nonnull
static <T> Order<T> by(@Nonnull
 SingularAttribute<T,?> attribute,
 @Nonnull
 SortDirection direction,
 boolean ignoreCase)

An order where an entity is sorted by the given attribute, in the given direction, with the specified case-sensitivity.

by

@Nonnull
static <T> Order<T> by(@Nonnull
 SingularAttribute<T,?> attribute,
 @Nonnull
 SortDirection direction,
 @Nonnull
 Nulls nullPrecedence)

An order where an entity is sorted by the given attribute, in the given direction, with the specified precedence for null values. If the given attribute is of textual type, the ordering is case-sensitive.

asc

@Nonnull
static <T> Order<T> asc(@Nonnull
 Class<T> entityClass,
 @Nonnull
 String attributeName)

An order where an entity of the given class is sorted by the attribute with the given name, with smaller values first. If the named attribute is of textual type, the ordering is case-sensitive.

desc

@Nonnull
static <T> Order<T> desc(@Nonnull
 Class<T> entityClass,
 @Nonnull
 String attributeName)

An order where an entity of the given class is sorted by the attribute with the given name, with larger values first. If the named attribute is of textual type, the ordering is case-sensitive.

by

@Nonnull
static <T> Order<T> by(@Nonnull
 Class<T> entityClass,
 @Nonnull
 String attributeName,
 @Nonnull
 SortDirection direction)

An order where an entity of the given class is sorted by the attribute with the given name, in the given direction. If the named attribute is of textual type, the ordering is case-sensitive.

by

@Nonnull
static <T> Order<T> by(@Nonnull
 Class<T> entityClass,
 @Nonnull
 String attributeName,
 @Nonnull
 SortDirection direction,
 boolean ignoreCase)

An order where an entity of the given class is sorted by the attribute with the given name, in the given direction, with the specified case-sensitivity.

by

@Nonnull
static <T> Order<T> by(@Nonnull
 Class<T> entityClass,
 @Nonnull
 String attributeName,
 @Nonnull
 SortDirection direction,
 @Nonnull
 Nulls nullPrecedence)

An order where an entity of the given class is sorted by the attribute with the given name, in the given direction. If the named attribute is of textual type, with the specified precedence for null values. If the named attribute is of textual type, the ordering is case-sensitive.

asc

@Nonnull
static Order<Object[]> asc(int element)

An order where the result set is sorted by the select item in the given position with smaller values first. If the item is of textual type, the ordering is case-sensitive.

desc

@Nonnull
static Order<Object[]> desc(int element)

An order where the result set is sorted by the select item in the given position with larger values first. If the item is of textual type, the ordering is case-sensitive.

by

@Nonnull
static Order<Object[]> by(int element,
 @Nonnull
 SortDirection direction)

An order where the result set is sorted by the select item in the given position, in the given direction. If the item is of textual type, the ordering is case-sensitive.

by

@Nonnull
static Order<Object[]> by(int element,
 @Nonnull
 SortDirection direction,
 boolean ignoreCase)

An order where the result set is sorted by the select item in the given position in the given direction, with the specified case-sensitivity.

by

@Nonnull
static Order<Object[]> by(int element,
 @Nonnull
 SortDirection direction,
 @Nonnull
 Nulls nullPrecedence)

An order where the result set is sorted by the select item in the given position in the given direction, with the specified precedence for null values. If the named attribute is of textual type, the ordering is case-sensitive.

direction

@Nonnull
SortDirection direction()

The direction, ascending or descending, in which results are sorted.

Since:

7

nullPrecedence

@Nonnull
Nulls nullPrecedence()

The ordering of null values.

Since:

7

caseSensitive

boolean caseSensitive()

For a lexicographic order based on textual values, whether case is significant.

Since:

7

entityClass

@Nullable
Class<X> entityClass()

For an order based on an entity attribute, the entity class which declares the attribute.

Returns:

the Java class which declares the attribute, or null if this order is not based on an attribute

Since:

7

attributeName

@Nullable
String attributeName()

For an order based on an entity attribute, the name of the attribute.

Returns:

the name of the attribute, or null if this order is not based on an attribute

Since:

7

attribute

@Nullable
SingularAttribute<X,?> attribute()

For an order based on an entity attribute, the metamodel object representing the attribute.

Returns:

the attribute, or null if this order is not based on an attribute, or if only the name of the attribute was specified

Since:

7

element

int element()

For an order based on an indexed element of the select clause, the index of the element.

Returns:

the index, or 1 is this order is based on an entity attribute

Since:

7

reverse

@Nonnull
Order<X> reverse()

Returns:

this order, but with the sorting direction reversed.

Since:

6.5

ignoringCase

@Nonnull
Order<X> ignoringCase()

Returns:

this order, but without case-sensitivity.

Since:

6.5

withNullsFirst

@Nonnull
Order<X> withNullsFirst()

Returns:

this order, but with nulls sorted first.

Since:

6.5

withNullsLast

@Nonnull
Order<X> withNullsLast()

Returns:

this order, but with nulls sorted last.

Since:

6.5

reversedIf

@Nonnull
default Order<X> reversedIf(boolean reverse)

An order based on this order, possibly reversed.

Parameters:

reverse - true if the returned order should be reversed

Returns:

this order, but reversed if the argument is true

Since:

7.0

API Note:

This is a convenience for use with Jakarta Data

ignoringCaseIf

@Nonnull
default Order<X> ignoringCaseIf(boolean ignoreCase)

An order based on this order, possibly without case-sensitivity.

Parameters:

ignoreCase - true if this order should ignore case

Returns:

this order, but ignoring case if the argument is true

Since:

7.0

API Note:

This is a convenience for use with Jakarta Data

apply

@Incubating(since="8.0",
            group="query-specifications")
default void apply(@Nonnull
 CriteriaQuery<?> query,
 @Nonnull
 Root<?> root,
 @Nonnull
 CriteriaBuilder builder)

Apply this order to the given root entity of the given criteria query.

Since:

8.0

reverse

@Nonnull
static <T> List<Order<? super T>> reverse(@Nonnull
 List<Order<? super T>> ordering)

Reverse the direction of the given ordering list

Parameters:

ordering - a list of Order items

Returns:

a new list, with each Order reversed

Since:

6.5

See Also:

• reverse()

getDirection

@Nonnull
@Deprecated(since="7",
            forRemoval=true)
default SortDirection getDirection()

Deprecated, for removal: This API element is subject to removal in a future version.

getNullPrecedence

@Nonnull
@Deprecated(since="7",
            forRemoval=true)
default Nulls getNullPrecedence()

Deprecated, for removal: This API element is subject to removal in a future version.

isCaseInsensitive

@Deprecated(since="7",
            forRemoval=true)
default boolean isCaseInsensitive()

Deprecated, for removal: This API element is subject to removal in a future version.

getAttribute

@Nullable
@Deprecated(since="7",
            forRemoval=true)
default SingularAttribute<X,?> getAttribute()

Deprecated, for removal: This API element is subject to removal in a future version.

getEntityClass

@Nullable
@Deprecated(since="7",
            forRemoval=true)
default Class<X> getEntityClass()

Deprecated, for removal: This API element is subject to removal in a future version.

getAttributeName

@Nullable
@Deprecated(since="7",
            forRemoval=true)
default String getAttributeName()

Deprecated, for removal: This API element is subject to removal in a future version.

getElement

@Deprecated(since="7",
            forRemoval=true)
default int getElement()

Deprecated, for removal: This API element is subject to removal in a future version.