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