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 * Used in the mapping of associations. It is specified on the owning side of an association.
020 * <p>
021 * A join table is typically used in the mapping of many-to-many and unidirectional one-to-many associations.
022 * It may also be used to map bidirectional many-to-one/one-to-many associations, unidirectional many-to-one
023 * relationships, and one-to-one associations (both bidirectional and unidirectional).
024 * <p>
025 * When a join table is used in mapping a relationship with an embeddable class on the owning side of the
026 * relationship, the containing entity rather than the embeddable class is considered the owner of the
027 * relationship.
028 * <p>
029 * If the <code>JoinTable</code> annotation is missing, the default values of the annotation elements apply.
030 * The name of the join table is assumed to be the table names of the associated primary tables concatenated
031 * together (owning side first) using an underscore.
032 * <p>
033 * <pre>
034 *
035 *    Example:
036 *
037 *    &#064;JoinTable(
038 *        name="CUST_PHONE",
039 *        joinColumns=
040 *            &#064;JoinColumn(name="CUST_ID", referencedColumnName="ID"),
041 *        inverseJoinColumns=
042 *            &#064;JoinColumn(name="PHONE_ID", referencedColumnName="ID")
043 *    )
044 * </pre>
045 *
046 * @see JoinColumn
047 * @see JoinColumns
048 * @since Java Persistence 1.0
049 */
050@Target({FIELD})
051@Retention(RUNTIME)
052public @interface JoinTable {
053
054  /**
055   * (Optional) The name of the join table.
056   * Defaults to the concatenated names of the two associated primary entity tables, separated by an
057   * underscore.
058   *
059   * @return The name
060   */
061  String name() default "";
062
063  /**
064   * (Optional) The catalog of the table.
065   * Defaults to the default catalog.
066   *
067   * @return The catalog
068   */
069  String catalog() default "";
070
071  /**
072   * (Optional) The schema of the table.
073   * Defaults to the default schema for user.
074   *
075   * @return The schema
076   */
077  String schema() default "";
078
079  /**
080   * (Optional) The foreign key columns of the join table which reference the primary table of the entity
081   * owning the association. (I.e. the owning side of the association).
082   * Uses the same defaults as for {@link JoinColumn}.
083   *
084   * @return The join columns
085   */
086  JoinColumn[] joinColumns() default {};
087
088  /**
089   * (Optional) The foreign key columns of the join table which reference the primary table of the entity
090   * that does not own the association. (I.e. the inverse side of the association).
091   * Uses the same defaults as for {@link JoinColumn}.
092   *
093   * @return The inverse join cols
094   */
095  JoinColumn[] inverseJoinColumns() default {};
096
097  /**
098   * (Optional) Unique constraints that are to be placed on the table. These are only used if table
099   * generation is in effect.
100   * Defaults to no additional constraints.
101   *
102   * @return The unique constraints
103   */
104  UniqueConstraint[] uniqueConstraints() default {};
105
106  /**
107   * (Optional) Indexes for the table. These are only used if table generation is in effect.
108   *
109   * @return The indexes
110   */
111  Index[] indexes() default {};
112
113  /**
114   * (Optional) Used to specify or control the generation of a foreign key constraint for the columns
115   * corresponding to the joinColumns element when table generation is in effect.
116   *
117   * @return The foreign key
118   * @since Java Persistence 2.1
119   */
120  ForeignKey foreignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT);
121
122  /**
123   * (Optional) Used to specify or control the generation of a foreign key constraint for the columns
124   * corresponding to the inverseJoinColumns element when table generation is in effect.
125   *
126   * @return The inverse fk
127   * @since Java Persistence 2.1
128   */
129  ForeignKey inverseForeignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT);
130}