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