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