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.*;
016import static java.lang.annotation.RetentionPolicy.RUNTIME;
017
018/**
019 * Defines a primary key generator that may be referenced by name when a generator element is specified for
020 * the {@link GeneratedValue} annotation. A table generator may be specified on the entity class or on the
021 * primary key field or property. The scope of the generator name is global to the persistence unit (across
022 * all generator types).
023 * <p>
024 * <pre>
025 *    Example 1:
026 *
027 *    &#064;Entity public class Employee {
028 *        ...
029 *        &#064;TableGenerator(
030 *            name="empGen",
031 *            table="ID_GEN",
032 *            pkColumnName="GEN_KEY",
033 *            valueColumnName="GEN_VALUE",
034 *            pkColumnValue="EMP_ID",
035 *            allocationSize=1)
036 *        &#064;Id
037 *        &#064;GeneratedValue(strategy=TABLE, generator="empGen")
038 *        int id;
039 *        ...
040 *    }
041 *
042 *    Example 2:
043 *
044 *    &#064;Entity public class Address {
045 *        ...
046 *        &#064;TableGenerator(
047 *            name="addressGen",
048 *            table="ID_GEN",
049 *            pkColumnName="GEN_KEY",
050 *            valueColumnName="GEN_VALUE",
051 *            pkColumnValue="ADDR_ID")
052 *        &#064;Id
053 *        &#064;GeneratedValue(strategy=TABLE, generator="addressGen")
054 *        int id;
055 *        ...
056 *    }
057 * </pre>
058 *
059 * @see GeneratedValue
060 * @since Java Persistence 1.0
061 */
062@Target({TYPE, METHOD, FIELD})
063@Retention(RUNTIME)
064public @interface TableGenerator {
065  /**
066   * (Required) A unique generator name that can be referenced by one or more classes to be the generator
067   * for id values.
068   *
069   * @return name
070   */
071  String name();
072
073  /**
074   * (Optional) Name of table that stores the generated id values.
075   * Defaults to a name chosen by persistence provider.
076   *
077   * @return table
078   */
079  String table() default "";
080
081  /**
082   * (Optional) The catalog of the table. Defaults to the default catalog.
083   *
084   * @return catalog
085   */
086  String catalog() default "";
087
088  /**
089   * (Optional) The schema of the table. Defaults to the default schema for user.
090   *
091   * @return schema
092   */
093  String schema() default "";
094
095  /**
096   * (Optional) Name of the primary key column in the table. Defaults to a provider-chosen name.
097   *
098   * @return pk col name
099   */
100  String pkColumnName() default "";
101
102  /**
103   * (Optional) Name of the column that stores the last value generated. Defaults to a provider-chosen name.
104   *
105   * @return value column name
106   */
107  String valueColumnName() default "";
108
109  /**
110   * (Optional) The primary key value in the generator table that distinguishes this set of generated values
111   * from others that may be stored in the table. Defaults to a provider-chosen value to store in the
112   * primary key column of the generator table
113   *
114   * @return pk col val
115   */
116  String pkColumnValue() default "";
117
118  /**
119   * (Optional) The initial value to be used to initialize the column that stores the last value generated.
120   *
121   * @return init val
122   */
123  int initialValue() default 0;
124
125  /**
126   * (Optional) The amount to increment by when allocating id numbers from the generator.
127   *
128   * @return alloc size
129   */
130  int allocationSize() default 50;
131
132  /**
133   * (Optional) Unique constraints that are to be placed on the table. These are only used if table
134   * generation is in effect. These constraints apply in addition to primary key constraints. Defaults to no
135   * additional constraints.
136   *
137   * @return unique constraints
138   */
139  UniqueConstraint[] uniqueConstraints() default {};
140
141  /**
142   * (Optional) Indexes for the table. These are only used if table generation is in effect.
143   *
144   * @return The indexes
145   */
146  Index[] indexes() default {};
147}