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 a persistent field or property of an entity whose
020 * value is an instance of an embeddable class. The embeddable
021 * class must be annotated as {@link Embeddable}.
022 * <p>
023 * <p> The <code>AttributeOverride</code>, <code>AttributeOverrides</code>,
024 * <code>AssociationOverride</code>, and <code>AssociationOverrides</code>
025 * annotations may be used to override mappings declared or defaulted
026 * by the embeddable class.
027 * <p>
028 * <pre>
029 *   Example:
030 *
031 *   &#064;Embedded
032 *   &#064;AttributeOverrides({
033 *       &#064;AttributeOverride(name="startDate", column=&#064;Column("EMP_START")),
034 *       &#064;AttributeOverride(name="endDate", column=&#064;Column("EMP_END"))
035 *   })
036 *   public EmploymentPeriod getEmploymentPeriod() { ... }
037 * </pre>
038 *
039 * @see Embeddable
040 * @see AttributeOverride
041 * @see AttributeOverrides
042 * @see AssociationOverride
043 * @see AssociationOverrides
044 * @since Java Persistence 1.0
045 */
046@Target({FIELD})
047@Retention(RUNTIME)
048public @interface Embedded {
049
050  /**
051   * WARNING: This is an Ebean extension (not yet part of JPA standard, refer to JPA_SPEC-23).
052   * <p>
053   * When specified all the properties in the embedded bean have a prefix applied to their DB column name.
054   * </p>
055   * <h3>Example:</h3>
056   * <p/>
057   * <pre>{@code
058   *
059   *  @Entity
060   *  public class Invoice {
061   *    ...
062   *
063   *    @Embedded(prefix="ship_")
064   *    Address shipAddress;
065   *
066   *    @Embedded(prefix="bill_")
067   *    Address billAddress;
068   *
069   * }</pre>
070   * <p>
071   * Without this extension we need to specify AttributeOverride on each property like:
072   * </p>
073   * <pre>{@code
074   *
075   *  @Entity
076   *  public class Invoice {
077   *    ...
078   *
079   *    @Embedded
080   *    @AttributeOverride(name = "street", column = @Column(name = "ship_street"))
081   *    @AttributeOverride(name = "suburb", column = @Column(name = "ship_suburb"))
082   *    @AttributeOverride(name = "city", column = @Column(name = "ship_city"))
083   *    @AttributeOverride(name = "status", column = @Column(name = "ship_status"))
084   *    Address shipAddress;
085   *
086   *
087   *    @Embedded
088   *    @AttributeOverride(name = "street", column = @Column(name = "bill_street"))
089   *    @AttributeOverride(name = "suburb", column = @Column(name = "bill_suburb"))
090   *    @AttributeOverride(name = "city", column = @Column(name = "bill_city"))
091   *    @AttributeOverride(name = "status", column = @Column(name = "bill_status"))
092   *    Address billAddress;
093   *
094   * }</pre>
095   */
096  String prefix() default "";
097}