javax.persistence.JoinTable Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of javax.persistence Show documentation
The Java Persistence API (JPA) : a standard interface-based Java model abstraction of persistence, developed by the JCP.
There is a newer version: 2.2.4
Show newest version
/*
 * Copyright (c) 2008, 2009, 2011 Oracle, Inc. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0
 * which accompanies this distribution.  The Eclipse Public License is available
 * at http://www.eclipse.org/legal/epl-v10.html and the Eclipse Distribution License
 * is available at http://www.eclipse.org/org/documents/edl-v10.php.
 */
package javax.persistence;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

/**
 * Used in the mapping of associations. It is specified on the owning side of an association.
 * 
 * A join table is typically used in the mapping of many-to-many and unidirectional one-to-many associations.
 * It may also be used to map bidirectional many-to-one/one-to-many associations, unidirectional many-to-one
 * relationships, and one-to-one associations (both bidirectional and unidirectional).
 * 

 * When a join table is used in mapping a relationship with an embeddable class on the owning side of the
 * relationship, the containing entity rather than the embeddable class is considered the owner of the
 * relationship.
 * 

 * If the JoinTable annotation is missing, the default values of the annotation elements apply.
 * The name of the join table is assumed to be the table names of the associated primary tables concatenated
 * together (owning side first) using an underscore.
 *
 * 
 *
 *    Example:
 * 
 *    @JoinTable(
 *        name="CUST_PHONE",
 *        joinColumns=
 *            @JoinColumn(name="CUST_ID", referencedColumnName="ID"),
 *        inverseJoinColumns=
 *            @JoinColumn(name="PHONE_ID", referencedColumnName="ID")
 *    )
 * 
 * @see JoinColumn
 * @see JoinColumns
 * @since Java Persistence 1.0
 */
@Target({ANNOTATION_TYPE, METHOD, FIELD})
@Retention(RUNTIME)
public @interface JoinTable
{

    /**
     * (Optional) The name of the join table.
     * Defaults to the concatenated names of the two associated primary entity tables, separated by an
     * underscore.
     * @return The name
     */
    String name() default "";

    /**
     * (Optional) The catalog of the table.
     * Defaults to the default catalog.
     * @return The catalog
     */
    String catalog() default "";

    /**
     * (Optional) The schema of the table.
     * Defaults to the default schema for user.
     * @return The schema
     */
    String schema() default "";

    /**
     * (Optional) The foreign key columns of the join table which reference the primary table of the entity
     * owning the association. (I.e. the owning side of the association).
     * Uses the same defaults as for {@link JoinColumn}.
     * @return The join columns
     */
    JoinColumn[] joinColumns() default {};

    /**
     * (Optional) The foreign key columns of the join table which reference the primary table of the entity
     * that does not own the association. (I.e. the inverse side of the association).
     * Uses the same defaults as for {@link JoinColumn}.
     * @return The inverse join cols
     */
    JoinColumn[] inverseJoinColumns() default {};

    /**
     * (Optional) Unique constraints that are to be placed on the table. These are only used if table
     * generation is in effect.
     * Defaults to no additional constraints.
     * @return The unique constraints
     */
    UniqueConstraint[] uniqueConstraints() default {};

    /**
     * (Optional) Indexes for the table. These are only used if table generation is in effect.
     * @return The indexes
     */
    Index[] indexes() default {};

    /**
     * (Optional) Used to specify or control the generation of a foreign key constraint for the columns
     * corresponding to the joinColumns element when table generation is in effect.
     * @since Java Persistence 2.1
     * @return The foreign key
     */
    ForeignKey foreignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT);

    /**
     * (Optional) Used to specify or control the generation of a foreign key constraint for the columns
     * corresponding to the inverseJoinColumns element when table generation is in effect.
     * @since Java Persistence 2.1
     * @return The inverse fk
     */
    ForeignKey inverseForeignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT);
}