拨云剑之 javax.persistence.Convert

http://www.boyunjian.com/javasrc/org.eclipse.persistence/javax.persistence/2.1.0/_/javax/persistence/Convert.java

/*******************************************************************************
 * Copyright (c) 2011 - 2013 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:
 *     Linda DeMichiel - Java Persistence 2.1
 *
 ******************************************************************************/
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;
 
/**
 *  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(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(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(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(name="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
 */
@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;
}