Re: [jakarta.ee-spec] Specification text

[Richard Monson-Haefel <rmonson@xxxxxxxxxxxxx>]

Hi Tom,

This is an excellent question. I’m an alternate of the Jakarta EE Specification Committee.  The committee will be meeting for the first time later this week to begin setting up norms and rules for defining specifications.  My gut tells me to align the Java doc with the specification, but let me bring this up to the committee when it meets so that I can provide you with an official response.  Once the Specification Committee has defined processes, guidelines, and rules for creating and updating specifications these kinds of issues will be addressed.

More questions of this type are very helpful to the specification committee so keep them coming!

Richard

On Wed, May 2, 2018 at 8:19 AM Tom Jenkinson <tom.jenkinson@xxxxxxxxxx> wrote:

Hello,

I am the project lead for the EE4J JTA project. I am looking to start work on producing specification text for the project using the public Javadocs we have in our GitHub repo as the basis: https://github.com/eclipse-ee4j/jta-api 

I have a question of what we should do in cases where the Javadoc is not a full transpose of the meaning in the specification?

Some examples:

* The github project shows only a few instances for the word "must", the specification text  shows more examples of these requirements though. For example, in 3.1.2 it is stated that UserTransaction objects must be Referenceable and Serializable. The requirement does not appear in the Javadoc.

* Handling unchecked exceptions in beforeCompletion. Unchecked exceptions thrown by Synchronization objects should (since JTA 1.1) result in marking the transaction for rollback. The Javadoc does not describe that.

* The JTA specification has in  at least one case deviated from XA. Defined in 3.4.3 an XAResource is required to allow any thread to perform transaction association calls xa_start and xa_end calls for a specific branch, in XA that is not the case.

What is the recommended way to deal with these type of issues?

Thanks,

Tom

_______________________________________________
jakarta.ee-spec mailing list
jakarta.ee-spec@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/jakarta.ee-spec

--

Richard Monson-Haefel
http://twitter.com/rmonson
http://www.tomitribe.com
http://www.tomitribe.io