[hornetq-commits] JBoss hornetq SVN: r8607 - trunk/src/main/org/hornetq/core/client.

[do-not-reply at jboss.org]

Author: jmesnil
Date: 2009-12-07 10:10:28 -0500 (Mon, 07 Dec 2009)
New Revision: 8607

Modified:
   trunk/src/main/org/hornetq/core/client/ClientRequestor.java
Log:
HORNETQ-186: fill in Javadocs for core API

* documented API

Modified: trunk/src/main/org/hornetq/core/client/ClientRequestor.java
===================================================================
--- trunk/src/main/org/hornetq/core/client/ClientRequestor.java	2009-12-07 14:53:52 UTC (rev 8606)
+++ trunk/src/main/org/hornetq/core/client/ClientRequestor.java	2009-12-07 15:10:28 UTC (rev 8607)
@@ -21,7 +21,14 @@
 
 
 /**
- * a ClientRequestor.
+ * The ClientRequestor class helps making requests.
+ *
+ * The ClientRequestor constructor is given a ClientSession and a request address. 
+ * It creates a temporary queue for the responses and provides a request method that sends the request message and waits for its reply.
+ *
+ * @apiviz.uses org.hornetq.core.client.ClientSession
+ * @apiviz.owns org.hornetq.core.client.ClientProducer
+ * @apiviz.owns org.hornetq.core.client.ClientConsumer
  * 
  * @author <a href="jmesnil at redhat.com">Jeff Mesnil</a>
  */
@@ -35,6 +42,15 @@
 
    private final SimpleString replyQueue;
 
+   /**
+    * Constructor for the ClientRequestor.
+    * 
+    * The implementation expects a ClientSession with automatic commits of sends and acknowledgements
+    * 
+    * @param session a ClientSession uses to handle requests and replies 
+    * @param requestAddress the address to send request messages to
+    * @throws Exception
+    */
    public ClientRequestor(final ClientSession session, final SimpleString requestAddress) throws Exception
    {
       queueSession = session;
@@ -45,16 +61,36 @@
       replyConsumer = queueSession.createConsumer(replyQueue);
    }
 
+   /**
+    * @see ClientRequestor#ClientRequestor(ClientSession, SimpleString)
+    */
    public ClientRequestor(final ClientSession session, final String requestAddress) throws Exception
    {
       this(session, toSimpleString(requestAddress));
    }
 
+   /**
+    * Send a message to the request address and wait indefinitely for a reply.
+    * The temporary queue is used for the REPLYTO_HEADER_NAME, and only one reply per request is expected
+    *
+    * @param request the message to send
+    * @return the reply message
+    * @throws Exception
+    */
    public ClientMessage request(final ClientMessage request) throws Exception
    {
       return request(request, 0);
    }
 
+   /**
+    * Send a message to the request address and wait for the given timeout for a reply.
+    * The temporary queue is used for the REPLYTO_HEADER_NAME, and only one reply per request is expected
+    * 
+    * @param request  the message to send
+    * @param timeout the timeout to wait for a reply (in milliseconds)
+    * @return the reply message or <code>null</code> if no message is replied before the timeout elapses
+    * @throws Exception
+    */
    public ClientMessage request(final ClientMessage request, final long timeout) throws Exception
    {
       request.putStringProperty(ClientMessageImpl.REPLYTO_HEADER_NAME, replyQueue);
@@ -62,6 +98,11 @@
       return replyConsumer.receive(timeout);
    }
 
+   /**
+    * Close the ClientRequestor and its session.
+    * 
+    * @throws Exception if an exception occurs while closing the ClientRequestor
+    */
    public void close() throws Exception
    {
       replyConsumer.close();