HORNETQ-185 + HORNETQ-186: API review + javadoc

* added javadoc for QueueControl API

src/main/org/hornetq/core/management/QueueControl.java

@@ -21,117 +21,265 @@
 import org.hornetq.core.server.management.Parameter;
 
 /**
- * @author <a href="mailto:jmesnil@redhat.com">Jeff Mesnil</a>
- * 
- * @version <tt>$Revision$</tt>
+ * A QueueControl is used to manage a queue.
  * 
+ * @author <a href="mailto:jmesnil@redhat.com">Jeff Mesnil</a>
  */
 public interface QueueControl
 {
    // Attributes ----------------------------------------------------
 
+   /**
+    * Returns the name of this queue.
+    */
    String getName();
 
+   /**
+    * Returns the address this queue is bound to.
+    */
    String getAddress();
 
+   /**
+    * Returns this queue ID.
+    */
    long getID();
 
+   /**
+    * Returns whether this queue is temporary.
+    */
    boolean isTemporary();
 
+   /**
+    * Returns whether this queue is durable.
+    */
    boolean isDurable();
 
+   /**
+    * Returns the filter associated to this queue.
+    */
    String getFilter();
 
+   /**
+    * Returns the number of messages currently in this queue.
+    */
    int getMessageCount();
 
+   /**
+    * Returns the number of scheduled messages in this queue.
+    */
    long getScheduledCount();
 
+
+   /**
+    * Returns the number of consumers consuming messages from this queue.
+    */
    int getConsumerCount();
 
+   /**
+    * Returns the number of messages that this queue is currently delivering to its consumers.
+    */
    int getDeliveringCount();
 
+   /**
+    * Returns the number of messages added to this queue since it was created.
+    */
    int getMessagesAdded();
 
+   /**
+    * Returns the expiry address associated to this queue.
+    */
    String getExpiryAddress();
 
+   /**
+    * Sets the expiry address associated to this queue to the specified expiryAddress.
+    */
    void setExpiryAddress(@Parameter(name = "expiryAddress", desc = "Expiry address of the queue") String expiryAddres) throws Exception;
 
+   /**
+    * Returns the dead-letter address associated to this queue.
+    */
    String getDeadLetterAddress();
 
+   /**
+    * Sets the dead-letter address associated to this queue to the specified deadLetterAddress.
+    */
    void setDeadLetterAddress(@Parameter(name = "deadLetterAddress", desc = "Dead-letter address of the queue") String deadLetterAddress) throws Exception;
 
    // Operations ----------------------------------------------------
 
+   /**
+    * Lists all the messages scheduled for delivery for this queue.
+    * <br>
+    * 1 Map represents 1 message, keys are the message's properties and headers, values are the corresponding values.
+    */
    @Operation(desc = "List the messages scheduled for delivery", impact = MBeanOperationInfo.INFO)
    Map<String, Object>[] listScheduledMessages() throws Exception;
 
+   /**
+    * Lists all the messages scheduled for delivery for this queue using JSON serialization.
+    */
    @Operation(desc = "List the messages scheduled for delivery and returns them using JSON", impact = MBeanOperationInfo.INFO)
    String listScheduledMessagesAsJSON() throws Exception;
 
+   /**
+     * Lists all the messages in this queue matching the specified filter.
+    * <br>
+    * 1 Map represents 1 message, keys are the message's properties and headers, values are the corresponding values.
+    */
    @Operation(desc = "List all the messages in the queue matching the given filter", impact = MBeanOperationInfo.INFO)
    Map<String, Object>[] listMessages(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filter) throws Exception;
 
+   /**
+    * Lists all the messages in this queue matching the specified filter using JSON serialization.
+   */
    @Operation(desc = "List all the messages in the queue matching the given filter and returns them using JSON", impact = MBeanOperationInfo.INFO)
    String listMessagesAsJSON(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filter) throws Exception;
 
+   /**
+    * Counts the number of messages in this queue matching the specified filter.
+    */
    @Operation(desc = "Returns the number of the messages in the queue matching the given filter", impact = MBeanOperationInfo.INFO)
    int countMessages(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filter) throws Exception;
 
+   /**
+    * Removes the message corresponding to the specified message ID.
+    *
+    * @return {@code true}Êif the message was removed, {@code false} else
+    */
    @Operation(desc = "Remove the message corresponding to the given messageID", impact = MBeanOperationInfo.ACTION)
    boolean removeMessage(@Parameter(name = "messageID", desc = "A message ID") long messageID) throws Exception;
 
+   /**
+    * Removes all the message corresponding to the specified filter.
+    * <br>
+    * Using {@code null} or an empty filter will remove <em>all</em> messages from this queue.
+    * 
+    * @return the number of removed messages
+    */
    @Operation(desc = "Remove the messages corresponding to the given filter (and returns the number of removed messages)", impact = MBeanOperationInfo.ACTION)
    int removeMessages(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filter) throws Exception;
 
-   @Operation(desc = "Remove the messages corresponding to the given filter (and returns the number of expired messages)", impact = MBeanOperationInfo.ACTION)
+   /**
+    * Expires all the message corresponding to the specified filter.
+    * <br>
+    * Using {@code null} or an empty filter will expire <em>all</em> messages from this queue.
+    * 
+    * @return the number of expired messages
+    */
+   @Operation(desc = "Expire the messages corresponding to the given filter (and returns the number of expired messages)", impact = MBeanOperationInfo.ACTION)
    int expireMessages(@Parameter(name = "filter", desc = "A message filter") String filter) throws Exception;
 
+   /**
+    * Expires the message corresponding to the specified message ID.
+    *
+    * @return {@code true}Êif the message was expired, {@code false} else
+    */
    @Operation(desc = "Remove the message corresponding to the given messageID", impact = MBeanOperationInfo.ACTION)
    boolean expireMessage(@Parameter(name = "messageID", desc = "A message ID") long messageID) throws Exception;
 
+   /**
+    * Moves the message corresponding to the specified message ID to the specified other queue.
+    *
+    * @return {@code true}Êif the message was moved, {@code false} else
+    */
    @Operation(desc = "Move the message corresponding to the given messageID to another queue", impact = MBeanOperationInfo.ACTION)
    boolean moveMessage(@Parameter(name = "messageID", desc = "A message ID") long messageID,
                        @Parameter(name = "otherQueueName", desc = "The name of the queue to move the message to") String otherQueueName) throws Exception;
 
+   /**
+    * Moves all the message corresponding to the specified filter  to the specified other queue.
+    * <br>
+    * Using {@code null} or an empty filter will move <em>all</em> messages from this queue.
+    * 
+    * @return the number of moved messages
+    */
    @Operation(desc = "Move the messages corresponding to the given filter (and returns the number of moved messages)", impact = MBeanOperationInfo.ACTION)
    int moveMessages(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filter,
                     @Parameter(name = "otherQueueName", desc = "The name of the queue to move the messages to") String otherQueueName) throws Exception;
 
+   /**
+    * Sends the message corresponding to the specified message ID to this queue's dead letter address.
+    *
+    * @return {@code true}Êif the message was sent to the dead letter address, {@code false} else
+    */
    @Operation(desc = "Send the message corresponding to the given messageID to this queue's Dead Letter Address", impact = MBeanOperationInfo.ACTION)
    boolean sendMessageToDeadLetterAddress(@Parameter(name = "messageID", desc = "A message ID") long messageID) throws Exception;
 
+   /**
+    * Sends all the message corresponding to the specified filter to this queue's dead letter address.
+    * <br>
+    * Using {@code null} or an empty filter will send <em>all</em> messages from this queue.
+    * 
+    * @return the number of sent messages
+    */
    @Operation(desc = "Send the messages corresponding to the given filter to this queue's Dead Letter Address", impact = MBeanOperationInfo.ACTION)
    int sendMessagesToDeadLetterAddress(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filterStr) throws Exception;
 
+   /**
+    * Changes the message's priority corresponding to the specified message ID to the specified priority.
+    * 
+    * @param priority between 0 and 9 inclusive.
+    *
+    * @return {@code true}Êif the message priority was changed
+    */
    @Operation(desc = "Change the priority of the message corresponding to the given messageID", impact = MBeanOperationInfo.ACTION)
    boolean changeMessagePriority(@Parameter(name = "messageID", desc = "A message ID") long messageID,
                                  @Parameter(name = "newPriority", desc = "the new priority (between 0 and 9)") int newPriority) throws Exception;
 
+   /**
+    * Changes the priority for all the message corresponding to the specified filter to the specified priority.
+    * 
+    * @return the number of changed messages
+    */
    @Operation(desc = "Change the priority of the messages corresponding to the given filter", impact = MBeanOperationInfo.ACTION)
    int changeMessagesPriority(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filter,
                               @Parameter(name = "newPriority", desc = "the new priority (between 0 and 9)") int newPriority) throws Exception;
 
+   /**
+    * Lists the message counter for this queue.
+    */
    @Operation(desc = "List the message counters", impact = MBeanOperationInfo.INFO)
    String listMessageCounter() throws Exception;
 
+   /**
+    * Resets the message counter for this queue.
+    */
    @Operation(desc = "Reset the message counters", impact = MBeanOperationInfo.INFO)
    void resetMessageCounter() throws Exception;
 
+   /**
+    * Lists the message counter for this queue as a HTML table.
+    */
    @Operation(desc = "List the message counters as HTML", impact = MBeanOperationInfo.INFO)
    String listMessageCounterAsHTML() throws Exception;
 
+   /**
+    * Lists the message counter history for this queue.
+    */
    @Operation(desc = "List the message counters history", impact = MBeanOperationInfo.INFO)
    String listMessageCounterHistory() throws Exception;
 
+   /**
+    * Lists the message counter history for this queue as a HTML table.
+    */
    @Operation(desc = "List the message counters history HTML", impact = MBeanOperationInfo.INFO)
    String listMessageCounterHistoryAsHTML() throws Exception;
 
+   /**
+    * Pauses the queue. Messages are no longer delivered to its consumers.
+    */
    @Operation(desc = "Pauses the Queue", impact = MBeanOperationInfo.ACTION)
    void pause() throws Exception;
 
+   /**
+    * Resumes the queue. Messages are again delivered to its consumers.
+    */
    @Operation(desc = "Resumes delivery of queued messages and gets the queue out of paused state.", impact = MBeanOperationInfo.ACTION)
    void resume() throws Exception;
 
+   /**
+    * Returns whether the queue is pause.
+    */
    @Operation(desc = "Inspects if the queue is paused", impact = MBeanOperationInfo.INFO)
    boolean isPaused() throws Exception;
 }