001/*
002 * Copyright (c) 2008, 2009, 2011 Oracle, Inc. All rights reserved.
003 *
004 * This program and the accompanying materials are made available under the
005 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0
006 * which accompanies this distribution.  The Eclipse Public License is available
007 * at http://www.eclipse.org/legal/epl-v10.html and the Eclipse Distribution License
008 * is available at http://www.eclipse.org/org/documents/edl-v10.php.
009 */
010package javax.persistence;
011
012import java.lang.annotation.Retention;
013import java.lang.annotation.Target;
014
015import static java.lang.annotation.ElementType.FIELD;
016import static java.lang.annotation.RetentionPolicy.RUNTIME;
017
018/**
019 * Specifies the ordering of the elements of a collection valued association or element collection at the
020 * point when the association or collection is retrieved.
021 * <p>
022 * The syntax of the <code>value</code> ordering element is an <code>orderby_list</code>, as follows:
023 * <p>
024 * <pre>
025 *    orderby_list::= orderby_item [,orderby_item]*
026 *    orderby_item::= [property_or_field_name] [ASC | DESC]
027 * </pre>
028 * <p>
029 * If <code>ASC</code> or <code>DESC</code> is not specified, <code>ASC</code> (ascending order) is assumed.
030 * <p>
031 * If the ordering element is not specified for an entity association, ordering by the primary key of the
032 * associated entity is assumed.
033 * <p>
034 * The property or field name must correspond to that of a persistent property or field of the associated
035 * class or embedded class within it. The properties or fields used in the ordering must correspond to columns
036 * for which comparison operators are supported.
037 * <p>
038 * The dot (".") notation is used to refer to an attribute within an embedded attribute. The value of each
039 * identifier used with the dot notation is the name of the respective embedded field or property.
040 * <p>
041 * The <code>OrderBy</code> annotation may be applied to an element collection. When <code>OrderBy</code> is
042 * applied to an element collection of basic type, the ordering will be by value of the basic objects and the
043 * property or field name is not used. When specifying an ordering over an element collection of embeddable
044 * type, the dot notation must be used to specify the attribute or attributes that determine the ordering.
045 * <p>
046 * The <code>OrderBy</code> annotation is not used when an order column is specified.
047 * <p>
048 * <pre>
049 *    Example 1:
050 *
051 *    &#064;Entity
052 *    public class Course {
053 *       ...
054 *       &#064;ManyToMany
055 *       &#064;OrderBy("lastname ASC")
056 *       List&#060;Student&#062; students;
057 *       ...
058 *    }
059 *
060 *    Example 2:
061 *
062 *    &#064;Entity
063 *    public class Student {
064 *       ...
065 *       &#064;ManyToMany(mappedBy="students")
066 *       &#064;OrderBy // ordering by primary key is assumed
067 *       List&#060;Course&#062; courses;
068 *       ...
069 *    }
070 *
071 *    Example 3:
072 *
073 *    &#064;Entity
074 *    public class Person {
075 *         ...
076 *       &#064;ElementCollection
077 *       &#064;OrderBy("zipcode.zip, zipcode.plusFour")
078 *       Set&#060;Address&#062; residences;
079 *       ...
080 *    }
081 *
082 *    &#064;Embeddable
083 *    public class Address {
084 *       protected String street;
085 *       protected String city;
086 *       protected String state;
087 *       &#064;Embedded protected Zipcode zipcode;
088 *    }
089 *
090 *    &#064;Embeddable
091 *    public class Zipcode {
092 *       protected String zip;
093 *       protected String plusFour;
094 *    }
095 * </pre>
096 *
097 * @see OrderColumn
098 * @since Java Persistence 1.0
099 */
100@Target({FIELD})
101@Retention(RUNTIME)
102public @interface OrderBy {
103
104  /**
105   * An <code>orderby_list</code>. Specified as follows:
106   * <p>
107   * <pre>
108   *    orderby_list::= orderby_item [,orderby_item]*
109   *    orderby_item::= [property_or_field_name] [ASC | DESC]
110   * </pre>
111   * <p>
112   * If <code>ASC</code> or <code>DESC</code> is not specified, <code>ASC</code> (ascending order) is
113   * assumed.
114   * <p>
115   * If the ordering element is not specified, ordering by the primary key of the associated entity is
116   * assumed.
117   *
118   * @return the ordering clause
119   */
120  String value() default "";
121}