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