Minor Description
Currently, when setRollbackOnly is invoked on a Broker or EntityManager, there is no way to specify the cause or reason for the invocation. Given that we invoke setRollbackOnly() whenever most PersistenceExceptions are thrown (in org.apache.openjpa.persistence.PersistenceExceptions as per section 3.7 of the JPA spec), transactions are frequently marked as RollbackOnly when problems occur. If one part of an application swallows or otherwise handles the exception, and another part of the application tries to subsequently commit the transaction, it has no way of having any idea what caused the problem. And even though the RollbackOnly flag can't be reset, it can be useful for reporting purposes, or for application logic outside of the transaction to know whether to re-try the entire operation.
Furthermore, this behavior can cause problems with managed JTA transactions, since if an exception occurs during the flush or commit process (e.g., if a duplicate primary key is persisted), the rollback only flag gets set on the JTA transaction. Some TransactionManagers will check this flag at various points in the commit process and eagerly fail when they see the RollbackOnly flag, leaving the developer of the managed application with no way of knowing what caused the transaction to fail.
I propose to add a new setRollbackOnly(Throwable cause) method to Broker and EntityManager, where we can internally track the cause of the invocation. If nothing else, then the application programmer can at least access it with a getRollbackReason() method and act accordingly. Also, some TransactionManager implementations (such as BEA's, which exhibits the behavior I described earlier) have their own extensions for tracking the rollback reason, and we might be able to integrate with them by sharing this knowledge.