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.FIELD;
017import static java.lang.annotation.ElementType.METHOD;
018import static java.lang.annotation.RetentionPolicy.RUNTIME;
019
020/**
021 * Specifies a column for joining an entity association or element collection. If the <code>JoinColumn</code>
022 * annotation itself is defaulted, a single join column is assumed and the default values apply.
023 * <p>
024 * <pre>
025 *   Example:
026 *
027 *   &#064;ManyToOne
028 *   &#064;JoinColumn(name="ADDR_ID")
029 *   public Address getAddress() { return address; }
030 *
031 *
032 *   Example: unidirectional one-to-many association using a foreign key mapping
033 *
034 *   // In Customer class
035 *   &#064;OneToMany
036 *   &#064;JoinColumn(name="CUST_ID") // join column is in table for Order
037 *   public Set&#060;Order&#062; getOrders() {return orders;}
038 * </pre>
039 *
040 * @see ManyToOne
041 * @see OneToMany
042 * @see OneToOne
043 * @see JoinTable
044 * @see CollectionTable
045 * @since Java Persistence 1.0
046 */
047@Target({METHOD, FIELD})
048@Retention(RUNTIME)
049@Repeatable(JoinColumns.class)
050public @interface JoinColumn {
051
052  /**
053   * (Optional) The name of the foreign key column. The table in which it is found depends upon the context.
054   * <ul>
055   * <li>If the join is for a OneToOne or ManyToOne mapping using a foreign key mapping strategy, the
056   * foreign key column is in the table of the source entity or embeddable.
057   * <li>If the join is for a unidirectional OneToMany mapping using a foreign key mapping strategy, the
058   * foreign key is in the table of the target entity.
059   * <li>If the join is for a ManyToMany mapping or for a OneToOne or bidirectional ManyToOne/OneToMany
060   * mapping using a join table, the foreign key is in a join table.
061   * <li>If the join is for an element collection, the foreign key is in a collection table.
062   * </ul>
063   * <p>
064   * Default (only applies if a single join column is used): The concatenation of the following: the name of
065   * the referencing relationship property or field of the referencing entity or embeddable class; "_"; the
066   * name of the referenced primary key column. If there is no such referencing relationship property or
067   * field in the entity, or if the join is for an element collection, the join column name is formed as the
068   * concatenation of the following: the name of the entity; "_"; the name of the referenced primary key
069   * column.
070   *
071   * @return The name
072   */
073  String name() default "";
074
075  /**
076   * (Optional) The name of the column referenced by this foreign key column.
077   * <ul>
078   * <li>When used with entity relationship mappings other than the cases described here, the referenced
079   * column is in the table of the target entity.
080   * <li>When used with a unidirectional OneToMany foreign key mapping, the referenced column is in the
081   * table of the source entity.
082   * <li>When used inside a <code>JoinTable</code> annotation, the referenced key column is in the entity
083   * table of the owning entity, or inverse entity if the join is part of the inverse join definition.
084   * <li>When used in a <code>CollectionTable</code> mapping, the referenced column is in the table of the
085   * entity containing the collection.
086   * </ul>
087   * <p>
088   * Default (only applies if single join column is being used): The same name as the primary key column of
089   * the referenced table.
090   *
091   * @return The referenced col name
092   */
093  String referencedColumnName() default "";
094
095  /**
096   * (Optional) Whether the property is a unique key. This is a shortcut for the
097   * <code>UniqueConstraint</code> annotation at the table level and is useful for when the unique key
098   * constraint is only a single field. It is not necessary to explicitly specify this for a join column
099   * that corresponds to a primary key that is part of a foreign key.
100   *
101   * @return whether this col is unique
102   */
103  boolean unique() default false;
104
105  /**
106   * (Optional) Whether the foreign key column is nullable.
107   *
108   * @return Whether this col is nullable
109   */
110  boolean nullable() default true;
111
112  /**
113   * (Optional) Whether the column is included in SQL INSERT statements generated by the persistence
114   * provider.
115   *
116   * @return Whether insertable
117   */
118  boolean insertable() default true;
119
120  /**
121   * (Optional) Whether the column is included in SQL UPDATE statements generated by the persistence
122   * provider.
123   *
124   * @return Whether updateable
125   */
126  boolean updatable() default true;
127
128  /**
129   * (Optional) The SQL fragment that is used when generating the DDL for the column.
130   * <p>
131   * Defaults to the generated SQL for the column.
132   *
133   * @return The column definition
134   */
135  String columnDefinition() default "";
136
137  /**
138   * (Optional) The name of the table that contains the column. If a table is not specified, the column is
139   * assumed to be in the primary table of the applicable entity.
140   * <p>
141   * Default:
142   * <ul>
143   * <li>If the join is for a OneToOne or ManyToOne mapping using a foreign key mapping strategy, the name
144   * of the table of the source entity or embeddable.
145   * <li>If the join is for a unidirectional OneToMany mapping using a foreign key mapping strategy, the
146   * name of the table of the target entity.
147   * <li>If the join is for a ManyToMany mapping or for a OneToOne or bidirectional ManyToOne/OneToMany
148   * mapping using a join table, the name of the join table.
149   * <li>If the join is for an element collection, the name of the collection table.
150   * </ul>
151   *
152   * @return Table
153   */
154  String table() default "";
155
156  /**
157   * (Optional) The foreign key constraint specification for the join column. This is used only if table
158   * generation is in effect. Default is provider defined.
159   *
160   * @return The foreign key specification
161   */
162  ForeignKey foreignKey() default @ForeignKey();
163}