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 a column that is used to maintain the persistent order of a list. The persistence provider is
021 * responsible for maintaining the order upon retrieval and in the database. The persistence provider is
022 * responsible for updating the ordering upon flushing to the database to reflect any insertion, deletion, or
023 * reordering affecting the list.
024 * <p>
025 * The <code>OrderColumn</code> annotation is specified on a OneToMany or ManyToMany relationship or on an
026 * element collection. The <code>OrderColumn</code> annotation is specified on the side of the relationship
027 * that references the collection that is to be ordered. The order column is not visible as part of the state
028 * of the entity or embeddable class.
029 * <p>
030 * The {@link OrderBy} annotation should be used for ordering that is visible as persistent state and
031 * maintained by the application. The <code>OrderBy</code> annotation is not used when
032 * <code>OrderColumn</code> is specified.
033 * <p>
034 * The order column must be of integral type. The persistence provider maintains a contiguous (non-sparse)
035 * ordering of the values of the order column when updating the association or element collection. The order
036 * column value for the first element is 0.
037 * <p>
038 * <pre>
039 *
040 *    Example:
041 *
042 *    &#064;Entity
043 *    public class CreditCard {
044 *
045 *       &#064;Id long ccNumber;
046 *
047 *       &#064;OneToMany  // unidirectional
048 *       &#064;OrderColumn
049 *       List&#060;CardTransaction&#062; transactionHistory;
050 *       ...
051 *    }
052 *
053 * </pre>
054 *
055 * @see OrderBy
056 * @since Java Persistence 2.0
057 */
058@Target({METHOD, FIELD})
059@Retention(RUNTIME)
060public @interface OrderColumn {
061
062  /**
063   * (Optional) The name of the ordering column. Defaults to the concatenation of the name of the
064   * referencing property or field; "_"; "ORDER".
065   *
066   * @return name
067   */
068  String name() default "";
069
070  /**
071   * (Optional) Whether the database column is nullable.
072   *
073   * @return whether nullable
074   */
075  boolean nullable() default true;
076
077  /**
078   * (Optional) Whether the column is included in SQL INSERT statements generated by the persistence
079   * provider.
080   *
081   * @return whether insertable
082   */
083  boolean insertable() default true;
084
085  /**
086   * (Optional) Whether the column is included in SQL UPDATE statements generated by the persistence
087   * provider.
088   *
089   * @return whether updateable
090   */
091  boolean updatable() default true;
092
093  /**
094   * (Optional) The SQL fragment that is used when generating the DDL for the column. Defaults to generated
095   * SQL to create a column of the inferred type.
096   *
097   * @return column definition
098   */
099  String columnDefinition() default "";
100}