-
@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 definedautoApply=false
, overriding the use of a converter definedautoApply=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 asEnumerated
orTemporal
. 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.
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.
attributeName()
must be specified.To override conversion mappings at multiple levels of embedding, a dot (
.
) notation form must be used in theattributeName()
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 theattributeName()
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 {@snippet :
-
-
Optional Element Summary
Optional Elements Modifier and Type Optional Element Description java.lang.String
attributeName
A name or period-separated path identifying the converted attribute relative to the annotated program element.java.lang.Class<? extends AttributeConverter>
converter
Specifies the converter to be applied.boolean
disableConversion
Disables an auto-apply or inherited converter.
-
-
-
Element Detail
-
converter
java.lang.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
java.lang.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 namedstartDate
of the annotated entity class, - if an embedded field is annotated
@Convert(attributeName = "startDate")
, then the converter is applied to the field or property namedstartDate
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 namedjobType
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:
- ""
- if an entity class is annotated
-
-
-
disableConversion
boolean disableConversion
Disables an auto-apply or inherited converter. IfdisableConversion = true
, theconverter()
element should not be specified.- Default:
- false
-
-