public @Interface Convert

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 java.util.Map, in which case the converter is applied to the elements of the collection.

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 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 mapped superclass, to enable or override conversion of an inherited basic or embedded attribute.

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