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