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.Retention;
013import java.lang.annotation.Target;
014
015import static java.lang.annotation.ElementType.FIELD;
016import static java.lang.annotation.RetentionPolicy.RUNTIME;
017
018/**
019 * Specifies the mapping for the key column of a map whose map key is a basic type. If the <code>name</code>
020 * element is not specified, it defaults to the concatenation of the following: the name of the referencing
021 * relationship field or property; "_"; "KEY".
022 * <p>
023 * <pre>
024 *    Example:
025 *
026 *    &#064;Entity
027 *    public class Item {
028 *       &#064;Id int id;
029 *       ...
030 *       &#064;ElementCollection
031 *       &#064;MapKeyColumn(name="IMAGE_NAME")
032 *       &#064;Column(name="IMAGE_FILENAME")
033 *       &#064;CollectionTable(name="IMAGE_MAPPING")
034 *       Map&#060;String, String&#062; images;  // map from image name to filename
035 *       ...
036 *    }
037 * </pre>
038 *
039 * @since Java Persistence 2.0
040 */
041@Target({FIELD})
042@Retention(RUNTIME)
043public @interface MapKeyColumn {
044  /**
045   * (Optional) The name of the map key column. The table in which it is found depends upon the context. If
046   * the map key is for an element collection, the map key column is in the collection table for the map
047   * value. If the map key is for a ManyToMany entity relationship or for a OneToMany entity relationship
048   * using a join table, the map key column is in a join table. If the map key is for a OneToMany entity
049   * relationship using a foreign key mapping strategy, the map key column is in the table of the entity
050   * that is the value of the map.
051   * <p>
052   * Defaults to the concatenation of the following: the name of the referencing relationship field or
053   * property; "_"; "<code>KEY</code>".
054   *
055   * @return The name
056   */
057  String name() default "";
058
059  /**
060   * (Optional) Whether the column is a unique key. This is a shortcut for the <code>UniqueConstraint</code>
061   * annotation at the table level and is useful for when the unique key constraint corresponds to only a
062   * single column. This constraint applies in addition to any constraint entailed by primary key mapping
063   * and to constraints specified at the table level.
064   *
065   * @return Whether unique
066   */
067  boolean unique() default false;
068
069  /**
070   * (Optional) Whether the database column is nullable.
071   *
072   * @return Whether nullable
073   */
074  boolean nullable() default false;
075
076  /**
077   * (Optional) Whether the column is included in SQL INSERT statements generated by the persistence
078   * provider.
079   *
080   * @return Whether insertable
081   */
082  boolean insertable() default true;
083
084  /**
085   * (Optional) Whether the column is included in SQL UPDATE statements generated by the persistence
086   * provider.
087   *
088   * @return Whether updateable
089   */
090  boolean updatable() default true;
091
092  /**
093   * (Optional) The SQL fragment that is used when generating the DDL for the column.
094   * <p>
095   * Defaults to the generated SQL to create a column of the inferred type.
096   *
097   * @return The column definition
098   */
099  String columnDefinition() default "";
100
101  /**
102   * (Optional) The name of the table that contains the column.
103   * <p>
104   * Defaults: If the map key is for an element collection, the name of the collection table for the map
105   * value. If the map key is for a OneToMany or ManyToMany entity relationship using a join table, the name
106   * of the join table for the map. If the map key is for a OneToMany entity relationship using a foreign
107   * key mapping strategy, the name of the primary table of the entity that is the value of the map.
108   *
109   * @return The table
110   */
111  String table() default "";
112
113  /**
114   * (Optional) The column length. (Applies only if a string-valued column is used.)
115   *
116   * @return The length
117   */
118  int length() default 255;
119
120  /**
121   * (Optional) The precision for a decimal (exact numeric) column. (Applies only if a decimal column is
122   * used.)
123   * <p>
124   * Default: 0. (The value must be set by the developer.)
125   *
126   * @return The precision
127   */
128  int precision() default 0; // decimal precision
129
130  /**
131   * (Optional) The scale for a decimal (exact numeric) column. (Applies only if a decimal column is used.)
132   *
133   * @return The scale
134   */
135  int scale() default 0; // decimal scale
136}