AttributeConverter handling
Support for jakarta.persistence.AttributeConverter was reworked. @Converter(autoApply=true) classes found on the classpath are now registered and applied to every basic attribute whose declared type matches (excluding identifiers, version fields, relations, collections and maps) unless the attribute declares its own @Convert; previously autoApply was ignored.
Class-level @Convert(attributeName=…)/@Converts, converters on embedded attributes, on mapped superclass attributes and on element collection elements are honored (previously ignored or rejected). The database column type is now derived from the converter’s database type Y instead of the attribute type X (a Boolean to Integer converter now yields an INTEGER column).
A converter whose attribute type is the collection or map itself, for example AttributeConverter<List<Item>, String> on a List<Item> attribute, converts the attribute as a whole.
Such an attribute is now mapped as a basic attribute to one column and is fetched eagerly unless it is declared LAZY.
In 4.1.x it was left out of the mapping with only a warning, and its contents were not stored.
Expect a new column for each such attribute.
One converter instance per attribute is created lazily through the no-argument constructor and shared between threads, so converters must be stateless. RuntimeExceptions thrown by a converter surface as jakarta.persistence.PersistenceException instead of MetaDataException. @Convert(disableConversion=true) only cancels an explicit converter on that attribute; it does not prevent an autoApply converter from being applied.
A change made in place to an element of a collection or map that is converted as a whole is now written at flush.
To find it, the converted value of such an attribute is saved when it is loaded and compared before each flush, which calls convertToDatabaseColumn once per load and once per flush for every such instance in the persistence context.
Clear the persistence context in long batch runs that flush repeatedly.
The value of a converted attribute whose type is not a basic, temporal, collection or map type is now the object returned by convertToEntityAttribute.
In 4.1.x it was replaced by a generated subclass that copied the value through its getter and setter pairs, losing any state without a setter.
A change made in place to such a value is found by the same check at flush as above.
Where OpenJPA needs a copy of the value, for detachCopy, for merge, for restoring state on rollback and for the data cache, the copy is made by converting the value to its column value and back.
The data cache holds the column value of such an attribute.
Since such a value has no proxy, a change made to it in place, like a change to an element of a collection or map converted as a whole, does not mark the attribute dirty when it is made.
The attribute is reported as dirty, for example by OpenJPAStateManager.getDirty, only once the change was found by a flush, by a query that checks for changes before it runs, or when a savepoint is set.
On rollback, a value changed in place is restored from the converted value saved when it was loaded, also when no flush found the change.
A converter is now also consulted for null in both directions, as required by Jakarta Persistence 3.2; in 4.1.x a null attribute or null column value bypassed the converter.
Converter implementations must therefore be null-safe.
A converter written without null checks throws on the first null it sees, which surfaces as a jakarta.persistence.PersistenceException.
This also changes the stored data where a converter maps null to a column default: a null attribute is written as convertToDatabaseColumn(null) and a null column value is read as convertToEntityAttribute(null).
Converters on attributes of an embeddable are no exception; note that an embeddable without a mapped null-indicator column is materialized from its all-null columns, so its converted attributes are loaded from a null column value.
Queries are unaffected: a null in a query always means SQL NULL and is never passed through the converter, so x IS NULL, x = :nullParameter, SET x = NULL and SET x = :nullParameter keep the same meaning as in 4.1.x.
A converter that maps null to a column default can therefore not be queried for its null attributes by IS NULL; compare against the substitute value instead.
For a @Lob (or <lob/>) attribute with a converter, the kind of LOB now follows the converter’s database type: a converter to String yields a CLOB (TEXT on PostgreSQL and MySQL) and a converter to byte[] a BLOB (BYTEA on PostgreSQL). In 4.1.x the attribute type decided, so a converter to String on any attribute type other than String produced a BLOB, and a converter to byte[] on a String attribute a CLOB.
Tables created by 4.1.x for such attributes no longer match the mapping; alter the column type, or pin it with @Column(columnDefinition=…).
With the data cache enabled, a converted attribute is now kept in the cache in its database form.
The converter’s convertToDatabaseColumn runs when an instance is put into the cache, and convertToEntityAttribute runs each time an instance is loaded from the cache, so every persistence context gets its own attribute value.
This applies to attributes converted as a whole and to collections whose elements are converted.
In 4.1.x the cache held the attribute value itself and handed the same objects to every persistence context without calling the converter, so a change made in place in one context showed up in the others.
A converter that is costly or has side effects now runs on cache hits as well.
A converter that throws while the cache is filled leaves that attribute out of the cache, and it is then loaded from the database; one that throws on a cache hit fails the load with a jakarta.persistence.PersistenceException, as a load from the database would.
Audit existing @Converter(autoApply=true) classes: attributes of the matching type that were stored unconverted by 4.1.x are now written and read through the converter and their generated column type changes.
Remove autoApply, declare an explicit converter, or pin the column type with @Column(columnDefinition=…) where the old behavior is required.