1 /* 2 * The contents of this file are subject to the terms 3 * of the Common Development and Distribution License 4 * (the License). You may not use this file except in 5 * compliance with the License. 6 * 7 * You can obtain a copy of the license at 8 * https://glassfish.dev.java.net/public/CDDLv1.0.html or 9 * glassfish/bootstrap/legal/CDDLv1.0.txt. 10 * See the License for the specific language governing 11 * permissions and limitations under the License. 12 * 13 * When distributing Covered Code, include this CDDL 14 * Header Notice in each file and include the License file 15 * at glassfish/bootstrap/legal/CDDLv1.0.txt. 16 * If applicable, add the following below the CDDL Header, 17 * with the fields enclosed by brackets [] replaced by 18 * you own identifying information: 19 * "Portions Copyrighted [year] [name of copyright owner]" 20 * 21 * Copyright 2006 Sun Microsystems, Inc. All rights reserved. 22 */ 23 package javax.persistence; 24 25 import java.lang.annotation.Target; 26 import java.lang.annotation.Retention; 27 import static java.lang.annotation.ElementType.METHOD; 28 import static java.lang.annotation.ElementType.FIELD; 29 import static java.lang.annotation.RetentionPolicy.RUNTIME; 30 31 /** 32 * This annotation specifies the ordering of the elements of a 33 * collection valued association at the point when the association 34 * is retrieved. 35 * 36 * <p> The syntax of the <code>value</code> ordering element is an 37 * <code>orderby_list</code>, as follows: 38 * 39 * <pre> 40 * orderby_list::= orderby_item [,orderby_item]* 41 * orderby_item::= property_or_field_name [ASC | DESC] 42 * </pre> 43 * 44 * <p> If <code>ASC</code> or <code>DESC</code> is not specified, 45 * <code>ASC</code> (ascending order) is assumed. 46 * 47 * <p> If the ordering element is not specified, ordering by 48 * the primary key of the associated entity is assumed. 49 * 50 * <p> The property or field name must correspond to that of a 51 * persistent property or field of the associated class. The 52 * properties or fields used in the ordering must correspond to 53 * columns for which comparison operators are supported. 54 * 55 * <pre> 56 * Example: 57 * 58 * @Entity public class Course { 59 * ... 60 * @ManyToMany 61 * @OrderBy("lastname ASC") 62 * public List<Student> getStudents() {...}; 63 * ... 64 * } 65 * 66 * @Entity public class Student { 67 * ... 68 * @ManyToMany(mappedBy="students") 69 * @OrderBy // PK is assumed 70 * public List<Course> getCourses() {...}; 71 * ... 72 * } 73 * </pre> 74 * 75 * @since Java Persistence 1.0 76 */ 77 @Target({METHOD, FIELD}) 78 @Retention(RUNTIME) 79 80 public @interface OrderBy { 81 82 /** 83 * An <code>orderby_list</code>, specified as follows: 84 * 85 * <pre> 86 * orderby_list::= orderby_item [,orderby_item]* 87 * orderby_item::= property_or_field_name [ASC | DESC] 88 * </pre> 89 * 90 * <p> If <code>ASC</code> or <code>DESC</code> is not specified, 91 * <code>ASC</code> (ascending order) is assumed. 92 * 93 * <p> If the ordering element is not specified, ordering by 94 * the primary key of the associated entity is assumed. 95 */ 96 String value() default ""; 97 } 98