Java tutorial
/******************************************************************************* * Copyright (c) 2011 - 2015 Oracle Corporation. 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: * Petros Splinakis - Java Persistence 2.2 * Linda DeMichiel - Java Persistence 2.1 * ******************************************************************************/ package javax.persistence; import java.lang.annotation.Repeatable; 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; /** * Specifies the conversion of a Basic field or property. It is * not necessary to use the <code>Basic</code> annotation or corresponding * XML element to specify the Basic type. * * <p>The <code>Convert</code> annotation should not be used to specify * conversion of the following: Id attributes, version attributes, * relationship attributes, and attributes explicitly denoted as * Enumerated or Temporal. Applications that specify such conversions * will not be portable. * * <p>The <code>Convert</code> annotation may be applied to a basic * attribute or to an element collection of basic type (in which case * the converter is applied to the elements of the collection). In * these cases, the <code>attributeName</code> element must not be * specified. * * <p>The <code>Convert</code> annotation may be applied to an embedded * attribute or to a map collection attribute whose key or value is of * embeddable type (in which case the converter is applied to the * specified attribute of the embeddable instances contained in the * collection). In these cases, the <code>attributeName</code> * element must be specified. * * <p>To override conversion mappings at multiple levels of embedding, * a dot (".") notation form must be used in the <code>attributeName</code> * 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. * * <p>When the <code>Convert</code> annotation is applied to a map containing * instances of embeddable classes, the <code>attributeName</code> element * must be specified, and <code>"key."</code> or <code>"value."</code> * must be used to prefix the name of the attribute that is to be converted * in order to specify it as part of the map key or map value. * * <p>When the <code>Convert</code> annotation is applied to a map to specify * conversion of a map key of basic type, <code>"key"</code> must be used * as the value of the <code>attributeName</code> element to specify that * it is the map key that is to be converted. * * <p>The <code>Convert</code> annotation may be applied to an entity class * that extends a mapped superclass to specify or override a conversion * mapping for an inherited basic or embedded attribute. * * <pre> * Example 1: Convert a basic attribute * * @Converter * public class BooleanToIntegerConverter * implements AttributeConverter<Boolean, Integer> { ... } * * @Entity * public class Employee { * @Id long id; * * @Convert(converter=BooleanToIntegerConverter.class) * boolean fullTime; * ... * } * * * Example 2: Auto-apply conversion of a basic attribute * * @Converter(autoApply=true) * public class EmployeeDateConverter * implements AttributeConverter<com.acme.EmployeeDate, java.sql.Date> { ... } * * @Entity * public class Employee { * @Id long id; * ... * // EmployeeDateConverter is applied automatically * EmployeeDate startDate; * } * * * Example 3: Disable conversion in the presence of an autoapply converter * * @Convert(disableConversion=true) * EmployeeDate lastReview; * * * Example 4: Apply a converter to an element collection of basic type * * @ElementCollection * // applies to each element in the collection * @Convert(converter=NameConverter.class) * List<String> names; * * * Example 5: Apply a converter to an element collection that is a map or basic values. * The converter is applied to the map value. * * @ElementCollection * @Convert(converter=EmployeeNameConverter.class) * Map<String, String> responsibilities; * * * Example 6: Apply a converter to a map key of basic type * * @OneToMany * @Convert(converter=ResponsibilityCodeConverter.class, * attributeName="key") * Map<String, Employee> responsibilities; * * * Example 7: Apply a converter to an embeddable attribute * * @Embedded * @Convert(converter=CountryConverter.class, * attributeName="country") * Address address; * * * Example 8: Apply a converter to a nested embeddable attribute * * @Embedded * @Convert(converter=CityConverter.class, * attributeName="region.city") * Address address; * * * Example 9: Apply a converter to a nested attribute of an embeddable that is a map key * of an element collection * * @Entity public class PropertyRecord { * ... * @Convert(attributeName="key.region.city", * converter=CityConverter.class) * @ElementCollection * Map<Address, PropertyInfo> parcels; * } * * * Example 10: Apply a converter to an embeddable that is a map key for a relationship * * @OneToMany * @Convert(attributeName="key.jobType", * converter=ResponsibilityTypeConverter.class) * Map<Responsibility, Employee> responsibilities; * * * Example 11: Override conversion mappings for attributes inherited from a mapped superclass * * @Entity * @Converts({ * @Convert(attributeName="startDate", * converter=DateConverter.class), * @Convert(attributeName="endDate", * converter=DateConverter.class)}) * public class FullTimeEmployee extends GenericEmployee { ... } * </pre> * * @see Converter * @see Converts * @see Basic * * @since Java Persistence 2.1 */ @Repeatable(Converts.class) @Target({ METHOD, FIELD, TYPE }) @Retention(RUNTIME) public @interface Convert { /** * Specifies the converter to be applied. A value for this * element must be specified if multiple converters would * otherwise apply. */ Class converter() default void.class; /** * The <code>attributeName</code> element must be specified unless the * <code>Convert</code> annotation is on an attribute of basic type * or on an element collection of basic type. In these cases, the * <code>attributeName</code> element must not be specified. */ String attributeName() default ""; /** * Used to disable an auto-apply or inherited converter. * If disableConversion is true, the <code>converter</code> element should * not be specified. */ boolean disableConversion() default false; }