[#118] Jakarta-ize Enterprise Web Services Specification Document Chapters 1-4

[andymc12]

In general, this PR should:

• Java EE -> Jakarta EE
• Removing references to JAX-RPC
• Enterprise JavaBeans -> Jakarta Enterprise Beans
• Version updates where applicable

This PR is still in progress. Feedback welcome at any point (so far, only 3 chapters done).

Completes chapters 1-4 of #118.

[andymc12]

@lukasj I just pushed the changes to Chapter 4. @sawadood (Syed) from my team will be helping out by contributing some of the other chapters. His changes may need to come in a separate PR. Thanks for the review so far!

[lukasj]

section 1:

• doc conventions - I'd make "The italic Times..." in italic and let "The Courier font..." really use the Courier font

section 2:

• wrong nesting (see separate note)
• part 2.5 (Web Services Registry Goals) should be completely removed since JAXR is being dropped

[lukasj]

Section 3:

• 3.8.1 - wrong nesting of particular standards (SOAP, WSDL, UDDI)
• 3.10 - broken links to other parts of the document - the one at the beginning going to chapter 5 and the one at the end going to section 5.4
• rest has its own note

[lukasj]

Section 4:

• 4.2.2 - pointers to '7.2' and '7.2.5' should be links
• 4.2.4.1 - pointer to 4.2.5 goes to 4.2.5.1 instead
• 4.2.5.1 - "...Port Stub, Dynamic Proxy, or Call will..." - Call is JAX-RPC specific and should be removed
• 4.2.8.2 - JTA -> Jakarta Transactions
• 4.2.9 - remove? JAX-RPC may be covered by "other client/runtimes", or no?
• 4.2.13 - remove spec version number from "Jakarta XML Web Services 2.2"

in general also (on multiple places):

• JAXB -> Jakarta XML Binding
• javax.xml.ws -> jakarta.xml.ws (wrong almost only in sections 4.2.7-4.2.8)
• tables are missing headers and ids/numbers (sections 4.2.10, 4.2.12, 4.2.13 and few others noted inline)

[lukasj]

To sum this up:

• in general great job ! Thanks
• what I believe needs to be fixed are acronyms (JAXB, JTA), package names (javax->jakarta), complete JAXR/JAXRPC removal
• I do not care much about purely formatting issues ie monospace font not being used for code, wrong nesting, trivial things like missing dot somewhere or missing table headers (even though this one would be good to fix), basically all the rest is more or less nice to have/easy to do

Also I'm still thinking about section 3.6.1. ie "Beginning in Java SE 11, the JAX-WS APIs are no longer available as part of the Java SE class library." does not make much sense since "jakarta" APIs has never been part of Java SE, it is also not mentioned anywhere in this spec that this APIs was ever part of SE (except of section 8.1.1). So perhaps:

Instead of:
"Jakarta XML Web Services 3.0 renames the JAX-WS API packages from javax. to jakarta.. Beginning in Java SE 11, the JAX-WS APIs are no longer available as part of the Java SE class library."

use sth like:
"Jakarta XML Web Services 3.0 is a next version of JAX-WS 2.2 Specification. It moves existing APIs from javax.xml.ws packages to jakarta.xml.ws packages."

[andymc12]

Whew! That's a lot of changes! :-) But I think I got them all. Please take another (hopefully final) look to make sure I got everything. There was a "Refer to ... section 7.2.5" sentence in chapter 4, but no anchor in chapter 7 - so I had to add one. That might add a merge conflict with @sawadood's PR #120... Thanks!

[lukasj]

Second round:

• section 1 - DONE
• section 2 - DONE
• section 3:
  ** 3.8.1 - still wrong nesting of particular standards (SOAP, WSDL, UDDI)
• section 4:
  ** few minor things noted inline

[andymc12]

Next round of review changes are in. Thanks again for the review @lukasj

[lukasj]

LGTM, thanks!