Contradiction in the javadoc of UserTransaction and @Transactional

[glassfishrobot]

There is a contradiction in the JTA spec:

1. On one hand, the UserTransaction javadoc [1] states that if the thread is already associated with a transaction and the Transaction Manager implementation does not support nested transactions, a NotSupportedException will be thrown.

2. On the other hand, the javadoc of the Transactional annotation [2] states that if an attempt is made to call any method of the UserTransaction interface from within the scope of a bean or method annotated with @transactional and a Transactional.TxType other than NOT_SUPPORTED or NEVER, an IllegalStateException must be thrown

So if I have a method annotated with @transactional(TxType.REQUIRED) and within it I call userTransaction.begin(), then what should be the expected exception - IllegalStateException or NotSupportedException ?

[1] http://docs.oracle.com/javaee/7/api/javax/transaction/UserTransaction.html#begin--

[2] http://docs.oracle.com/javaee/7/api/javax/transaction/Transactional.html

[glassfishrobot]

@glassfishrobot Commented
Reported by SvetlinZarev

[glassfishrobot]

@glassfishrobot Commented
Was assigned to paul_parkinson

[glassfishrobot]

@glassfishrobot Commented
ldemichiel said:
I believe the intent here is that it is always an error to try to access any method of the UserTransaction interface when a bean is marked as using container-managed transactional demarcation as specified by the Transactional annotation, and to treat this error uniformly. I don't see this as a contradiction with regard to the rule that UserTransaction.begin must not be invoked when a transaction is in progress, but rather that the rules around @transactional take precedence / are applied first.

[glassfishrobot]

@glassfishrobot Commented
svetlinzarev said:
It makes sense now. Just to confirm my understanding: It's meant that calling any method on UserTransaction from application code is forbidden when using CMT demarcation (regardless of whether nested transactions are supported), thus any such calls should result in IllegalStateException being thrown by the called method. Hence in the case described in the ticket description, userTransaction.begin() must throw IllegalStateException:

@Transactional(TxType.REQUIRED)
    public void testTxTypeRequired() {
        userTransaction.begin(); //Will throw IllegalStateException
        //do stuff
        userTransaction.commit();
    }

In that case it might be good idea to enhance the javadoc of UserTransaction, in order to make its contract unambiguous that its methods may throw IllegalStateException.

[glassfishrobot]

@glassfishrobot Commented
This issue was imported from java.net JIRA JTA_SPEC-14

[glassfishrobot]

• Issue Imported From: Contradiction in the javadoc of UserTransaction and @Transactional javaee/jta-spec#14
• Original Issue Raised By:@glassfishrobot
• Original Issue Assigned To: @glassfishrobot