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

[do-not-reply at jboss.org]

Author: ataylor
Date: 2009-12-09 06:48:23 -0500 (Wed, 09 Dec 2009)
New Revision: 8637

Modified:
   trunk/src/main/org/hornetq/core/client/ClientProducer.java
Log:
ClientProducer javadocs

Modified: trunk/src/main/org/hornetq/core/client/ClientProducer.java
===================================================================
--- trunk/src/main/org/hornetq/core/client/ClientProducer.java	2009-12-09 11:22:17 UTC (rev 8636)
+++ trunk/src/main/org/hornetq/core/client/ClientProducer.java	2009-12-09 11:48:23 UTC (rev 8637)
@@ -18,22 +18,43 @@
 import org.hornetq.utils.SimpleString;
 
 /**
+ * A ClientProducer is ised to send messages to a specific address. Messages are then routed on the server to any queues
+ * that are bound to the address. A ClientProducer can either be created with a specific address in mind or with none.
+ * With the latter the address must be provided using the appropriate send() method.  <br><br>
+ *
+ * The sending semantics can change depending on what blocking semantics are set via {@link ClientSessionFactory#setBlockOnDurableSend(boolean)}
+ * and {@link org.hornetq.core.client.ClientSessionFactory#setBlockOnNonDurableSend(boolean)} . If set to true
+ * then for each message type, durable and non durable respectively, any exceptions such as the address not existing or
+ * security exceptions will be thrown at the time of send. Alternatively if set to false then exceptions will only be
+ * logged on the server.      <br><br>
+ *
+ * The send rate can also be controlled via {@link ClientSessionFactory#setProducerMaxRate(int)}
+ * and the {@link org.hornetq.core.client.ClientSessionFactory#setProducerWindowSize(int)}. <br><br>
+ *
  * @author <a href="mailto:tim.fox at jboss.com">Tim Fox</a>
  * @author <a href="mailto:ataylor at redhat.com">Andy Taylor</a>
  */
 public interface ClientProducer
 {
    /**
-    * Return the address where messages will be sent to.
-    * The address can be <code>null</code> if the ClientProducer
-    * was creating without specifying an address with {@link ClientSession#createProducer()}. 
+    * Returns the address where messages will be sent.
+    *
+    * <br><br>The address can be <code>null</code> if the ClientProducer
+    *
+    * was creating without specifying an address, that is by using {@link ClientSession#createProducer()}. 
     * 
     * @return the address where messages will be sent
     */
    SimpleString getAddress();
 
    /**
-    * Send a message.
+    * Sends a message to an address.
+    *
+    * specified in {@link ClientSession#createProducer(String)} or similar methods.
+    *
+    * <br><br>This will block until confirmation that the message has reached the server has been received if
+    * {@link ClientSessionFactory#setBlockOnDurableSend(boolean)} or {@link org.hornetq.core.client.ClientSessionFactory#setBlockOnNonDurableSend(boolean)}
+    * are set to <code>true</code>  for the specified message type.
     * 
     * @param message the message to send
     * @throws HornetQException if an exception occurs while sending the message
@@ -41,8 +62,12 @@
    void send(Message message) throws HornetQException;
 
    /**
-    * Send a message to the specified address instead of the ClientProducer's address.
-    * 
+    * Sends a message to the specified address instead of the ClientProducer's address.
+    *
+    * <br><br>This will block until confirmation that the message has reached the server has been received if
+    * {@link ClientSessionFactory#setBlockOnDurableSend(boolean)} or {@link org.hornetq.core.client.ClientSessionFactory#setBlockOnNonDurableSend(boolean)}
+    * are set to true for the specified message type.
+    *
     * @param address the address where the message will be sent
     * @param message the message to send
     * @throws HornetQException if an exception occurs while sending the message
@@ -50,8 +75,12 @@
    void send(SimpleString address, Message message) throws HornetQException;
 
    /**
-    * Send a message to the specified address instead of the ClientProducer's address.
-    * 
+    * Sends a message to the specified address instead of the ClientProducer's address.
+    *
+    * <br><br>This will block until confirmation that the message has reached the server has been received if
+    * {@link ClientSessionFactory#setBlockOnDurableSend(boolean)} or {@link org.hornetq.core.client.ClientSessionFactory#setBlockOnNonDurableSend(boolean)}
+    * are set to true for the specified message type.
+    *
     * @param address the address where the message will be sent
     * @param message the message to send
     * @throws HornetQException if an exception occurs while sending the message
@@ -59,37 +88,37 @@
    void send(String address, Message message) throws HornetQException;
 
    /**
-    * Close the ClientProducer.
+    * Closes the ClientProducer. If already closed nothing is done.
     * 
     * @throws HornetQException if an exception occurs while closing the producer
     */
    void close() throws HornetQException;
 
    /**
-    * Return whether the producer is closed or not.
+    * Returns whether the producer is closed or not.
     * 
     * @return <code>true</code> if the producer is closed, <code>false</code> else
     */
    boolean isClosed();
 
    /**
-    * Return whether the producer will block when sending <em>durable</em> messages.
+    * Returns whether the producer will block when sending <em>durable</em> messages.
     * 
     * @return <code>true</code> if the producer blocks when sending durable, <code>false</code> else
     */
    boolean isBlockOnDurableSend();
 
    /**
-    * Return whether the producer will block when sending <em>non-durable</em> messages.
+    * Returns whether the producer will block when sending <em>non-durable</em> messages.
     * 
     * @return <code>true</code> if the producer blocks when sending non-durable, <code>false</code> else
     */
    boolean isBlockOnNonDurableSend();
 
    /**
-    * Return the producer maximum rate.
+    * Returns the maximum rate at which a ClientProducer can send messages per second.
     * 
-    * @return the producer maximum rate
+    * @return the producers maximum rate
     */
    int getMaxRate();
 }