    001    /*
    002     * Copyright 2009 Red Hat, Inc.
    003     * Red Hat licenses this file to you under the Apache License, version
    004     * 2.0 (the "License"); you may not use this file except in compliance
    005     * with the License.  You may obtain a copy of the License at
    006     *    http://www.apache.org/licenses/LICENSE-2.0
    007     * Unless required by applicable law or agreed to in writing, software
    008     * distributed under the License is distributed on an "AS IS" BASIS,
    009     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
    010     * implied.  See the License for the specific language governing
    011     * permissions and limitations under the License.
    012     */
    013
    014    package org.hornetq.api.core.management;
    015
    016    import java.util.Map;
    017
    018    import javax.management.MBeanOperationInfo;
    019
    020
    021    /**
    022     * A QueueControl is used to manage a queue.
    023     *
    024     * @author <a href="mailto:jmesnil@redhat.com">Jeff Mesnil</a>
    025     */
    026    public interface QueueControl
    027    {
    028       // Attributes ----------------------------------------------------
    029
    030       /**
    031        * Returns the name of this queue.
    032        */
    033       String getName();
    034
    035       /**
    036        * Returns the address this queue is bound to.
    037        */
    038       String getAddress();
    039
    040       /**
    041        * Returns this queue ID.
    042        */
    043       long getID();
    044
    045       /**
    046        * Returns whether this queue is temporary.
    047        */
    048       boolean isTemporary();
    049
    050       /**
    051        * Returns whether this queue is durable.
    052        */
    053       boolean isDurable();
    054
    055       /**
    056        * Returns the filter associated to this queue.
    057        */
    058       String getFilter();
    059
    060       /**
    061        * Returns the number of messages currently in this queue.
    062        */
    063       long getMessageCount();
    064
    065       /**
    066        * Returns the number of scheduled messages in this queue.
    067        */
    068       long getScheduledCount();
    069
    070       /**
    071        * Returns the number of consumers consuming messages from this queue.
    072        */
    073       int getConsumerCount();
    074
    075       /**
    076        * Returns the number of messages that this queue is currently delivering to its consumers.
    077        */
    078       int getDeliveringCount();
    079
    080       /**
    081        * Returns the number of messages added to this queue since it was created.
    082        */
    083       long getMessagesAdded();
    084
    085       /**
    086        * Returns the expiry address associated to this queue.
    087        */
    088       String getExpiryAddress();
    089
    090       /**
    091        * Sets the expiry address associated to this queue to the specified expiryAddress.
    092        */
    093       void setExpiryAddress(@Parameter(name = "expiryAddress", desc = "Expiry address of the queue") String expiryAddres) throws Exception;
    094
    095       /**
    096        * Returns the dead-letter address associated to this queue.
    097        */
    098       String getDeadLetterAddress();
    099
    100       /**
    101        * Sets the dead-letter address associated to this queue to the specified deadLetterAddress.
    102        */
    103       void setDeadLetterAddress(@Parameter(name = "deadLetterAddress", desc = "Dead-letter address of the queue") String deadLetterAddress) throws Exception;
    104
    105       // Operations ----------------------------------------------------
    106
    107       /**
    108        * Lists all the messages scheduled for delivery for this queue.
    109        * <br>
    110        * 1 Map represents 1 message, keys are the message's properties and headers, values are the corresponding values.
    111        */
    112       @Operation(desc = "List the messages scheduled for delivery", impact = MBeanOperationInfo.INFO)
    113       Map<String, Object>[] listScheduledMessages() throws Exception;
    114
    115       /**
    116        * Lists all the messages scheduled for delivery for this queue using JSON serialization.
    117        */
    118       @Operation(desc = "List the messages scheduled for delivery and returns them using JSON", impact = MBeanOperationInfo.INFO)
    119       String listScheduledMessagesAsJSON() throws Exception;
    120
    121       /**
    122        * Lists all the messages in this queue matching the specified filter.
    123        * <br>
    124        * 1 Map represents 1 message, keys are the message's properties and headers, values are the corresponding values.
    125        * <br>
    126        * Using {@code null} or an empty filter will list <em>all</em> messages from this queue.
    127        */
    128       @Operation(desc = "List all the messages in the queue matching the given filter", impact = MBeanOperationInfo.INFO)
    129       Map<String, Object>[] listMessages(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filter) throws Exception;
    130
    131       /**
    132        * Lists all the messages in this queue matching the specified filter using JSON serialization.
    133        * <br>
    134        * Using {@code null} or an empty filter will list <em>all</em> messages from this queue.
    135        */
    136       @Operation(desc = "List all the messages in the queue matching the given filter and returns them using JSON", impact = MBeanOperationInfo.INFO)
    137       String listMessagesAsJSON(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filter) throws Exception;
    138
    139       /**
    140        * Counts the number of messages in this queue matching the specified filter.
    141        * <br>
    142        * Using {@code null} or an empty filter will count <em>all</em> messages from this queue.
    143        */
    144       @Operation(desc = "Returns the number of the messages in the queue matching the given filter", impact = MBeanOperationInfo.INFO)
    145       long countMessages(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filter) throws Exception;
    146
    147       /**
    148        * Removes the message corresponding to the specified message ID.
    149        *
    150        * @return {@code true} if the message was removed, {@code false} else
    151        */
    152       @Operation(desc = "Remove the message corresponding to the given messageID", impact = MBeanOperationInfo.ACTION)
    153       boolean removeMessage(@Parameter(name = "messageID", desc = "A message ID") long messageID) throws Exception;
    154
    155       /**
    156        * Removes all the message corresponding to the specified filter.
    157        * <br>
    158        * Using {@code null} or an empty filter will remove <em>all</em> messages from this queue.
    159        *
    160        * @return the number of removed messages
    161        */
    162       @Operation(desc = "Remove the messages corresponding to the given filter (and returns the number of removed messages)", impact = MBeanOperationInfo.ACTION)
    163       int removeMessages(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filter) throws Exception;
    164
    165       /**
    166        * Expires all the message corresponding to the specified filter.
    167        * <br>
    168        * Using {@code null} or an empty filter will expire <em>all</em> messages from this queue.
    169        *
    170        * @return the number of expired messages
    171        */
    172       @Operation(desc = "Expire the messages corresponding to the given filter (and returns the number of expired messages)", impact = MBeanOperationInfo.ACTION)
    173       int expireMessages(@Parameter(name = "filter", desc = "A message filter") String filter) throws Exception;
    174
    175       /**
    176        * Expires the message corresponding to the specified message ID.
    177        *
    178        * @return {@code true} if the message was expired, {@code false} else
    179        */
    180       @Operation(desc = "Remove the message corresponding to the given messageID", impact = MBeanOperationInfo.ACTION)
    181       boolean expireMessage(@Parameter(name = "messageID", desc = "A message ID") long messageID) throws Exception;
    182
    183       /**
    184        * Moves the message corresponding to the specified message ID to the specified other queue.
    185        *
    186        * @return {@code true} if the message was moved, {@code false} else
    187        */
    188       @Operation(desc = "Move the message corresponding to the given messageID to another queue. rejectDuplicate=false on this case", impact = MBeanOperationInfo.ACTION)
    189       boolean moveMessage(@Parameter(name = "messageID", desc = "A message ID") long messageID,
    190                           @Parameter(name = "otherQueueName", desc = "The name of the queue to move the message to") String otherQueueName) throws Exception;
    191
    192       /**
    193        * Moves the message corresponding to the specified message ID to the specified other queue.
    194        *
    195        * @return {@code true} if the message was moved, {@code false} else
    196        */
    197       @Operation(desc = "Move the message corresponding to the given messageID to another queue", impact = MBeanOperationInfo.ACTION)
    198       boolean moveMessage(@Parameter(name = "messageID", desc = "A message ID") long messageID,
    199                           @Parameter(name = "otherQueueName", desc = "The name of the queue to move the message to") String otherQueueName,
    200                           @Parameter(name = "rejectDuplicates", desc = "Reject messages identified as duplicate by the duplicate message") boolean rejectDuplicates) throws Exception;
    201
    202       /**
    203        * Moves all the message corresponding to the specified filter  to the specified other queue.
    204        * RejectDuplicates = false on this case
    205        * <br>
    206        * Using {@code null} or an empty filter will move <em>all</em> messages from this queue.
    207        *
    208        * @return the number of moved messages
    209        */
    210       @Operation(desc = "Move the messages corresponding to the given filter (and returns the number of moved messages). RejectDuplicates=false on this case.", impact = MBeanOperationInfo.ACTION)
    211       int moveMessages(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filter,
    212                        @Parameter(name = "otherQueueName", desc = "The name of the queue to move the messages to") String otherQueueName) throws Exception;
    213
    214
    215       /**
    216        * Moves all the message corresponding to the specified filter  to the specified other queue.
    217        * <br>
    218        * Using {@code null} or an empty filter will move <em>all</em> messages from this queue.
    219        *
    220        * @return the number of moved messages
    221        */
    222       @Operation(desc = "Move the messages corresponding to the given filter (and returns the number of moved messages)", impact = MBeanOperationInfo.ACTION)
    223       int moveMessages(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filter,
    224                        @Parameter(name = "otherQueueName", desc = "The name of the queue to move the messages to") String otherQueueName,
    225                        @Parameter(name = "rejectDuplicates", desc = "Reject messages identified as duplicate by the duplicate message") boolean rejectDuplicates) throws Exception;
    226
    227       /**
    228        * Sends the message corresponding to the specified message ID to this queue's dead letter address.
    229        *
    230        * @return {@code true} if the message was sent to the dead letter address, {@code false} else
    231        */
    232       @Operation(desc = "Send the message corresponding to the given messageID to this queue's Dead Letter Address", impact = MBeanOperationInfo.ACTION)
    233       boolean sendMessageToDeadLetterAddress(@Parameter(name = "messageID", desc = "A message ID") long messageID) throws Exception;
    234
    235       /**
    236        * Sends all the message corresponding to the specified filter to this queue's dead letter address.
    237        * <br>
    238        * Using {@code null} or an empty filter will send <em>all</em> messages from this queue.
    239        *
    240        * @return the number of sent messages
    241        */
    242       @Operation(desc = "Send the messages corresponding to the given filter to this queue's Dead Letter Address", impact = MBeanOperationInfo.ACTION)
    243       int sendMessagesToDeadLetterAddress(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filterStr) throws Exception;
    244
    245       /**
    246        * Changes the message's priority corresponding to the specified message ID to the specified priority.
    247        *
    248        * @param newPriority between 0 and 9 inclusive.
    249        *
    250        * @return {@code true} if the message priority was changed
    251        */
    252       @Operation(desc = "Change the priority of the message corresponding to the given messageID", impact = MBeanOperationInfo.ACTION)
    253       boolean changeMessagePriority(@Parameter(name = "messageID", desc = "A message ID") long messageID,
    254                                     @Parameter(name = "newPriority", desc = "the new priority (between 0 and 9)") int newPriority) throws Exception;
    255
    256       /**
    257        * Changes the priority for all the message corresponding to the specified filter to the specified priority.
    258        * <br>
    259        * Using {@code null} or an empty filter will change <em>all</em> messages from this queue.
    260        *
    261        * @return the number of changed messages
    262        */
    263       @Operation(desc = "Change the priority of the messages corresponding to the given filter", impact = MBeanOperationInfo.ACTION)
    264       int changeMessagesPriority(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filter,
    265                                  @Parameter(name = "newPriority", desc = "the new priority (between 0 and 9)") int newPriority) throws Exception;
    266
    267       /**
    268        * Lists the message counter for this queue.
    269        */
    270       @Operation(desc = "List the message counters", impact = MBeanOperationInfo.INFO)
    271       String listMessageCounter() throws Exception;
    272
    273       /**
    274        * Resets the message counter for this queue.
    275        */
    276       @Operation(desc = "Reset the message counters", impact = MBeanOperationInfo.INFO)
    277       void resetMessageCounter() throws Exception;
    278
    279       /**
    280        * Lists the message counter for this queue as a HTML table.
    281        */
    282       @Operation(desc = "List the message counters as HTML", impact = MBeanOperationInfo.INFO)
    283       String listMessageCounterAsHTML() throws Exception;
    284
    285       /**
    286        * Lists the message counter history for this queue.
    287        */
    288       @Operation(desc = "List the message counters history", impact = MBeanOperationInfo.INFO)
    289       String listMessageCounterHistory() throws Exception;
    290
    291       /**
    292        * Lists the message counter history for this queue as a HTML table.
    293        */
    294       @Operation(desc = "List the message counters history HTML", impact = MBeanOperationInfo.INFO)
    295       String listMessageCounterHistoryAsHTML() throws Exception;
    296
    297       /**
    298        * Pauses the queue. Messages are no longer delivered to its consumers.
    299        */
    300       @Operation(desc = "Pauses the Queue", impact = MBeanOperationInfo.ACTION)
    301       void pause() throws Exception;
    302
    303       /**
    304        * Resumes the queue. Messages are again delivered to its consumers.
    305        */
    306       @Operation(desc = "Resumes delivery of queued messages and gets the queue out of paused state.", impact = MBeanOperationInfo.ACTION)
    307       void resume() throws Exception;
    308
    309       @Operation(desc = "List all the existent consumers on the Queue")
    310       String listConsumersAsJSON() throws Exception;
    311
    312       /**
    313        * Returns whether the queue is paused.
    314        */
    315       @Operation(desc = "Inspects if the queue is paused", impact = MBeanOperationInfo.INFO)
    316       boolean isPaused() throws Exception;
    317    }