Initial spec doc contribution for Jakarta EE #275

OndroMih · 2020-05-03T09:27:13Z

Initial modifications by @tivrfoa of the donated document for Jakarta EE. This is a follow-up for #267, which was closed before merged.

This pull request builds on #273. After #273, this PR will only contain changes made in the donated document to make it easier to review.

(This PR replaces #274 which wasn't synchronized with master and didn't show only diffs in the spec file)

Signed-off-by: Leandro Coutinho <lescoutinhovr@gmail.com>

….adoc Signed-off-by: Leandro Coutinho <lescoutinhovr@gmail.com>

Signed-off-by: Leandro Coutinho <lescoutinhovr@gmail.com>

hussainnm

References to JCA need to change to Jakarta Connectors instead of Jakarta EE Connector Architecture
References to EJB need to change to Enterprise Beans or enterprise beans (most references are to EJB containers)
References to JTA need to change to Jakarta transactions or just transactions

hussainnm · 2020-05-03T09:56:11Z

spec/src/main/asciidoc/messaging-spec.adoc


-For historical reasons JMS offers four alternative sets of interfaces
+For historical reasons Jakarta Messaging offers three alternative sets of interfaces


Why change to three - (1.0 = 2, 1.1 = 1, 2.0 = 1 = four)

I reverted this back to "four"

Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

OndroMih · 2020-05-07T15:40:08Z

@hussainnm, I'm going to fix the wrong references to JCA, EJB and JTA.

I'm not sure whether to change references to "EJB Container" because the spec in the master branch of Jakarta Enterprise Beans currently still defines it as "EJB Container". I also asked about it in the Enterprise Beans github issue here: jakartaee/enterprise-beans#99 (comment)

OndroMih · 2020-05-07T16:12:31Z

The Enterprise Beans PR https://github.com/eclipse-ee4j/ejb-api/pull/96/files#diff-adade127f19060d71cb75f896da4c40cR89 proposes to change "EJB Container" to "Enterprise Beans Container". I'll replace "EJB Container" to match that.

The scope section was redundant after we added the original JMS spec content. Enterprise Beans container is used instead of EJB container as currently proposed by the Enterprise Beans spec but the final name is not yet approved. Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

JTA transaction replaced with Jakarta transaction Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

OndroMih · 2020-05-07T18:08:54Z

@hussainnm, I've replaced all references to JCA, EJB and JTA:

Jakarta EE Connector Architecture -> Jakarta Connectors
EJB and Enterprise JavaBeans -> Jakarta Enterprise Beans
EJB Container -> Enterprise Beans container
JTA -> Jakarta Transactions
JTA transaction -> Jakarta Transaction

I also removed the scope section which became redundant. It caused that the section numbers were shifted and it was there only as a stub before the Java EE document was donated.

hussainnm · 2020-05-08T08:22:37Z

spec/src/main/asciidoc/messaging-spec.adoc

 commit and rollback methods in this context throws a Jakarta Messaging
 TransactionInProgressException.

 ==== Distributed transactions

 Jakarta Messaging does not require that a provider support distributed transactions;
 however, it does define that if a provider supplies this support it
-should be done via the JTA XAResource API.
+should be done via the Jakarta Transactions XAResource API.


XAResource API is still under JDK and not part of Jakarta Transactions.

Change yo Java XA Resource API as suggested.

hussainnm

Minor changes:
2 occurrences of javax.transaction.UserTransaction
1 occurrence of javax.inject.Inject
XAResource API is still under JDK, this could be changed to Java XAResource API instead of Jakarta Transactions XAResource API

spec/src/main/asciidoc/messaging-spec.adoc

Co-authored-by: hussainnm <mailathussain@yahoo.com>

Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

hussainnm

Please bear with me, I am reviewing it randomly and not going through it line by line. Here are two more issues i found
2 occurrences of Java™ Platform, Enterprise Edition needs to be changed to Jakarta EE Platform.
9 occurrences of missing sections, search for empty quotes.

hussainnm · 2020-05-08T12:15:56Z

spec/src/main/asciidoc/messaging-spec.adoc

 client. Some providers may supply such a triggering mechanism via their
 administrative facilities.

 === Request/reply

-JMS provides the JMSReplyTo message header field for specifying the
+Jakarta Messaging provides the JMSReplyTo message header field for specifying the
 Destination where a reply to a message should be sent. The
 JMSCorrelationID header field of the reply can be used to reference the
 original request. See Section “” for more information.


There are total 9 missing references like this. You can search for empty quotes in the document.

There were more, I found 16 missing references. I copied the references from the JMS 2.0 specification. I also checked that the section numbers are correct and they are.

hussainnm · 2020-05-08T12:16:55Z

spec/src/main/asciidoc/messaging-spec.adoc


-The JMS API is designed to be suitable for use by both Java client
+The Jakarta Messaging API is designed to be suitable for use by both Java client
 applications using the Java™ Platform, Standard Edition (Java SE), and
 Java middle-tier services using the Java™ Platform, Enterprise Edition


2 occurrences of Java™ Platform, Enterprise Edition needs to be changed to Jakarta EE Platform.

I've fixed those references.

I also removed references to specific versions of Jakarta EE platform or Enterprise Beans as they obsolete with every new version. They were confusing anyway because they referred to an older version of Java EE because the JMS spec was finalized before the version of Java EE spec that included it. If we don't use the exact version, it should be implicitly the Jakarta EE version that includes this version of Jakarta Messaging.

OndroMih · 2020-05-08T17:51:21Z

No problem with raising more issues as you continue reviewing the document, @hussainnm. I'm glad that you're so thorough. Is it OK if I keep fixing issues you report as soon as possible or if I wait until you're finished with your review? What's more convenient for you?

Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

hussainnm

There is another missing underscore in 3.8.1.1. Message selector syntax on L1442

Table 8-1 and 8-2 do not need header in section 8.5. Receiving messages synchronously and
8.6. Receiving message bodies synchronously respectively

Add Code blocks in 7.10 JMSProducer method chaining, 12.4.3 Injection Syntax, Chapter 14 and 15
Also review and indent the code within code blocks. There are a few unnecessary backslashes().

Chapter 16 was Appendix A in the original document. There are three references A.1, A1.8, A1.9. You have two options:

change Chapter 16 to Appendix A or
change the references to Chapter 16, 16.1.8, 16.1.9 respectively.

Just a general observation, the keywords like class names, method names, etc., need to be in monospace (``) for better readability. You could do this in a separate PR.

hussainnm · 2020-05-08T23:05:19Z

spec/src/main/asciidoc/messaging-spec.adoc

@@ -1245,18 +1241,18 @@ properties are undefined.

 ==== Provider-specific properties

-JMS reserves the ‘JMS___<vendor_name>__’ property name prefix for
+Jakarta Messaging reserves the ‘JMS___<vendor_name>__’ property name prefix for


There is a problem here with the underscore missing between JMS and <vendor_name>. The missing underscore is showing up on the next line
This is formatting issue.

hussainnm · 2020-05-08T23:22:13Z

spec/src/main/asciidoc/messaging-spec.adoc

@@ -3102,7 +3101,7 @@ send(Destination destination, Message message)

 ____


Quote block is not required

Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

And a formatting fix Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

OndroMih · 2020-05-09T11:21:04Z

Thanks for more comments, @hussainnm.

I believe I've fixed all except I didn't change keywords in the text as it would be too much work now and also would pollute the diff for this PR. I may raise a separate PR after this is merged.

Here's what I've fixed today:

missing underscore in Message selector syntax and provider-specific properties
Removed headers for Table 8-1 and 8-2
Fixed all code blocks
Turned chapter 16 into Appendix (existing references to Appendix should now be OK)

hussainnm · 2020-05-09T11:41:28Z

spec/src/main/asciidoc/messaging-spec.adoc

+    try (JMSContext context=connectionFactory.createContext();){
+        context.createProducer().send(dataQueue,body);
+    }
+}



Missing closing block (----), this is messing rest of the document.

I was afraid this could happen, I should've doublechecked. This is fixed and I also fixed it in one more place which Asciidoctor reported as missing ending element.

Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

hussainnm

Line 6052 and 6074 is missing closing block.

Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

OndroMih · 2020-05-09T21:46:08Z

Line 6052 and 6074 is missing closing block.

Fixed. There were a few more which I discovered using a regex search.

hussainnm

LGTM

arjantijms · 2020-06-06T19:45:01Z

Amazing work everyone! Thanks a bunch :)

I'll merge this now. If there are additional changes needed they can be done in follow-up PRs.

tivrfoa added 7 commits May 3, 2020 11:22

Change "Java EE" to "Jakarta EE"

2bd5796

Signed-off-by: Leandro Coutinho <lescoutinhovr@gmail.com>

Replace all ocurrences of javax.jms for jakarta.jms in messaging-spec…

4683591

….adoc Signed-off-by: Leandro Coutinho <lescoutinhovr@gmail.com>

Change JMS to Jakarta Messaging in messaging-spec.adoc

6032b2d

Signed-off-by: Leandro Coutinho <lescoutinhovr@gmail.com>

Replace other ocurrences of "JMS" to "Jakarta Messaging" in the spec.

8e19c83

Signed-off-by: Leandro Coutinho <lescoutinhovr@gmail.com>

fix package name

46ac63c

Signed-off-by: Leandro Coutinho <lescoutinhovr@gmail.com>

Use JMS when referring to historic moments.

d9c2690

Signed-off-by: Leandro Coutinho <lescoutinhovr@gmail.com>

Update copyright years to 2020

310ac48

Signed-off-by: Leandro Coutinho <lescoutinhovr@gmail.com>

OndroMih requested review from dblevins and bshannon May 3, 2020 09:27

OndroMih mentioned this pull request May 3, 2020

Initial spec doc contribution for Jakarta EE #274

Closed

hussainnm reviewed May 3, 2020

View reviewed changes

Changed "3 interfaces" back to original "4 interfaces"

6998f9f

Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

Ondrej Mihalyi added 3 commits May 7, 2020 18:41

Replaced references to JTA with Jakarta Transactions

475e561

JTA transaction replaced with Jakarta transaction Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

Replaced Enterprise JavaBeans with Jakarta Enterprise Beans

0a2b18c

Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

hussainnm reviewed May 8, 2020

View reviewed changes

spec/src/main/asciidoc/messaging-spec.adoc Outdated Show resolved Hide resolved

spec/src/main/asciidoc/messaging-spec.adoc Outdated Show resolved Hide resolved

spec/src/main/asciidoc/messaging-spec.adoc Outdated Show resolved Hide resolved

Ondro Mihályi and others added 2 commits May 8, 2020 13:26

Fixed references to jakarta.* APIs

8367a54

Co-authored-by: hussainnm <mailathussain@yahoo.com>

Spec document: JTA -> Java for XAResource API

e2eb4a3

Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

hussainnm reviewed May 8, 2020

View reviewed changes

Ondrej Mihalyi added 2 commits May 8, 2020 20:06

Fixed spec: references to Java Platform EE

839811a

Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

Fixed spec doc: missing references to sections

0d112ce

Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

hussainnm reviewed May 8, 2020

View reviewed changes

Ondrej Mihalyi added 3 commits May 9, 2020 09:57

Spec doc: fix formatting

6f3a512

Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

Spec doc: Fixed code blocks

33885c1

Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

Spec doc: Use appendix template

446c687

And a formatting fix Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

hussainnm reviewed May 9, 2020

View reviewed changes

Spec doc: Fix of formatting

392dc2a

Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

hussainnm reviewed May 9, 2020

View reviewed changes

Spec doc - fix of missing code block endings

75e563c

Signed-off-by: Ondro Mihalyi <ondrej.mihalyi@payara.fish>

hussainnm approved these changes May 9, 2020

View reviewed changes

ivargrimstad self-requested a review June 6, 2020 08:11

ivargrimstad approved these changes Jun 6, 2020

View reviewed changes

arjantijms approved these changes Jun 6, 2020

View reviewed changes

arjantijms merged commit 1f8e032 into jakartaee:master Jun 6, 2020

OndroMih mentioned this pull request May 3, 2021

Jakarta-ize JMS Specification document #266

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Initial spec doc contribution for Jakarta EE #275

Initial spec doc contribution for Jakarta EE #275

OndroMih commented May 3, 2020

hussainnm left a comment

hussainnm May 3, 2020

OndroMih May 7, 2020

OndroMih commented May 7, 2020

OndroMih commented May 7, 2020

OndroMih commented May 7, 2020

hussainnm May 8, 2020

OndroMih May 8, 2020

hussainnm left a comment

hussainnm left a comment

hussainnm May 8, 2020

OndroMih May 8, 2020

hussainnm May 8, 2020

OndroMih May 8, 2020

OndroMih commented May 8, 2020

hussainnm left a comment •

edited

Loading

hussainnm May 8, 2020

OndroMih May 9, 2020

hussainnm May 8, 2020

OndroMih May 9, 2020

OndroMih commented May 9, 2020 •

edited

Loading

hussainnm May 9, 2020

OndroMih May 9, 2020

hussainnm left a comment

OndroMih commented May 9, 2020 •

edited

Loading

hussainnm left a comment

arjantijms commented Jun 6, 2020


		For historical reasons JMS offers four alternative sets of interfaces
		For historical reasons Jakarta Messaging offers three alternative sets of interfaces

		@@ -3102,7 +3101,7 @@ send(Destination destination, Message message)

		____

Initial spec doc contribution for Jakarta EE #275

Initial spec doc contribution for Jakarta EE #275

Conversation

OndroMih commented May 3, 2020

hussainnm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

OndroMih commented May 7, 2020

OndroMih commented May 7, 2020

OndroMih commented May 7, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hussainnm left a comment

Choose a reason for hiding this comment

hussainnm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

OndroMih commented May 8, 2020

hussainnm left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

OndroMih commented May 9, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hussainnm left a comment

Choose a reason for hiding this comment

OndroMih commented May 9, 2020 • edited Loading

hussainnm left a comment

Choose a reason for hiding this comment

arjantijms commented Jun 6, 2020

hussainnm left a comment •

edited

Loading

OndroMih commented May 9, 2020 •

edited

Loading

OndroMih commented May 9, 2020 •

edited

Loading