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