javax.persistence.AssociationOverride Maven / Gradle / Ivy

/*
 * Copyright (c) 2008, 2009, 2011 Oracle, Inc. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0
 * which accompanies this distribution.  The Eclipse Public License is available
 * at http://www.eclipse.org/legal/epl-v10.html and the Eclipse Distribution License
 * is available at http://www.eclipse.org/org/documents/edl-v10.php.
 */
package javax.persistence;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.Repeatable;

/**
 * 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;
 *     }
 * 
 * @see Embedded
 * @see Embeddable
 * @see MappedSuperclass
 * @see AttributeOverride
 * @since Java Persistence 1.0
 */
@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
@Repeatable(AssociationOverrides.class)
public @interface AssociationOverride
{

    /**
     * (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.
     * @return name
     */
    String name();

    /**
     * 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.
     * @return join cols
     */
    JoinColumn[] joinColumns() default {};

    /**
     * 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
     * @return join table
     */
    JoinTable joinTable() default @JoinTable;

    /**
     * (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.
     * @since Java Persistence 2.1
     * @return FK
     */
    ForeignKey foreignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT);
}