Copyright (c) 2008 - 2013 Oracle Corporation. 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.
Contributors:
Linda DeMichiel - Java Persistence 2.1
Linda DeMichiel - Java Persistence 2.0
/*******************************************************************************
* Copyright (c) 2008 - 2013 Oracle Corporation. 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.
*
* Contributors:
* Linda DeMichiel - Java Persistence 2.1
* Linda DeMichiel - Java Persistence 2.0
*
******************************************************************************/
package javax.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 Also: - OrderColumn
Since: Java Persistence 1.0
/**
* Specifies the ordering of the elements of a collection valued
* association or element collection at the point when the association
* or collection is retrieved.
*
* <p> The syntax of the <code>value</code> ordering element is an
* <code>orderby_list</code>, as follows:
*
* <pre>
* orderby_list::= orderby_item [,orderby_item]*
* orderby_item::= [property_or_field_name] [ASC | DESC]
* </pre>
*
* <p> If <code>ASC</code> or <code>DESC</code> is not specified,
* <code>ASC</code> (ascending order) is assumed.
*
* <p> If the ordering element is not specified for an entity association,
* ordering by the primary key of the associated entity is assumed.
*
* <p> 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.
*
* <p> 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.
*
* <p> The <code>OrderBy</code> annotation may be applied to an element
* collection. When <code>OrderBy</code> 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.
*
* <p> The <code>OrderBy</code> annotation is not used when an order
* column is specified.
*
*
* <pre>
* 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;
* }
* </pre>
*
* @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.
/**
* An <code>orderby_list</code>. Specified as follows:
*
* <pre>
* orderby_list::= orderby_item [,orderby_item]*
* orderby_item::= [property_or_field_name] [ASC | DESC]
* </pre>
*
* <p> If <code>ASC</code> or <code>DESC</code> is not specified,
* <code>ASC</code> (ascending order) is assumed.
*
* <p> If the ordering element is not specified, ordering by
* the primary key of the associated entity is assumed.
*/
String value() default "";
}