jakarta.persistence.Convert

Specifies how the values of a field or property are converted to a basic type, enabling a converter defined autoApply=false, overriding the use of a converter defined autoApply=true, or overriding the use of a converter specified by a field or property of an embedded type or inherited mapped superclass.

It is not necessary to use the Basic annotation (or corresponding XML element) to specify the converted basic type. Nor is it usually necessary to explicitly specify the converter class, except to disambiguate cases where multiple converters would otherwise apply.

The Convert annotation should not be used to specify conversion of id attributes, of version attributes, of relationship attributes, or of attributes explicitly declared as Enumerated or Temporal. Applications that depend on such conversions are not portable.

The Convert annotation may be applied to:

• a basic attribute, or
• a collection attribute of any type other than Map<K,V>, in which case the converter is applied to the elements of the collection.

In these cases, the attributeName must not be specified.

Alternatively, the Convert annotation may be applied to:

• an embedded attribute,
• a collection attribute whose element type is an embeddable type, in which case the converter is applied to the specified attribute of the embeddable instances contained in the collection
• a map collection attribute, that is, a collection attribute of type Map<K,V>, in which case the converter is applied to the keys or values of the map, or to the specified attribute of the embeddable instances contained in the map, or
• an entity class which extends a mapped superclass, to enable or override conversion of an inherited basic or embedded attribute.

In these cases, the attributeName 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.

The dot notation may also be used with map entries:

• When this annotation is applied to a map to specify conversion of a map key or value, "key" or "value", respectively, must be used as the value of the attributeName element to specify that it is the map key or map value that is converted.
• When this annotation is applied to a map whose key or value type is an embeddable type, the attributeName element must be specified, and "key." or "value." (respectively) must be used to prefix the name of the attribute of the key or value type that is converted.

Example 1: Convert a basic attribute

 @Converter
 public class BooleanToIntegerConverter
         implements AttributeConverter {  ... }

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

 @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 names;

Example 5: Apply a converter to an element collection that is a map of basic values. The converter is applied to the map value.

 @ElementCollection
 @Convert(converter = EmployeeNameConverter.class)
 Map responsibilities;

Example 6: Apply a converter to a map key of basic type

 @OneToMany
 @Convert(converter = ResponsibilityCodeConverter.class,
          attributeName = "key")
 Map 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 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 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 { ... }

See Also:

Converter

Converts

Basic

Since:

Jakarta Persistence (JPA) 2.1