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