JPA Annotation

Convert

Target: METHOD, FIELD, TYPE

Implemented Interfaces:: Annotation

Specifies how the values of a field or property are converted to a plain, 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 plain 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 plain of any type other than java.util.Map, in which case the converter is applied to the elements of the collection.

In these cases, the Convert.attributeName must not be specified.

Alternatively, the Convert annotation may be applied to:

an plain,
a plain 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 java.util.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 plain, to enable or override conversion of an inherited basic or embedded attribute.

In these cases, the Convert.attributeName must be specified.

To override conversion mappings at multiple levels of embedding, a dot (.) notation form must be used in the Convert.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 Convert.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 Convert.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 :

See Also:: Converter; Converts; Basic

Since:: JPA 2.1

Public Annotation Attributes

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

For example:

if an plain is annotated @Convert(attributeName = "startDate"), then the converter is applied to the field or property named startDate of the annotated entity class,
if an plain is annotated @Convert(attributeName = "startDate"), then the converter is applied to the field or property named startDate of the referenced plain class, or
if an plain 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.)

Since:: JPA 2.1

Specifies the plain to be applied.

This element must be explicitly specified if multiple converters would otherwise apply.

Since:: JPA 2.1

Disables an plain or inherited converter.

If disableConversion = true, the Convert.converter element should not be specified.

Since:: JPA 2.1