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 * Designates a <code>ManyToOne</code> or <code>OneToOne</code> relationship attribute that provides the
021 * mapping for an {@link EmbeddedId} primary key, an attribute within an <code>EmbeddedId</code> primary key,
022 * or a simple primary key of the parent entity. The <code>value</code> element specifies the attribute within
023 * a composite key to which the relationship attribute corresponds. If the entity's primary key is of the same
024 * Java type as the primary key of the entity referenced by the relationship, the value attribute is not
025 * specified.
026 * <p>
027 * <pre>
028 *    Example:
029 *
030 *    // parent entity has simple primary key
031 *
032 *    &#064;Entity
033 *    public class Employee {
034 *       &#064;Id long empId;
035 *       String name;
036 *       ...
037 *    }
038 *
039 *    // dependent entity uses EmbeddedId for composite key
040 *
041 *    &#064;Embeddable
042 *    public class DependentId {
043 *       String name;
044 *       long empid;   // corresponds to primary key type of Employee
045 *    }
046 *
047 *    &#064;Entity
048 *    public class Dependent {
049 *       &#064;EmbeddedId DependentId id;
050 *        ...
051 *       &#064;MapsId("empid")  //  maps the empid attribute of embedded id
052 *       &#064;ManyToOne Employee emp;
053 *    }
054 * </pre>
055 *
056 * @since Java Persistence 2.0
057 */
058@Target({METHOD, FIELD})
059@Retention(RUNTIME)
060public @interface MapsId {
061
062  /**
063   * (Optional) The name of the attribute within the composite key to which the relationship attribute
064   * corresponds. If not supplied, the relationship maps the entitys primary key.
065   *
066   * @return name
067   */
068  String value() default "";
069}