javax.persistence

## Annotation Type Convert

-     @Target(value={METHOD,FIELD,TYPE})
      @Retention(value=RUNTIME)
      public @interface Convert

  Specifies the conversion of a Basic field or property. It is not necessary to use the `Basic` annotation or corresponding XML element to specify the Basic type.

  The `Convert` 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.

  The `Convert` 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 `attributeName` element must not be specified.

  The `Convert` 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 `attributeName` element must be specified.

  To override conversion mappings at multiple levels of embedding, a dot (".") notation form must be used in the `attributeName` 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 the `Convert` annotation is applied to a map containing instances of embeddable classes, the `attributeName` element must be specified, and `"key."` or `"value."` 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.

  When the `Convert` annotation is applied to a map to specify conversion of a map key of basic type, `"key"` must be used as the value of the `attributeName` element to specify that it is the map key that is to be converted.

  The `Convert` 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.

           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 { ... }

  Since:
    Java Persistence 2.1
  See Also:
    `Converter`, `Converts`, `Basic`

- - ### Optional Element Summary

    Optional Elements
    Modifier and Type | Optional Element and Description
    --- | ---
    `String` | `attributeName` The `attributeName` element must be specified unless the `Convert` annotation is on an attribute of basic type or on an element collection of basic type.
    `Class` | `converter` Specifies the converter to be applied.
    `boolean` | `disableConversion` Used to disable an auto-apply or inherited converter.

- - ### Element Detail

    - #### converter

          public abstract Class converter

      Specifies the converter to be applied. A value for this element must be specified if multiple converters would otherwise apply.
      Default:
        void.class

    - #### attributeName

          public abstract String attributeName

      The `attributeName` element must be specified unless the `Convert` annotation is on an attribute of basic type or on an element collection of basic type. In these cases, the `attributeName` element must not be specified.
      Default:
        ""

    - #### disableConversion

          public abstract boolean disableConversion

      Used to disable an auto-apply or inherited converter. If disableConversion is true, the `converter` element should not be specified.
      Default:
        false

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.