Merge pull request #193 from pdudits/temp-queue-docs

Improving documentation for TempQueueTest

Author: arun-gupta

jms/temp-destination/src/main/java/org/javaee7/jms/temp/destination/JmsClient.java

@@ -15,33 +15,28 @@
  * @author Patrik Dudits
  */
 @Stateless
-@TransactionAttribute(TransactionAttributeType.NOT_SUPPORTED)
 public class JmsClient {
 
-    @Resource(name = Resources.REQUEST_QUEUE)
+    @Resource(lookup = Resources.REQUEST_QUEUE)
     Queue requestQueue;
 
     @Inject
     JMSContext jms;
 
+    @TransactionAttribute(TransactionAttributeType.NOT_SUPPORTED)        // <1> we need to send message in the middle of the method, therefore we cannot be transactional
     public String process(String request) {
 
-        // prepare the request message
         TextMessage requestMessage = jms.createTextMessage(request);
         TemporaryQueue responseQueue = jms.createTemporaryQueue();
-
-        // send the request
         jms.createProducer()
-                .setJMSReplyTo(responseQueue)
-                .send(requestQueue, requestMessage);
+                .setJMSReplyTo(responseQueue)                            // <2> set the temporary queue as replyToDestination
+                .send(requestQueue, requestMessage);                     // <3> immediately send the request message
 
-        // start listening on the temp queue for response
-        try (JMSConsumer consumer = jms.createConsumer(responseQueue)) {
+        try (JMSConsumer consumer = jms.createConsumer(responseQueue)) { // <4> listen on the temporary queue
 
-            // wait for the response
-            String response = consumer.receiveBody(String.class, 2000);
+            String response = consumer.receiveBody(String.class, 2000);  // <5> wait for a +TextMessage+ to arrive
 
-            if (response == null) {
+            if (response == null) {                                      // <6> +receiveBody+  returns +null+ in case of timeout
                 throw new IllegalStateException("Message processing timed out");
             } else {
                 return response;

jms/temp-destination/src/main/java/org/javaee7/jms/temp/destination/RequestResponseOverJMS.java

@@ -22,18 +22,17 @@ public class RequestResponseOverJMS implements MessageListener {
     @Override
     public void onMessage(Message message) {
         try {
-            Destination replyTo = message.getJMSReplyTo();
+            Destination replyTo = message.getJMSReplyTo(); // <1> get the destination for the response
             if (replyTo == null) {
-                // no response required, finish now.
                 return;
             }
             TextMessage request = (TextMessage) message;
-            String payload = request.getText();
+            String payload = request.getText();            // <2> read the payload
 
             System.out.println("Got request: "+payload);
 
-            String response = "Processed: "+payload;
-            jms.createProducer().send(replyTo, response);
+            String response = "Processed: "+payload;       // <3> process the request
+            jms.createProducer().send(replyTo, response);  // <4> send the response
         } catch (JMSException e) {
             e.printStackTrace();
         }

jms/temp-destination/src/test/java/org/javaee7/jms/temp/destination/TempQueueTest.java

@@ -14,7 +14,7 @@
  * Temporary queues are JMS queues that exist for the lifetime of single JMS connection.
  * Also the reception of the messages is exclusive to the connection, therefore no
  * reasonable use case exist for temporary topic within Java EE container, as connection
- * is usually exclusive to single component.
+ * is exclusive to single component.
  *
  * Temporary queues are usually used as reply channels for request / response communication
  * over JMS.
@@ -27,11 +27,15 @@ public class TempQueueTest {
      * listens on a Queue and passes the response to the destination specified in
      * +JMSReplyTo+ header of the message.
      *
+     * include::RequestResponseOverJMS#onMessage[]
+     *
      * +JmsClient+ is a client to this server, and has to be non transactional,
      * otherwise the request would be first sent upon commit, i. e. after the
      * business method finishes. That would be too late. We need to send the message
      * immediately, and wait for the response to arrive.
      *
+     * include::JmsClient#process[]
+     *
      */
     @Deployment
     public static WebArchive deployment() {