javax.persistence

## Annotation Type AssociationOverride

-     @Target(value={TYPE,METHOD,FIELD})
      @Retention(value=RUNTIME)
      public @interface AssociationOverride

  Used to override a mapping for an entity relationship.

  May be applied to an entity that extends a mapped superclass to override a relationship mapping defined by the mapped superclass. If not specified, the association is mapped the same as in the original mapping. When used to override a mapping defined by a mapped superclass, `AssociationOverride` is applied to the entity class.

  May be used to override a relationship mapping from an embeddable within an entity to another entity when the embeddable is on the owning side of the relationship. When used to override a relationship mapping defined by an embeddable class (including an embeddable class embedded within another embeddable class), `AssociationOverride` is applied to the field or property containing the embeddable.

  When `AssociationOverride` is used to override a relationship mapping from an embeddable class, the `name` element specifies the referencing relationship field or property within the embeddable class. To override mappings at multiple levels of embedding, a dot (".") notation syntax must be used in the `name` element to indicate an attribute within an embedded attribute. The value of each identifier used with the dot notation is the name of the respective embedded field or property.

  When `AssociationOverride` is applied to override the mappings of an embeddable class used as a map value, "`value.`" must be used to prefix the name of the attribute within the embeddable class that is being overridden in order to specify it as part of the map value.

  If the relationship mapping is a foreign key mapping, the `joinColumns` element is used. If the relationship mapping uses a join table, the `joinTable` element must be specified to override the mapping of the join table and/or its join columns.

          Example 1: Overriding the mapping of a relationship defined by a mapped superclass

          @MappedSuperclass
          public class Employee {
              ...
              @ManyToOne
              protected Address address;
              ...
          }

          @Entity
              @AssociationOverride(name="address",
                                   joinColumns=@JoinColumn(name="ADDR_ID"))
              // address field mapping overridden to ADDR_ID foreign key
          public class PartTimeEmployee extends Employee {
              ...
          }

          Example 2: Overriding the mapping for phoneNumbers defined in the ContactInfo class

          @Entity
          public class Employee {
              @Id int id;
              @AssociationOverride(
                name="phoneNumbers",
                joinTable=@JoinTable(
                   name="EMPPHONES",
                   joinColumns=@JoinColumn(name="EMP"),
                   inverseJoinColumns=@JoinColumn(name="PHONE")
                )
              )
              @Embedded ContactInfo contactInfo;
             ...
          }

          @Embeddable
          public class ContactInfo {
              @ManyToOne Address address; // Unidirectional
              @ManyToMany(targetEntity=PhoneNumber.class) List phoneNumbers;
          }

          @Entity
          public class PhoneNumber {
              @Id int number;
              @ManyToMany(mappedBy="contactInfo.phoneNumbers")
              Collection<Employee> employees;
           }

  Since:
    Java Persistence 1.0
  See Also:
    `Embedded`, `Embeddable`, `MappedSuperclass`, `AttributeOverride`

- - ### Required Element Summary

    Required Elements
    Modifier and Type | Required Element and Description
    --- | ---
    `String` | `name` (Required) The name of the relationship property whose mapping is being overridden if property-based access is being used, or the name of the relationship field if field-based access is used.

  - ### Optional Element Summary

    Optional Elements
    Modifier and Type | Optional Element and Description
    --- | ---
    `ForeignKey` | `foreignKey` (Optional) Used to specify or control the generation of a foreign key constraint for the columns corresponding to the `joinColumns` element when table generation is in effect.
    `JoinColumn[]` | `joinColumns` The join column(s) being mapped to the persistent attribute(s).
    `JoinTable` | `joinTable` The join table that maps the relationship.

- - ### Element Detail

    - #### name

          public abstract String name

      (Required) The name of the relationship property whose mapping is being overridden if property-based access is being used, or the name of the relationship field if field-based access is used.

    - #### joinColumns

          public abstract JoinColumn[] joinColumns

      The join column(s) being mapped to the persistent attribute(s). The `joinColumns` elements must be specified if a foreign key mapping is used in the overriding of the mapping of the relationship. The `joinColumns` element must not be specified if a join table is used in the overriding of the mapping of the relationship.
      Default:
        {}

    - #### foreignKey

          public abstract ForeignKey foreignKey

      (Optional) Used to specify or control the generation of a foreign key constraint for the columns corresponding to the `joinColumns` element when table generation is in effect. If both this element and the `foreignKey` element of any of the `joinColumns` elements are specified, the behavior is undefined. If no foreign key annotation element is specified in either location, the persistence provider's default foreign key strategy will apply.
      Since:
        Java Persistence 2.1
      Default:
        @javax.persistence.ForeignKey(javax.persistence.ConstraintMode.PROVIDER_DEFAULT)

    - #### joinTable

          public abstract JoinTable joinTable

      The join table that maps the relationship. The `joinTable` element must be specified if a join table is used in the overriding of the mapping of the relationship. The `joinTable` element must not be specified if a foreign key mapping is used in the overriding of the relationship.
      Since:
        Java Persistence 2.0
      Default:
        @javax.persistence.JoinTable

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.