jakarta.persistence.OrderBy Maven / Gradle / Ivy
Show all versions of jakarta.persistence-api Show documentation
/*
* Copyright (c) 2008, 2020 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0,
* or the Eclipse Distribution License v. 1.0 which is available at
* http://www.eclipse.org/org/documents/edl-v10.php.
*
* SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
*/
// Contributors:
// Linda DeMichiel - 2.1
// Linda DeMichiel - 2.0
package jakarta.persistence;
import java.lang.annotation.Target;
import java.lang.annotation.Retention;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Specifies the ordering of the elements of a collection valued
* association or element collection at the point when the association
* or collection is retrieved.
*
* The syntax of the value ordering element is an
* orderby_list, as follows:
*
*
* orderby_list::= orderby_item [,orderby_item]*
* orderby_item::= [property_or_field_name] [ASC | DESC]
*
*
* If ASC or DESC is not specified,
* ASC (ascending order) is assumed.
*
*
If the ordering element is not specified for an entity association,
* ordering by the primary key of the associated entity is assumed.
*
*
The property or field name must correspond to that of a
* persistent property or field of the associated class or embedded class
* within it. The properties or fields used in the ordering must correspond to
* columns for which comparison operators are supported.
*
*
The dot (".") notation is used to refer to an attribute within an
* embedded attribute. The value of each identifier used with the dot
* notation is the name of the respective embedded field or property.
*
*
The OrderBy annotation may be applied to an element
* collection. When OrderBy is applied to an element collection of
* basic type, the ordering will be by value of the basic objects and
* the property or field name is not used. When specifying an ordering
* over an element collection of embeddable type, the dot notation
* must be used to specify the attribute or attributes that determine
* the ordering.
*
*
The OrderBy annotation is not used when an order
* column is specified.
*
*
*
* Example 1:
*
* @Entity
* public class Course {
* ...
* @ManyToMany
* @OrderBy("lastname ASC")
* public List<Student> getStudents() {...};
* ...
* }
*
* Example 2:
*
* @Entity
* public class Student {
* ...
* @ManyToMany(mappedBy="students")
* @OrderBy // ordering by primary key is assumed
* public List<Course> getCourses() {...};
* ...
* }
*
* Example 3:
*
* @Entity
* public class Person {
* ...
* @ElementCollection
* @OrderBy("zipcode.zip, zipcode.plusFour")
* public Set<Address> getResidences() {...};
* ...
* }
*
* @Embeddable
* public class Address {
* protected String street;
* protected String city;
* protected String state;
* @Embedded protected Zipcode zipcode;
* }
*
* @Embeddable
* public class Zipcode {
* protected String zip;
* protected String plusFour;
* }
*
*
* @see OrderColumn
*
* @since 1.0
*/
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface OrderBy {
/**
* An orderby_list. Specified as follows:
*
*
* orderby_list::= orderby_item [,orderby_item]*
* orderby_item::= [property_or_field_name] [ASC | DESC]
*
*
* If ASC or DESC is not specified,
* ASC (ascending order) is assumed.
*
*
If the ordering element is not specified, ordering by
* the primary key of the associated entity is assumed.
*/
String value() default "";
}