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.ElementType.METHOD;
017import static java.lang.annotation.RetentionPolicy.RUNTIME;
018
019/**
020 * Specifies the ordering of the elements of a collection valued association or element collection at the
021 * point when the association or collection is retrieved.
022 * <p>
023 * The syntax of the <code>value</code> ordering element is an <code>orderby_list</code>, as follows:
024 * <p>
025 * <pre>
026 *    orderby_list::= orderby_item [,orderby_item]*
027 *    orderby_item::= [property_or_field_name] [ASC | DESC]
028 * </pre>
029 * <p>
030 * If <code>ASC</code> or <code>DESC</code> is not specified, <code>ASC</code> (ascending order) is assumed.
031 * <p>
032 * If the ordering element is not specified for an entity association, ordering by the primary key of the
033 * associated entity is assumed.
034 * <p>
035 * The property or field name must correspond to that of a persistent property or field of the associated
036 * class or embedded class within it. The properties or fields used in the ordering must correspond to columns
037 * for which comparison operators are supported.
038 * <p>
039 * The dot (".") notation is used to refer to an attribute within an embedded attribute. The value of each
040 * identifier used with the dot notation is the name of the respective embedded field or property.
041 * <p>
042 * The <code>OrderBy</code> annotation may be applied to an element collection. When <code>OrderBy</code> is
043 * applied to an element collection of basic type, the ordering will be by value of the basic objects and the
044 * property or field name is not used. When specifying an ordering over an element collection of embeddable
045 * type, the dot notation must be used to specify the attribute or attributes that determine the ordering.
046 * <p>
047 * The <code>OrderBy</code> annotation is not used when an order column is specified.
048 * <p>
049 * <pre>
050 *    Example 1:
051 *
052 *    &#064;Entity
053 *    public class Course {
054 *       ...
055 *       &#064;ManyToMany
056 *       &#064;OrderBy("lastname ASC")
057 *       public List&#060;Student&#062; getStudents() {...};
058 *       ...
059 *    }
060 *
061 *    Example 2:
062 *
063 *    &#064;Entity
064 *    public class Student {
065 *       ...
066 *       &#064;ManyToMany(mappedBy="students")
067 *       &#064;OrderBy // ordering by primary key is assumed
068 *       public List&#060;Course&#062; getCourses() {...};
069 *       ...
070 *    }
071 *
072 *    Example 3:
073 *
074 *    &#064;Entity
075 *    public class Person {
076 *         ...
077 *       &#064;ElementCollection
078 *       &#064;OrderBy("zipcode.zip, zipcode.plusFour")
079 *       public Set&#060;Address&#062; getResidences() {...};
080 *       ...
081 *    }
082 *
083 *    &#064;Embeddable
084 *    public class Address {
085 *       protected String street;
086 *       protected String city;
087 *       protected String state;
088 *       &#064;Embedded protected Zipcode zipcode;
089 *    }
090 *
091 *    &#064;Embeddable
092 *    public class Zipcode {
093 *       protected String zip;
094 *       protected String plusFour;
095 *    }
096 * </pre>
097 *
098 * @see OrderColumn
099 * @since Java Persistence 1.0
100 */
101@Target({METHOD, FIELD})
102@Retention(RUNTIME)
103public @interface OrderBy {
104
105  /**
106   * An <code>orderby_list</code>. Specified as follows:
107   * <p>
108   * <pre>
109   *    orderby_list::= orderby_item [,orderby_item]*
110   *    orderby_item::= [property_or_field_name] [ASC | DESC]
111   * </pre>
112   * <p>
113   * If <code>ASC</code> or <code>DESC</code> is not specified, <code>ASC</code> (ascending order) is
114   * assumed.
115   * <p>
116   * If the ordering element is not specified, ordering by the primary key of the associated entity is
117   * assumed.
118   *
119   * @return the ordering clause
120   */
121  String value() default "";
122}