This content being developed here with with the intent to be added to the docs
When migrating from the native TopLink API to JPA one of the major differences in behaviour is how relationships between entities are managed within transactions. The native TopLink approach within the UnitOfWork is 'persistence-by-reachability' while JPA leverages explicit CascadeType setting on the mappings to determine how they are managed/used for DETACH, MERGE, PERSIST, REFRESH, and REMOVE. When migrating an application that was written using TopLink's original native API care must be taken to configure cascading or alter your application's transaction logic to ensure the same functionality is maintained.
The following are some key scenarios.
New Entity Discovery
With JPA entities should never be discovered. They must be explicitly registered with an entity manager (persist) or they must be included as a dependent child within a relationship with cascade PERSIST enabled. If a new entity instance is found within a relationship and it has not been persisted or merged into the EntityManager an exception will be thrown during commit or flush.
Persist vs Merge
TODO: Discuss the use of the 2 methods and when they should be used for both new entities, existing detached entities, and managed entities.