javax.persistence.OrderBy Maven / Gradle / Ivy
package javax.persistence;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
/**
* 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 Java Persistence 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 "";
}