javax.persistence.AssociationOverride Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of hibernate-jpa-2.0-api
Hibernate definition of the Java Persistence 2.0 (JSR 317) API.
The newest version!
/*
 * Copyright (c) 2008, 2009 Sun Microsystems. 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.
 *
 * Contributors:
 *     Linda DeMichiel - Java Persistence 2.0 - Version 2.0 (October 1, 2009)
 *     Specification available from http://jcp.org/en/jsr/detail?id=317
 */

// $Id: AssociationOverride.java 20957 2011-06-13 09:58:51Z stliu $

package javax.persistence;

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

/**
 * 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)

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.
     */
    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.
     */
    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
     */
    JoinTable joinTable() default @JoinTable;
}