3.3.2.20. Compatibility with Specification

The default behavior of certain OpenJPA API methods can evolve to align with the behaviors defined in JPA specification. To maintain backward compatibility, OpenJPA allows configuration options such that while the default behavior changes to align with current JPA specification, the previous behaviors can always be emulated.

For example, JPA 2.0 specification introduces a new API void EntityManager.detach(Object entity) that detaches the given entity from the current persistence context. OpenJPA has provided similar feature via <T> T OpenJPAEntityManager.detach(T entity) prior to JPA 2.0. OpenJPA detach(), however, has different default behavior than what JPA 2.0 specification mandates. Firstly, OpenJPA creates a copy of the given entity as a detached instance and returns it, whereas JPA 2.0 behavior requires the same given entity instance be detached. Secondly, the given instance is removed from the persistence context for JPA 2.0, whereas OpenJPA detach() method, prior to JPA 2.0, does not remove the instance from the persistence context as a copy is returned. Thirdly, OpenJPA will flush before detaching a dirty instance so that the detached instance can later be merged, whereas JPA 2.0 detach() semantics does not require a dirty instance be flushed before detach.

A user application running with OpenJPA that is compliant to a specific version of JPA specification can emulate the older behavior by configuring OpenJPA compatibility options. For example, openjpa.Compatibility=FlushBeforeDetach=false,CopyOnDetach=true will emulate the older behavior of detach even when running with OpenJPA that is compliant to JPA 2.0 specification. The configuration can also be set to a different version of the specification. For example, openjpa.Specification="JPA 1.0" configuration setting will emulate default OpenJPA behavior as it were for JPA specification version 1.0. Setting openjpa.Specification is a shorthand for more fine-grained control available via openjpa.Compatibility.