Module jakarta.persistence
Package jakarta.persistence

Annotation Interface Convert

@Repeatable(Converts.class) @Target({METHOD,FIELD,TYPE}) @Retention(RUNTIME) public @interface 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, 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, 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<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 of 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 { ... }
Since:
2.1
See Also:

  • Element Details

    • converter

      Class<? extends AttributeConverter> converter
      Specifies the converter to be applied. This element must be explicitly specified if multiple converters would otherwise apply.
      Default:
      jakarta.persistence.AttributeConverter.class

    • attributeName

      String attributeName
      A name or period-separated path identifying the converted attribute relative to the annotated program element.

      For example:

      • if an entity class is annotated @Convert(attributeName = "startDate"), then the converter is applied to the field or property named startDate of the annotated entity class,
      • if an embedded field is annotated @Convert(attributeName = "startDate"), then the converter is applied to the field or property named startDate of the referenced embeddable class, or
      • if an map collection whose key type is an embeddable type is annotated @Convert(attributeName="key.jobType"), the converter is applied to the field or property named jobType of the map key class.

      When Convert directly annotates the converted attribute, this member must not be specified. (In this case the path relative to the annotated element is simply the empty path.)

      Default:
      ""

    • disableConversion

      boolean disableConversion
      Disables an auto-apply or inherited converter. If disableConversion = true, the converter() element should not be specified.
      Default:
      false