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

Example 2: Auto-apply conversion of a basic attribute

Example 3: Disable conversion in the presence of an autoapply converter

Example 4: Apply a converter to an element collection of basic type

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

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

Example 7: Apply a converter to an embeddable attribute

Example 8: Apply a converter to a nested embeddable attribute

Example 9: Apply a converter to a nested attribute of an embeddable that is a map key of an element collection

Example 10: Apply a converter to an embeddable that is a map key for a relationship

Example 11: Override conversion mappings for attributes inherited from a mapped superclass

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