Update README

[siwany]

Update README.adoc

[gkwan-ibm]

• "Open Liberty, which supports Jakarta Messaging API, will be used to demonstrate how to build scalable messaging solutions. " and "...By the end of this tutorial, you will have implemented ..."
  • rephrase this paragraph that no need to mention Open Liberty
  • e.g. "In this guide, you will use Jakarta Messaging APIs to build ..., and implment ..."
• "What is Java Message Service (JMS) ?" -> "What is Jakarta Messaging?"
  • update the following paragraph
• "What is Jakarta Messaging ?" -> "What is Jakarta Messaging?"
• Additional prerequisites
  • remove the macro statement ifdef::docker[] and endif::docker[]
  • Docker is not need if not run the IBM MQ section
  • IBM MQ container is required to run on Linux
  • let make the paragraph clear
  • "If you won’t be ..., you don’t need..."
    • use positive wordings (not use "won't" and "don't"
  • Not use points form in here
• Try what you’ll build
  • ref: https://openliberty.io/guides/microprofile-jwt.html#try-what-youll-build or https://openliberty.io/guides/grpc-intro.html#try-what-youll-build
  • "To try out the test, first go to the finish directory and run the following Maven goal that builds the application, starts the containers, runs the tests, and then stops the containers:"
    • rewrite this paragraph because no need to start/stop containers
  • "...your Liberty instance is ready:" -> "...your Liberty instances are ready:"
  • "Then, visit the http://localhost:9080/health URL ..."
    • shorten this paragraph because we do not implement all 3 health checks. Maybe like this "Visit the http://localhost:9080/health URL to confirm that the system microservice is up and running."
  • rewrite the paragraphs after "Also, the system and inventory services..", similar to https://openliberty.io/guides/microprofile-reactive-messaging.html#testing-the-application
    • keep to mention curl command
    • no need to mention http://localhost:9085/inventory/systems/{hostname}
    • format the output better
      • multiple lines
      • your hostname -> <your hostname>
      • current systemLoad value -> any number
  • keep "After you are finished ...", it is fine
  • Under the curl command, the "After you see the following message ..." and the output are not necessary.

[gkwan-ibm]

• Creating the message producer in the system service section
  • the 2 paragraphs "The SystemService class ..." and "The messages are transported..." seems containing dup information
    • improve or combine them
    • Publisher -> publisher
    • context.createProducer().send() -> send()
    • in the SystemService class, add an empty line before @Schedule...
    • move the "This method creates new ..." statement before the " The @Schedule..." statement
  • polish the paragraph "Add the jms feature ..."
    • not jms feature but messaging-3.1 and messagingClient-3.0
    • connection manager -> connectionManager element
      • missing the word element
      • "...to handle connections for the inventory system. " -> "...to handle connections for the messaging server runnind on the inventory service. "
    • configure a JMSQueueConnectionFactory -> define the jmsQueueConnectionFactory element
      • JMSQueueConnectionFactory -> jmsQueueConnectionFactory
      • "...to use this connection manager..." -> "...to use the InventoryCM connection manager ..."
      • also add a hotspot on InventoryCM
      • "...set its properties..." -> "...set the required remoteServerAddress properties..."
        • remove the "Add host and port variables ..." statement
        • hotpot remoteServerAddress with highlighting inventory.jms.host and inventory.jms.port
      • multiple "and" words. It is better to separate the "... and the jmsQueue ..." to a new statement
      • reduce "Also, ..", "Then, ..."
      • Combine the "Add the..." and "This feature enables..." -> "The messaging-3.1 and messagingClient-3.0 features enable..."
    • JMS Queue for the inventory system -> jmsQueue element for the inventory queue
  • polish the paragraph "If you want to learn ..."
    • "jmsQueue Server Properties" -> "JMS Queue"
    • "...see the jmsQueue..." -> "...see the JMS Queue..."
    • "jmsQueueConnectionFactory Server Properties" -> "JMS Queue Connection Factory" documents respectively
      • missing the "documents respectively."

[gkwan-ibm]

• Creating the message producer in the system service section
  • add instruction to start the dev mode
  • "(its CPU usage)" -> "(CPU usage)"
  • in the SystemService.java, the following line is too long, split it into 2 lines
    • SystemLoad systemLoad = new SystemLoad(getHostname(), Double.valueOf(OS_MEAN.getSystemLoadAverage()));
  • following 2 statements for the send() method have similar meaning, can combine or reduce?
    • "The send() method publishes its calculation as a message..."
    • "...then sends this information to the specified queue using send() method"
    • I suggest following:

      • The SystemService class contains the sendSystemLoad() method that calculates the average system load, creates an SystemLoad object, and publishes the object as a message by using the send() API to the jms/InventoryQueue queue running in the Jakarta messaging system. The @Schedule annotation...

        • sendSystemLoad() hotspot highlights the whole method as you already did
        • SystemLoad hotspot highlights the 2 lines to create the object
        • send() hotspot highlights the line as you already did
        • jms/InventoryQueue highlights the 2 lines for @Resource(lookup... and private Queue queue;
  • remove the hotspot of sendSystemLoad() in this statement "The @Schedule annotation on the sendSystemLoad() ..."
  • the hotspot of remoteServerAddress should not only highlight the variables but also highlight the whole properties.wasJms
    • "Set up the required remoteServerAddress ..."
    • sorry, I mean you can use multiple hotspots as https://github.com/OpenLiberty/guide-microprofile-openapi/blob/a375ff12f02613e26e9fb11158308207d7f4973f/README.adoc?plain=1#L208

[gkwan-ibm]

• Creating the consumer in the inventory microservice
  • remove the Navigate statement
  • the dev mode instruction should start the inventory service only
    • remove the whole "When you run ..." statement because we already explain in the previous system section
    • remove the "Dev mode holds..." statement for the same reason
  • "The InventoryQueueListener class..." -> "The InventoryQueueListener class..."
  • "... load information from JSON ..." -> "... load message from JSON ..."
  • I suggest the following

    • The inventory microservice receives the messages from the system microservice. Implement the InventoryQueueListener class with the MessageListener interface and annotate with @MessageDriven for listening the jms/InventoryQueue queue. Override the onMessage() method that processes the incoming messages, updates the inventory by using the InventoryManager bean, and logs the action. Use the SystemLoad.fromJson() method to convert the JSON message string to SystemLoad object.

    • InventoryQueueListener hotspot highlight the whole class
    • @MessageDriven hotspot highlight the annotation line
    • onMessage() hotspot highlight the method as already did
    • InventoryManager hotspot highlight the 2 @Inject lines and the if (manager.getSystem(... else {...} code block
    • SystemLoad.fromJson() hotspot highlight the line
  • Rewrite "Add the wasJmsEndpoint to listen for message from the InventoryQueue. "
    • https://openliberty.io/docs/latest/reference/config/wasJmsEndpoint.html
  • remove "Then" and "Lastly"
  • "... JMSQueueConnectionFactory to use this connection manager ..."
    • "this" is not clear, maybe same as the system service section to mention InventoryCM
  • missing explanation to the messagingEngine element
  • need to add the word "element" or "configuration" after the config wasJmsEndpoint, JMSQueueConnectionFactory, JMSQueue, JMSActivationSpec elements
    • also the letter case should match as the server.xml
• Running the application
  • add curl instruction similar to the Try what you’ll build section

[gkwan-ibm]

• Creating the message producer in the system service section
  • "... to use the InventoryCM. Set ..." -> "... to use the InventoryCM and set ..."
  • "...properties and the jmsQueue element for the inventory queue." -> "...properties. Use the jmsQueue element to define the inventory queue."
  • the remoteServerAddress hotspot highlights too many lines, it should highlight
    • update the tag/end properties.wasJms to propertiesWasJms in the server.xml and the hotspot in the README.adoc
    • in finish/system/src/main/liberty/config/server.xml, update the tag/end properties.wasJms comments to propertiesWasJms
• Creating the consumer in the inventory microservice
  • the InventoryManager hotspot should highlight

    @Inject
    private InventoryManager manager;

and

                if (manager.getSystem(hostname).isPresent()) {
                    manager.updateCpuStatus(hostname, loadAverage);
                    logger.info("Host " + hostname + " was updated: " + loadAverage);
                } else {
                    manager.addSystem(hostname, loadAverage);
                    logger.info("Host " + hostname + " was added: " + loadAverage);
                }

• JMSQueueConnectionFactory -> jmsQueueConnectionFactory
• JMSQueue -> jmsQueue
• JMSActivationSpec element to configures ... -> jmsActivationSpec element to configure ...

[gkwan-ibm]

• Testing the inventory application
  • "testNonEmpty() verifies that the host name..." -> "testNonEmpty() verifies that the hostname ..."
    • "host name" -> "hostname"
  • let remove the following paragraphs
    • "The @BeforeAll annotation..."
    • "The @BeforeEach and @AfterEach ..."
    • "To force these test cases ..."
  • remove "Alternatively, you can run..."
  • remove the stop commands

mvn -pl inventory liberty:stop
mvn -pl system liberty:stop

• • "where you ran Liberty." -> "...where you ran the system and inventory services."
• Running the tests
  • "...where you started dev mode." -> "...where you started dev mode for the inventory service."

[gkwan-ibm]

• What you’ll learn
  • "Additionally, you will discover how to integrate Liberty Messaging Server with IBM MQ." -> "Additionally, you will discover how to use IBM MQ for Jakarta Messaging."
• Using IBM MQ - Optional
  • "Now that the application is built and tested, deploy it using IBM MQ." -> "The application has been built and tested. In this section, you'll learn how to configure Liberty to use IBM MQ as the messaging server."
  • "IBM-MQ" -> "IBM MQ"
  • -> "If you’re a Mac user, check out this website for the How to build Mac IBM MQ container image guide on building IBM-MQ container image before starting this section.
  • try move the Mac instruction inside the Mac tab and polish the content better
  • inside the Mac tab
    • remove "before starting the following command" and add a . at the end of the statement
    • docker volume create qm1data and docker run ... should be moved after the statement "If it builds
      successfully, ..."
    • theibm-mqadvanced-server-dev:9.4.0.0-arm64. -> the ibm-mqadvanced-server-dev:9.4.0.0-arm64.
    • better to use \ to align the docker run command better like Win and Linux
    • split --detach --env MQ_APP_PASSWORD=passw0rd \ to 2 lines
  • inside the Win and Linux tabs
    • split --env MQ_APP_PASSWORD=passw0rd --env MQ_ADMIN_PASSWORD=passw0rd \ to 2 lines
  • Remove statement "Next, replace the pom.xml files of the system."
  • update the command title "Replace the system's pom.xml configuration file." -> "Replace the pom.xml file of the system service."
  • need to describe what are changed for the system pom.xml
  • Remove statement "Replace the pom.xml files of the inventory."
  • update the command title "Replace the inventory's pom.xml configuration file." -> "Replace the pom.xml file of the inventory service."
  • "Add properties for Liberty IBM MQ container ..." -> "Add the liberty.var.ibmmq-* properties for the IBM MQ container. You can change to different values when you deploy the application on production environment without modifying the Liberty server.xml configuration file.
    • liberty.var.ibmmq-* hotspot should highlight the properties that you already did
  • "Replace the system's server.xml configuration file." -> "Replace the server.xml file of the system service."
  • remove the statement "Also, replace the server.xml files for the system service."
  • update the command title "Replace the system's server.xml configuration file." -> "Replace the server.xml file of the system service."
  • Replace the paragraph "Add variables for IBM MQ settings into jmsQueueConnectionFactory ..." -> "Replace the properties.wasJms configuration by the properties.wmqjmsra configuration. All property values are defined in the pom.xml file that you have replaced in the step. Also, modify jmsQueue property to set the baseQueueName value with the ${ibmmq-inventory-queue-name} variable."
    • properties.wmqjmsra hotspot should highlight the whole block <properties.wmqjmsra .../>
    • <properties.wmqjmsra should indent 2 more spaces
    • no need to add hotspot on jmsQueue
    • baseQueueName hotspot should highlight <properties.wmqjmsra baseQueueName... />
    • in the server.xml, indent the <properties.wmqjmsra baseQueueName... /> with 4 spaces
  • "Replace the inventory's server.xml configuration file." -> Replace the server.xml file of the inventory service."
  • remove the statement "Replace the server.xml files for the inventory service."
  • update the command title "Replace the inventory's server.xml configuration file." -> "Replace the server.xml file fo the inventory service."
  • "Refine the ... for the inventory system, using variables..." -> "Refine the ... configurations with the variables..."
  • is missing to replace the inventory pom.xml file?
  • Improve the whole paragraph "Add property tags ..." better
    • Externalize the IBM MQ configuration properties in the properties configuration, so that you can change them when you deploy the application on production environment without modifying the Liberty server.xml configuration file.
    • add hotspot to the properties
  • the hotspots for both system and inventory server.xml seems not right and rewrite to the content that only mention the changes. I expect some configuration has no change, e.g. connectionManager
  • replace the paragraph "Since... " similar to the paragraph of "After you see the following message, your Liberty instance is ready in dev mode:" and the output
  • Move "After you see the following message,..." and output The defaultServer server... before the line "You can find the inventory and system services at the following URLs..."
  • "You can find the inventory and system services at the following URLs" -> "You can access the inventory service by the http://localhost:9085/inventory/systems URL."
  • "After you see the following message, your Liberty instance is ready in dev mode:" -> "After you see the following message, your Liberty instances are ready in dev mode:"
  • combine "Go to the command shell ...." and "If the tests pass,..." statements into a paragraph
  • "...dev mode and press enter/return and if the tests pass ..." -> "...dev mode and press enter/return to run the tests. If the tests pass ..."
  • "After ...the IBM MQ ... where you ran Liberty." -> "After ...the application ... where you ran the system and inventory services."
  • "...stop the Liberty instance first..." -> "...stop the Liberty instances ..."
  • reword the "When you’re finished trying out the IBM MQ, ..." paragraph
    • stop dev modes for both services
    • tear down the IBM MQ
  • remove "Alternatively, you can run the liberty:stop goal..." statment and the liberty:stop commands
  • "Stop ... Delete all IBM MQ ... commands:" paragraph -> "Run the following commands to stop the running IBM MQ container and clean up the qm1data volume:"

[gkwan-ibm]

Regarding the testApp.sh

• it failed, would you able to fix it?

INFO] Running it.io.openliberty.guides.inventory.InventoryEndpointIT
Error:  Tests run: 3, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 0.802 s <<< FAILURE! -- in it.io.openliberty.guides.inventory.InventoryEndpointIT
Error:  it.io.openliberty.guides.inventory.InventoryEndpointIT.testValue -- Time elapsed: 0.009 s <<< FAILURE!
org.opentest4j.AssertionFailedError: Hostname should be set by the first test. ==> expected: not <null>
	at org.junit.jupiter.api.AssertionFailureBuilder.build(AssertionFailureBuilder.java:152)
	at org.junit.jupiter.api.AssertionFailureBuilder.buildAndThrow(AssertionFailureBuilder.java:132)
	at org.junit.jupiter.api.AssertNotNull.failNull(AssertNotNull.java:49)
	at org.junit.jupiter.api.AssertNotNull.assertNotNull(AssertNotNull.java:35)
	at org.junit.jupiter.api.Assertions.assertNotNull(Assertions.java:312)
	at it.io.openliberty.guides.inventory.InventoryEndpointIT.testValue(InventoryEndpointIT.java:123)
	at java.base/java.lang.reflect.Method.invoke(Method.java:566)
	at java.base/java.util.ArrayList.forEach(ArrayList.java:1541)
	at java.base/java.util.ArrayList.forEach(ArrayList.java:1541)

• add the -ntp option to the following commands
  • mvn -pl models clean install
  • mvn -pl system liberty:stop
  • mvn -pl inventory liberty:stop
• remove the unnecessary comments
• add following at the end

docker stop QM1
docker volume remove qm1data

[gkwan-ibm]

• update the following code in all pom.xml files

            <plugin>
                <groupId>io.openliberty.tools</groupId>
                <artifactId>liberty-maven-plugin</artifactId>
                <version>3.10.2</version>
                <configuration>
                    <!-- devc config -->
                    <containerRunOpts>
                        -p 9085:9085
                        --network=reactive-app
                    </containerRunOpts>
                </configuration>
            </plugin>

to

            <plugin>
                <groupId>io.openliberty.tools</groupId>
                <artifactId>liberty-maven-plugin</artifactId>
                <version>3.10.2</version>
            </plugin>

[gkwan-ibm]

• testApp.sh
  • in the IBM MQ test, missing to copy the pom.xml and server.xml files from to ibmmq directory to the finish directory. The tests are not tested with IBM MQ and the required configuration.
  • remove line 48 and 64
  • in line 48, remove --platform linux/amd64 or remove the whole line
    • docker pull --platform linux/amd64 icr.io/ibm-messaging/mq:latest -> docker pull icr.io/ibm-messaging/mq:latest
• add the following line into both system and inventory server.xml

   <resourceAdapter id="wmqjmsra"
     location="https://repo.maven.apache.org/maven2/com/ibm/mq/wmq.jakarta.jmsra/9.3.5.0/wmq.jakarta.jmsra-9.3.5.0.rar" />

• In the IBM MQ section, after replace the server.xml, add a statement for adding resourceAdapter element to provide the RAR file that provides the IBM MQ classes for Java and Jakarta Messaging.
  • in the second paragraph, shorten the statement for resourceAdapter element
• align the both server.xml file

[poojasaji1]

Under Creating the consumer in the inventory microservice

• assigning a reliable and persistent destination for the InventoryQueue
  Under Try what you'll build
• in "by pressing CTRL+C in each command-line sessions where you" change sessions to session
  Under Running the tests
• in "stop the Liberty instance by pressing CTRL+C in each command-line sessions where you ran the system and inventory services." change sessions to session