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=&quot;jmesnil(a)redhat.com&quot;&gt;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();