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.Repeatable;
013import java.lang.annotation.Retention;
014import java.lang.annotation.Target;
015
016import static java.lang.annotation.ElementType.*;
017import static java.lang.annotation.RetentionPolicy.RUNTIME;
018
019/**
020 * Used to override the mapping of a <code>Basic</code> (whether
021 * explicit or default) property or field or <code>Id</code> property or
022 * field.
023 * <p>
024 * <p> May be applied to an entity that extends a mapped superclass or
025 * to an embedded field or property to override a basic mapping or id
026 * mapping defined by the mapped superclass or embeddable class (or
027 * embeddable class of one of its attributes).
028 * <p>
029 * <p> May be applied to an element collection containing instances of
030 * an embeddable class or to a map collection whose key and/or value
031 * is an embeddable class. When <code>AttributeOverride</code> is
032 * applied to a map, "<code>key.</code>" or "<code>value.</code>" must
033 * be used to prefix the name of the attribute that is being
034 * overridden in order to specify it as part of the map key or map
035 * value.
036 * <p>
037 * <p> To override mappings at multiple levels of embedding, a dot (".")
038 * notation form must be used in the <code>name</code> element to indicate an
039 * attribute within an embedded attribute.  The value of each identifier
040 * used with the dot notation is the name of the respective embedded
041 * field or property.
042 * <p>
043 * <p> If <code>AttributeOverride</code> is not specified, the column
044 * is mapped the same as in the original mapping.
045 * <p>
046 * <pre>
047 *    Example 1:
048 *
049 *    &#064;MappedSuperclass
050 *    public class Employee {
051 *        &#064;Id protected Integer id;
052 *        &#064;Version protected Integer version;
053 *        protected String address;
054 *        public Integer getId() { ... }
055 *        public void setId(Integer id) { ... }
056 *        public String getAddress() { ... }
057 *        public void setAddress(String address) { ... }
058 *    }
059 *
060 *    &#064;Entity
061 *    &#064;AttributeOverride(name="address", column=&#064;Column(name="ADDR"))
062 *    public class PartTimeEmployee extends Employee {
063 *        // address field mapping overridden to ADDR
064 *        protected Float wage();
065 *        public Float getHourlyWage() { ... }
066 *        public void setHourlyWage(Float wage) { ... }
067 *    }
068 *
069 *
070 *    Example 2:
071 *
072 *    &#064;Embeddable public class Address {
073 *        protected String street;
074 *        protected String city;
075 *        protected String state;
076 *        &#064;Embedded protected Zipcode zipcode;
077 *    }
078 *
079 *    &#064;Embeddable public class Zipcode {
080 *        protected String zip;
081 *        protected String plusFour;
082 *    }
083 *
084 *    &#064;Entity public class Customer {
085 *        &#064;Id protected Integer id;
086 *        protected String name;
087 *        &#064;AttributeOverrides({
088 *            &#064;AttributeOverride(name="state",
089 *                               column=&#064;Column(name="ADDR_STATE")),
090 *            &#064;AttributeOverride(name="zipcode.zip",
091 *                               column=&#064;Column(name="ADDR_ZIP"))
092 *        })
093 *        &#064;Embedded protected Address address;
094 *        ...
095 *    }
096 *
097 *
098 *    Example 3:
099 *
100 *    &#064;Entity public class PropertyRecord {
101 *        &#064;EmbeddedId PropertyOwner owner;
102 *        &#064;AttributeOverrides({
103 *            &#064;AttributeOverride(name="key.street",
104 *                               column=&#064;Column(name="STREET_NAME")),
105 *            &#064;AttributeOverride(name="value.size",
106 *                               column=&#064;Column(name="SQUARE_FEET")),
107 *            &#064;AttributeOverride(name="value.tax",
108 *                               column=&#064;Column(name="ASSESSMENT"))
109 *        })
110 *       &#064;ElementCollection
111 *       Map&#060;Address, PropertyInfo&#062; parcels;
112 *    }
113 *
114 *   &#064;Embeddable public class PropertyInfo {
115 *       Integer parcelNumber;
116 *       Integer size;
117 *       BigDecimal tax;
118 *   }
119 *
120 * </pre>
121 *
122 * @see Embedded
123 * @see Embeddable
124 * @see MappedSuperclass
125 * @see AssociationOverride
126 * @since Java Persistence 1.0
127 */
128@Target({TYPE, METHOD, FIELD})
129@Retention(RUNTIME)
130@Repeatable(AttributeOverrides.class)
131public @interface AttributeOverride {
132
133  /**
134   * (Required) The name of the property whose mapping is being
135   * overridden if property-based access is being used, or the
136   * name of the field if field-based access is used.
137   */
138  String name();
139
140  /**
141   * (Required) The column that is being mapped to the persistent
142   * attribute. The mapping type will remain the same as is
143   * defined in the embeddable class or mapped superclass.
144   */
145  Column column();
146}