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.Repeatable;
013import java.lang.annotation.Retention;
014import java.lang.annotation.Target;
015
016import static java.lang.annotation.ElementType.TYPE;
017import static java.lang.annotation.RetentionPolicy.RUNTIME;
018
019/**
020 * Specifies a secondary table for the annotated entity
021 * class. Specifying one or more secondary tables indicates that the
022 * data for the entity class is stored across multiple tables.
023 * <p>
024 * <p> If no <code>SecondaryTable</code> annotation is specified,
025 * it is assumed that all persistent fields or properties of the
026 * entity are mapped to the primary table. If no primary key join
027 * columns are specified, the join columns are assumed to reference
028 * the primary key columns of the primary table, and have the same
029 * names and types as the referenced primary key columns of the
030 * primary table.
031 * <p>
032 * <pre>
033 *    Example 1: Single secondary table with a single primary key column.
034 *
035 *    &#064;Entity
036 *    &#064;Table(name="CUSTOMER")
037 *    &#064;SecondaryTable(name="CUST_DETAIL",
038 *        pkJoinColumns=&#064;PrimaryKeyJoinColumn(name="CUST_ID"))
039 *    public class Customer { ... }
040 *
041 *
042 *    Example 2: Single secondary table with multiple primary key columns.
043 *
044 *    &#064;Entity
045 *    &#064;Table(name="CUSTOMER")
046 *    &#064;SecondaryTable(name="CUST_DETAIL",
047 *        pkJoinColumns={
048 *            &#064;PrimaryKeyJoinColumn(name="CUST_ID"),
049 *            &#064;PrimaryKeyJoinColumn(name="CUST_TYPE")})
050 *    public class Customer { ... }
051 * </pre>
052 *
053 * @since Java Persistence 1.0
054 */
055@Target(TYPE)
056@Retention(RUNTIME)
057@Repeatable(SecondaryTables.class)
058public @interface SecondaryTable {
059  /**
060   * (Required) The name of the table.
061   *
062   * @return name
063   */
064  String name();
065
066  /**
067   * (Optional) The catalog of the table.
068   * <p>
069   * Defaults to the default catalog.
070   *
071   * @return catalog
072   */
073  String catalog() default "";
074
075  /**
076   * (Optional) The schema of the table.
077   * <p>
078   * Defaults to the default schema for user.
079   *
080   * @return schema
081   */
082  String schema() default "";
083
084  /**
085   * (Optional) The columns that are used to join with the primary table.
086   * <p>
087   * Defaults to the column(s) of the same name(s) as the primary key column(s) in the primary table.
088   *
089   * @return pk join cols
090   */
091  PrimaryKeyJoinColumn[] pkJoinColumns() default {};
092
093  /**
094   * (Optional) Unique constraints that are to be placed on the table. These are typically only used if
095   * table generation is in effect. These constraints apply in addition to any constraints specified by the
096   * <code>Column</code> and <code>JoinColumn</code> annotations and constraints entailed by primary key
097   * mappings.
098   * <p>
099   * Defaults to no additional constraints.
100   *
101   * @return unique constraints
102   */
103  UniqueConstraint[] uniqueConstraints() default {};
104
105  /**
106   * (Optional) Indexes for the table. These are only used if table generation is in effect.
107   *
108   * @return The indexes
109   */
110  Index[] indexes() default {};
111
112  /**
113   * (Optional) Used to specify or control the generation of a foreign key constraint for the columns
114   * corresponding to the pkJoinColumns element when table generation is in effect.
115   *
116   * @return fk
117   * @since Java Persistence 2.1
118   */
119  ForeignKey foreignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT);
120}