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 * Applied to a persistent field or property of an entity
020 * class or mapped superclass to denote a composite primary
021 * key that is an embeddable class. The embeddable class
022 * must be annotated as {@link Embeddable}.
023 * <p>
024 * <p> There must be only one <code>EmbeddedId</code> annotation and
025 * no <code>Id</code> annotation when the <code>EmbeddedId</code> annotation is used.
026 * <p>
027 * <p> The {@link AttributeOverride} annotation may be used to override
028 * the column mappings declared within the embeddable class.
029 * <p>
030 * <p> The {@link MapsId} annotation may be used in conjunction
031 * with the <code>EmbeddedId</code> annotation to specify a derived
032 * primary key.
033 * <p>
034 * <p> If the entity has a derived primary key, the
035 * <code>AttributeOverride</code> annotation may only be used to
036 * override those attributes of the embedded id that do not correspond
037 * to the relationship to the parent entity.
038 * <p>
039 * <p> Relationship mappings defined within an embedded id class are not supported.
040 * <p>
041 * <pre>
042 *    Example 1:
043 *
044 *    &#064;EmbeddedId
045 *    protected EmployeePK empPK;
046 *
047 *
048 *    Example 2:
049 *
050 *    &#064;Embeddable
051 *    public class DependentId {
052 *       String name;
053 *       EmployeeId empPK;   // corresponds to primary key type of Employee
054 *    }
055 *
056 *    &#064;Entity
057 *    public class Dependent {
058 *       // default column name for "name" attribute is overridden
059 *       &#064;AttributeOverride(name="name", &#064;Column(name="dep_name"))
060 *       &#064;EmbeddedId DependentId id;
061 *       ...
062 *       &#064;MapsId("empPK")
063 *       &#064;ManyToOne Employee emp;
064 *    }
065 * </pre>
066 *
067 * @see Embeddable
068 * @see MapsId
069 * @since Java Persistence 1.0
070 */
071@Target({FIELD})
072@Retention(RUNTIME)
073public @interface EmbeddedId {
074}