A converter translates an entity attribute between a Java domain type and one database-column representation. It is useful when the domain model needs a richer type than the current schema can store directly. JPA defines AttributeConverter as a standard extension point for this mapping. section 6.3.2 section 6.0
Store a monetary amount in one column
An Item can declare a MonetaryAmount buyNowPrice while its PRICE column remains VARCHAR. The column stores a value such as “11.23 USD”. Annotate the property with @Convert(converter = MonetaryAmountConverter.class). The converter implements AttributeConverter<MonetaryAmount, String>: convertToDatabaseColumn produces the string for storage, and convertToEntityAttribute reconstructs the domain value when it is loaded. section 6.3.2
Listing 6.16 Converting between strings and MonetaryValue
Path: Ch06/mapping-value-types2/src/main/java/com/manning/javapersistence /ch06/converter/MonetaryAmountConverter.java @Converter #1 public class MonetaryAmountConverter #1 implements AttributeConverter<MonetaryAmount, String> { #1 @Override #2 public String convertToDatabaseColumn(MonetaryAmount monetaryAmount) { #2 return monetaryAmount.toString(); #2 } #2 @Override #3 public MonetaryAmount convertToEntityAttribute(String s) { #3 return MonetaryAmount.fromString(s); #3 } #3 } #1 A converter has to implement the <kbd>AttributeConverter</kbd> interface; the two arguments are the type of the Java property and the type in the database schema. The Java type is <kbd>MonetaryAmount</kbd>, and the database type is <kbd>String</kbd>, which maps, as usual, to an SQL <kbd>VARCHAR</kbd>. We must annotate the class with <kbd>@Converter</kbd>. #2 The <kbd>convertToDatabaseColumn</kbd> method will convert from the <kbd>MonetaryAmount</kbd> entity type to the string database column. #3 The <kbd>convertToEntityAttribute</kbd> method will convert from the string database column to the <kbd>MonetaryAmount</kbd> entity type.
The converter listing shows the JPA interface and the two conversion methods used at the database boundary. section 6.3.2
The converter is a buffer, not a substitute for a schema change. If the schema later provides separate amount and currency columns, MonetaryAmount can instead become an @Embeddable mapped to both columns. Conversion can be enabled or disabled selectively while tables are migrated. section 6.3.2
Reconstruct a more specific value type
A ZipcodeConverter maps a Zipcode to its string value and uses the stored string’s length to create a GermanZipcode or SwissZipcode on loading. An @Convert declaration can target the nested city.zipcode attribute of an embedded address. section 6.3.2
Prefer a standard JPA converter for this property-level transformation. A native Hibernate UserType is a separate, lower-level adapter option. Converters can also address legacy temporal mappings—for example, returning a plain java.util.Date or setting a non-default Calendar time zone after loading. section 6.4 section 6.3.1
