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 mapping to an entity that is a map key. The map key join column is in the collection table,
021 * join table, or table of the target entity that is used to represent the map. If no
022 * <code>MapKeyJoinColumn</code> annotation is specified, a single join column is assumed and the default
023 * values apply.
024 * <p>
025 * <pre>
026 *
027 *    Example 1:
028 *
029 *    &#064;Entity
030 *    public class Company {
031 *       &#064;Id int id;
032 *       ...
033 *       &#064;OneToMany   // unidirectional
034 *       &#064;JoinTable(name="COMPANY_ORGANIZATION",
035 *                  joinColumns=&#064;JoinColumn(name="COMPANY"),
036 *                  inverseJoinColumns=&#064;JoinColumn(name="VICEPRESIDENT"))
037 *       &#064;MapKeyJoinColumn(name="DIVISION")
038 *       Map&#060;Division, VicePresident&#062; organization;
039 *    }
040 *
041 *    Example 2:
042 *
043 *    &#064;Entity
044 *    public class VideoStore {
045 *       &#064;Id int id;
046 *       String name;
047 *       Address location;
048 *       ...
049 *       &#064;ElementCollection
050 *       &#064;CollectionTable(name="INVENTORY",
051 *                        joinColumns=&#064;JoinColumn(name="STORE"))
052 *       &#064;Column(name="COPIES_IN_STOCK")
053 *       &#064;MapKeyJoinColumn(name="MOVIE", referencedColumnName="ID")
054 *       Map&#060;Movie, Integer&#062; videoInventory;
055 *       ...
056 *     }
057 *
058 *     &#064;Entity
059 *     public class Movie {
060 *        &#064;Id long id;
061 *        String title;
062 *        ...
063 *     }
064 *
065 *     Example 3:
066 *
067 *     &#064;Entity
068 *     public class Student {
069 *        &#064;Id int studentId;
070 *        ...
071 *        &#064;ManyToMany  // students and courses are also many-many
072 *        &#064;JoinTable(name="ENROLLMENTS",
073 *                   joinColumns=&#064;JoinColumn(name="STUDENT"),
074 *                   inverseJoinColumns=&#064;JoinColumn(name="SEMESTER"))
075 *        &#064;MapKeyJoinColumn(name="COURSE")
076 *        Map&#060;Course, Semester&#062;  enrollment;
077 *        ...
078 *     }
079 * </pre>
080 *
081 * @since Java Persistence 2.0
082 */
083@Target({FIELD})
084@Retention(RUNTIME)
085@Repeatable(MapKeyJoinColumns.class)
086public @interface MapKeyJoinColumn {
087  /**
088   * (Optional) The name of the foreign key column for the map key. The table in which it is found depends
089   * upon the context.
090   * <ul>
091   * <li>If the join is for a map key for an element collection, the foreign key column is in the collection
092   * table for the map value.
093   * <li>If the join is for a map key for a ManyToMany entity relationship or for a OneToMany entity
094   * relationship using a join table, the foreign key column is in a join table.
095   * <li>If the join is for a OneToMany entity relationship using a foreign key mapping strategy, the
096   * foreign key column for the map key is in the table of the entity that is the value of the map.
097   * </ul>
098   * <p>
099   * Default (only applies if a single join column is used.) The concatenation of the following: the name of
100   * the referencing relationship property or field of the referencing entity or embeddable class; "_";
101   * "KEY".
102   *
103   * @return The name
104   */
105  String name() default "";
106
107  /**
108   * (Optional) The name of the column referenced by this foreign key column. The referenced column is in
109   * the table of the target entity.
110   * <p>
111   * Default (only applies if single join column is being used.) The same name as the primary key column of
112   * the referenced table
113   *
114   * @return The referenced col name
115   */
116  String referencedColumnName() default "";
117
118  /**
119   * (Optional) Whether the property is a unique key. This is a
120   * shortcut for the <code>UniqueConstraint</code> annotation
121   * at the table level and is useful for when the unique key
122   * constraint is only a single field.
123   *
124   * @return Whether unique
125   */
126  boolean unique() default false;
127
128  /**
129   * (Optional) Whether the foreign key column is nullable.
130   *
131   * @return Whether nullable
132   */
133  boolean nullable() default false;
134
135  /**
136   * (Optional) Whether the column is included in SQL INSERT statements generated by the persistence
137   * provider.
138   *
139   * @return Whether insertable
140   */
141  boolean insertable() default true;
142
143  /**
144   * (Optional) Whether the column is included in SQL UPDATE statements generated by the persistence
145   * provider.
146   *
147   * @return Whether updateable
148   */
149  boolean updatable() default true;
150
151  /**
152   * (Optional) The SQL fragment that is used when generating the DDL for the column. Defaults to SQL
153   * generated by the provider for the column.
154   *
155   * @return The column definition
156   */
157  String columnDefinition() default "";
158
159  /**
160   * (Optional) The name of the table that contains the foreign key column.
161   * <ul>
162   * <li>If the join is for a map key for an element collection, the foreign key column is in the collection
163   * table for the map value.
164   * <li>If the join is for a map key for a ManyToMany entity relationship or for a OneToMany entity
165   * relationship using a join table, the foreign key column is in a join table.
166   * <li>If the join is for a OneToMany entity relationship using a foreign key mapping strategy, the
167   * foreign key column for the map key is in the table of the entity that is the value of the map.
168   * </ul>
169   * <p>
170   * Default:
171   * <ul>
172   * <li>If the map is for an element collection, the name of the collection table for the map value.
173   * <li>If the map is for a OneToMany or ManyToMany entity relationship using a join table, the name of the
174   * join table for the map.
175   * <li>If the map is for a OneToMany entity relationship using a foreign key mapping strategy, the name of
176   * the primary table of the entity that is the value of the map.
177   * </ul>
178   *
179   * @return The table
180   */
181  String table() default "";
182
183  /**
184   * (Optional) The foreign key constraint specification for the join column. This is used only if table
185   * generation is in effect. Default is provider defined.
186   *
187   * @return The foreign key specification
188   */
189  ForeignKey foreignKey() default @ForeignKey();
190}