javax.persistence.OrderBy Maven / Gradle / Ivy
/*
* Copyright (c) 2008, 2009, 2011 Oracle, Inc. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0
* which accompanies this distribution. The Eclipse Public License is available
* at http://www.eclipse.org/legal/epl-v10.html and the Eclipse Distribution License
* is available at http://www.eclipse.org/org/documents/edl-v10.php.
*/
package javax.persistence;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
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")
* List<Student> students;
* ...
* }
*
* Example 2:
*
* @Entity
* public class Student {
* ...
* @ManyToMany(mappedBy="students")
* @OrderBy // ordering by primary key is assumed
* List<Course> courses;
* ...
* }
*
* Example 3:
*
* @Entity
* public class Person {
* ...
* @ElementCollection
* @OrderBy("zipcode.zip, zipcode.plusFour")
* Set<Address> residences;
* ...
* }
*
* @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({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.
*
* @return the ordering clause
*/
String value() default "";
}