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.*; 016import static java.lang.annotation.RetentionPolicy.RUNTIME; 017 018/** 019 * Used to override a mapping for an entity relationship. 020 * <p> 021 * <p> May be applied to an entity that extends a mapped superclass to 022 * override a relationship mapping defined by the mapped 023 * superclass. If not specified, the association is mapped the same as 024 * in the original mapping. When used to override a mapping defined by 025 * a mapped superclass, <code>AssociationOverride</code> is applied to 026 * the entity class. 027 * <p> 028 * <p> May be used to override a relationship mapping from an 029 * embeddable within an entity to another entity when the embeddable 030 * is on the owning side of the relationship. When used to override a 031 * relationship mapping defined by an embeddable class (including an 032 * embeddable class embedded within another embeddable class), 033 * <code>AssociationOverride</code> is applied to the field or 034 * property containing the embeddable. 035 * <p> 036 * <p> When <code>AssociationOverride</code> is used to override a 037 * relationship mapping from an embeddable class, the 038 * <code>name</code> element specifies the referencing relationship 039 * field or property within the embeddable class. To override mappings 040 * at multiple levels of embedding, a dot (".") notation syntax must 041 * be used in the <code>name</code> element to indicate an attribute 042 * within an embedded attribute. The value of each identifier used 043 * with the dot notation is the name of the respective embedded field 044 * or property. 045 * <p> 046 * <p> When <code>AssociationOverride</code> is applied to override 047 * the mappings of an embeddable class used as a map value, 048 * "<code>value.</code>" must be used to prefix the name of the 049 * attribute within the embeddable class that is being overridden in 050 * order to specify it as part of the map value. 051 * <p> 052 * <p> If the relationship mapping is a foreign key mapping, the 053 * <code>joinColumns</code> element is used. If the relationship 054 * mapping uses a join table, the <code>joinTable</code> element must 055 * be specified to override the mapping of the join table and/or its 056 * join columns. 057 * <p> 058 * <p> 059 * <pre> 060 * Example 1: Overriding the mapping of a relationship defined by a mapped superclass 061 * 062 * @MappedSuperclass 063 * public class Employee { 064 * ... 065 * @ManyToOne 066 * protected Address address; 067 * ... 068 * } 069 * 070 * @Entity 071 * @AssociationOverride(name="address", 072 * joinColumns=@JoinColumn(name="ADDR_ID")) 073 * // address field mapping overridden to ADDR_ID foreign key 074 * public class PartTimeEmployee extends Employee { 075 * ... 076 * } 077 * </pre> 078 * <p> 079 * <pre> 080 * Example 2: Overriding the mapping for phoneNumbers defined in the ContactInfo class 081 * 082 * @Entity 083 * public class Employee { 084 * @Id int id; 085 * @AssociationOverride( 086 * name="phoneNumbers", 087 * joinTable=@JoinTable( 088 * name="EMPPHONES", 089 * joinColumns=@JoinColumn(name="EMP"), 090 * inverseJoinColumns=@JoinColumn(name="PHONE") 091 * ) 092 * ) 093 * @Embedded ContactInfo contactInfo; 094 * ... 095 * } 096 * 097 * @Embeddable 098 * public class ContactInfo { 099 * @ManyToOne Address address; // Unidirectional 100 * @ManyToMany(targetEntity=PhoneNumber.class) List phoneNumbers; 101 * } 102 * 103 * @Entity 104 * public class PhoneNumber { 105 * @Id int number; 106 * @ManyToMany(mappedBy="contactInfo.phoneNumbers") 107 * Collection<Employee> employees; 108 * } 109 * </pre> 110 * 111 * @see Embedded 112 * @see Embeddable 113 * @see MappedSuperclass 114 * @see AttributeOverride 115 * @since Java Persistence 1.0 116 */ 117@Target({TYPE, METHOD, FIELD}) 118@Retention(RUNTIME) 119 120public @interface AssociationOverride { 121 122 /** 123 * (Required) The name of the relationship property whose mapping is 124 * being overridden if property-based access is being used, 125 * or the name of the relationship field if field-based access is used. 126 */ 127 String name(); 128 129 /** 130 * The join column(s) being mapped to the persistent attribute(s). 131 * The <code>joinColumns</code> elements must be specified if a 132 * foreign key mapping is used in the overriding of the mapping of 133 * the relationship. The <code>joinColumns</code> element must 134 * not be specified if a join table is used in the overriding of 135 * the mapping of the relationship. 136 */ 137 JoinColumn[] joinColumns() default {}; 138 139 /** 140 * The join table that maps the relationship. 141 * The <code>joinTable</code> element must be specified if a join table 142 * is used in the overriding of the mapping of the 143 * relationship. The <code>joinTable</code> element must not be specified 144 * if a foreign key mapping is used in the overriding of 145 * the relationship. 146 * 147 * @since Java Persistence 2.0 148 */ 149 JoinTable joinTable() default @JoinTable; 150 151 /** 152 * (Optional) Used to specify or control the generation of a foreign key constraint for the columns 153 * corresponding to the joinColumns element when table generation is in effect. 154 * 155 * @since Java Persistence 2.1 156 */ 157 ForeignKey foreignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT); 158}