jakartaee/connectors

Some observed issues in 2.0 Specification Text

Opened this issue · 0 comments

edbratt commented

A list of apparent formatting and other errors in Connector Spec

  • Copyright dates should be consistent across TCK, JavaDocs, and Spec. Docs. I believe they should be 2018, 2019 for all three.
  • JavaDocs could benefit with a "Send comments to jca-dev@eclipse.org" or something like that in the page footer.
  • Following refer to the Spec. doc. (Reviewed the .html copy)
    • Many internal links don't work. Dare I say most? Due to this, I couldn't tell if they were intended to be external references or not.
    • Some refs. appear to be footnotes, but there is no aggregation of these (at least not in the .html render)
    • Diagram in 8.6.4 -- Consecutive question mark text in left-most item should be: "Transaction.enlistResource(XAResource)". Text in bottom (final) should be: "XAResource.start(XID, flag)" (Quote from last Java EE version of Spec.)
    • Diagram in 8.6.5 Text with question marks should be (left most) "Transaction.delistResource(XAResource, flag)" text in right most should be, "XAResource.end(XId, flag)". (same source as previous).
    • 8.6.5, diagram fidelity loss. The text in the top far-right box originally used text position to distinguish the final three lanes (in lane-order, left to right: ManagedConnection Factory; Managed Connection; XAResource. This detail is lost in the new diagram.
    • Diagram in 8.10.3 "Connection Sharing Across Component Instances" string of question marks (just below LocalTransaction.begin) should be: "EJB A gets a connection handle and performs a unit of work on the EIS resource manager"
    • 11.4.4.1 DistributableWork interface -- Text formatting problems in paragraph immediately following the code block.
    • 14.9.2.1 XML format document format could be improved
    • 17.4.1 Text formatting in 2nd paragraph
    • 18.9, malformed control/text directive (appears to be missing a second closing square bracket).
    • 18.12.x has occasional free-floating punctuation. This results in a couple of strange looking lines of text.
    • 19.4 toward the end is a misformatted paragraph.

More general observations

  • References to legacy Spec. versions might be improved if they can use Jakarta EE references. Some legacy EJB references could be Jakarta Enterprise Bean Spec. references or could be EJB / Java EE references. Since the links didn't work, I couldn't easily sort it out. We would like to avoid references that are ambiguous, wherever possible even though the conversion and subsequent name changes are not helping us keep clarity.
  • Need to decide what to do with the references in section 2.5 to SCA and JBI. Are these even useful any more?
  • Was surprised to see the text in section 2.7 (document conventions) so far down into the text. I'd have expected this to be before any of the Specification Proper text had started.
  • May need to rework section 8.4 -- relationship to JAkarta Transaction, JTA (CORBA 1.1 definition?)
  • Section 22 Runtime Environment will need to be updated when we update to JDK 11
  • Would be nice if we could figure out how to relabel the appendices as appendices (comparing against the final Java EE JCA Spec.)
  • I think the "external references" section could be valuable. Consider reinstating that section.