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 type of the map key for associations of type <code>java.util.Map</code>. The map key can be a
020 * basic type, an embeddable class, or an entity. If the map is specified using Java generics, the
021 * <code>MapKeyClass</code> annotation and associated type need not be specified; otherwise they must be
022 * specified.
023 * <p>
024 * The <code>MapKeyClass</code> annotation is used in conjunction with <code>ElementCollection</code> or one
025 * of the collection-valued relationship annotations (<code>OneToMany</code> or <code>ManyToMany</code>). The
026 * <code>MapKey</code> annotation is not used when <code>MapKeyClass</code> is specified and vice versa.
027 * <p>
028 * <pre>
029 *
030 *    Example 1:
031 *
032 *    &#064;Entity
033 *    public class Item {
034 *       &#064;Id int id;
035 *       ...
036 *       &#064;ElementCollection(targetClass=String.class)
037 *       &#064;MapKeyClass(String.class)
038 *       Map images;  // map from image name to image filename
039 *       ...
040 *    }
041 *
042 *    Example 2:
043 *
044 *    // MapKeyClass and target type of relationship can be defaulted
045 *
046 *    &#064;Entity
047 *    public class Item {
048 *       &#064;Id int id;
049 *       ...
050 *       &#064;ElementCollection
051 *       Map&#060;String, String&#062; images;
052 *        ...
053 *     }
054 *
055 *     Example 3:
056 *
057 *     &#064;Entity
058 *     public class Company {
059 *        &#064;Id int id;
060 *        ...
061 *        &#064;OneToMany(targetEntity=com.example.VicePresident.class)
062 *        &#064;MapKeyClass(com.example.Division.class)
063 *        Map organization;
064 *     }
065 *
066 *     Example 4:
067 *
068 *     // MapKeyClass and target type of relationship are defaulted
069 *
070 *     &#064;Entity
071 *     public class Company {
072 *        &#064;Id int id;
073 *        ...
074 *        &#064;OneToMany
075 *        Map&#060;Division, VicePresident&#062; organization;
076 *     }
077 *
078 * </pre>
079 *
080 * @see ElementCollection
081 * @see OneToMany
082 * @see ManyToMany
083 * @since Java Persistence 2.0
084 */
085@Target({FIELD})
086@Retention(RUNTIME)
087public @interface MapKeyClass {
088  /**
089   * (Required) The type of the map key.
090   *
091   * @return The type
092   */
093  Class value();
094}