| /* |
| * Copyright (c) 2008, 2018 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 - 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. |
| * |
| * <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 <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 ""; |
| } |