| Re: [jakarta.ee-spec] Specification text |
It's reasonable to make the javadocs better, but you can't do that by violating the copyright/license for the specification document. Presumably whatever improvements are made will need to be approved by the to-be-defined specification process. The JCP would handle improvements that didn't change the requirements (which seems to be what you're asking about here) by using an "errata MR". We'll have to see how the new specification process wants to handle such changes.
Tom Jenkinson wrote on 05/ 3/18 06:29 AM:
Thanks for the response!
Regarding your comment that the idea might be to align the javadocs with the specification first, would that be an activity that the Jakarta community would do? If so, will it be OK to use the existing JTA specification text when adding these missing conditions to the Javadoc? On the other hand, perhaps the TCK already verifies some of these behaviours and so the Javadoc can draw from the conditions tested in the TCK instead?
Thinking specifically about the issue I mentioned regarding threading support for XAResources I wonder if the fact the XAResource interface is provided by the java.sql module (rather than JTA) might pose some difficulty as we won't be in control of adding requirements that are appropriate to add to the XAResource interface itself. In principle the requirement might be able to be associated with the enlistResource(XAResource) method of the XAResource interface itself but might that lead to confusion where an XAResource implementer just uses the XAResource interface to produce their implementation and are not aware of the requirements that we add to the javax.transaction.Transaction enlistResource javadoc?
I take on board that answers to these questions are not available yet and will be part of the remit of the specification committee so I provide them to help with the discussions.
On 2 May 2018 at 15:56, Richard Monson-Haefel <rmonson@xxxxxxxxxxxxx> wrote:
--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
_______________________________________________
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
_______________________________________________ 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