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.jms.management;
015    
016    import java.util.List;
017    import java.util.Map;
018    
019    import javax.management.MBeanOperationInfo;
020    
021    import org.hornetq.api.core.management.Operation;
022    import org.hornetq.api.core.management.Parameter;
023    
024    /**
025     * A JMSQueueControl is used to manage a JMS queue.
026     * 
027     * @author <a href="mailto:jmesnil@redhat.com">Jeff Mesnil</a>
028     */
029    public interface JMSQueueControl extends DestinationControl
030    {
031       // Attributes ----------------------------------------------------
032    
033       /**
034        * Returns the expiry address associated to this queue.
035        */
036       String getExpiryAddress();
037    
038       /**
039        * Sets the expiry address associated to this queue to the specified expiryAddress.
040        */
041       void setExpiryAddress(@Parameter(name = "expiryAddress", desc = "Expiry address of the queue") String expiryAddress) throws Exception;
042    
043       /**
044        * Returns the dead-letter address associated to this queue.
045        */
046       String getDeadLetterAddress();
047    
048       /**
049        * Sets the dead-letter address associated to this queue to the specified deadLetterAddress.
050        */
051       void setDeadLetterAddress(@Parameter(name = "deadLetterAddress", desc = "Dead-letter address of the queue") String deadLetterAddress) throws Exception;
052    
053       /**
054        * Returns the number of messages added to this queue since it was created.
055        */
056       long getMessagesAdded();
057    
058       /**
059        * Returns the number of scheduled messages in this queue.
060        */
061       long getScheduledCount();
062    
063       /**
064        * Returns the number of consumers consuming messages from this queue.
065        */
066       int getConsumerCount();
067    
068       /**
069        * Returns the number of messages that this queue is currently delivering to its consumers.
070        */
071       int getDeliveringCount();
072    
073       /**
074        * returns the selector for the queue
075        */
076       String getSelector();
077    
078       // Operations ----------------------------------------------------
079    
080       /**
081        * Returns the JNDI bindings associated  to this connection factory.
082        */
083       @Operation(desc = "Returns the list of JNDI bindings associated")
084       String[] getJNDIBindings();
085       
086       /**
087        * Add the JNDI binding to this destination
088        */
089       @Operation(desc = "Adds the queue to another JNDI binding")
090       void addJNDI(@Parameter(name = "jndiBinding", desc = "the name of the binding for JNDI") String jndi) throws Exception;
091    
092       /**
093        * Lists all the JMS messages in this queue matching the specified filter.
094        * <br>
095        * 1 Map represents 1 message, keys are the message's properties and headers, values are the corresponding values.
096        * <br>
097        * Using {@code null} or an empty filter will list <em>all</em> messages from this queue.
098        */
099       @Operation(desc = "List all messages in the queue which matches the filter", impact = MBeanOperationInfo.INFO)
100       Map<String, Object>[] listMessages(@Parameter(name = "filter", desc = "A JMS Message filter") String filter) throws Exception;
101    
102       /**
103        * Lists all the JMS messages in this queue matching the specified filter using JSON serialization.
104        * <br>
105        * Using {@code null} or an empty filter will list <em>all</em> messages from this queue.
106        */
107       @Operation(desc = "List all messages in the queue which matches the filter and return them using JSON", impact = MBeanOperationInfo.INFO)
108       String listMessagesAsJSON(@Parameter(name = "filter", desc = "A JMS Message filter (can be empty)") String filter) throws Exception;
109    
110       /**
111        * Counts the number of messages in this queue matching the specified filter.
112        * <br>
113        * Using {@code null} or an empty filter will count <em>all</em> messages from this queue.
114        */
115       @Operation(desc = "Returns the number of the messages in the queue matching the given filter", impact = MBeanOperationInfo.INFO)
116       int countMessages(@Parameter(name = "filter", desc = "A JMS message filter (can be empty)") String filter) throws Exception;
117    
118       /**
119        * Removes the message corresponding to the specified message ID.
120        *
121        * @return {@code true} if the message was removed, {@code false} else
122        */
123       @Operation(desc = "Remove the message corresponding to the given messageID", impact = MBeanOperationInfo.ACTION)
124       boolean removeMessage(@Parameter(name = "messageID", desc = "A message ID") String messageID) throws Exception;
125    
126       /**
127        * Removes all the message corresponding to the specified filter.
128        * <br>
129        * Using {@code null} or an empty filter will remove <em>all</em> messages from this queue.
130        * 
131        * @return the number of removed messages
132        */
133       @Operation(desc = "Remove the messages corresponding to the given filter (and returns the number of removed messages)", impact = MBeanOperationInfo.ACTION)
134       int removeMessages(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filter) throws Exception;
135    
136       /**
137        * Expires all the message corresponding to the specified filter.
138        * <br>
139        * Using {@code null} or an empty filter will expire <em>all</em> messages from this queue.
140        * 
141        * @return the number of expired messages
142        */
143       @Operation(desc = "Expire the messages corresponding to the given filter (and returns the number of expired messages)", impact = MBeanOperationInfo.ACTION)
144       int expireMessages(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filter) throws Exception;
145    
146       /**
147        * Expires the message corresponding to the specified message ID.
148        *
149        * @return {@code true} if the message was expired, {@code false} else
150        */
151       @Operation(desc = "Expire the message corresponding to the given messageID", impact = MBeanOperationInfo.ACTION)
152       boolean expireMessage(@Parameter(name = "messageID", desc = "A message ID") String messageID) throws Exception;
153    
154       /**
155        * Sends the message corresponding to the specified message ID to this queue's dead letter address.
156        *
157        * @return {@code true} if the message was sent to the dead letter address, {@code false} else
158        */
159       @Operation(desc = "Send the message corresponding to the given messageID to this queue's Dead Letter Address", impact = MBeanOperationInfo.ACTION)
160       boolean sendMessageToDeadLetterAddress(@Parameter(name = "messageID", desc = "A message ID") String messageID) throws Exception;
161    
162       /**
163        * Sends all the message corresponding to the specified filter to this queue's dead letter address.
164        * <br>
165        * Using {@code null} or an empty filter will send <em>all</em> messages from this queue.
166        * 
167        * @return the number of sent messages
168        */
169       @Operation(desc = "Send the messages corresponding to the given filter to this queue's Dead Letter Address", impact = MBeanOperationInfo.ACTION)
170       int sendMessagesToDeadLetterAddress(@Parameter(name = "filter", desc = "A message filter (can be empty)") String filterStr) throws Exception;
171    
172       /**
173        * Changes the message's priority corresponding to the specified message ID to the specified priority.
174        * 
175        * @param newPriority between 0 and 9 inclusive.
176        *
177        * @return {@code true} if the message priority was changed
178        */
179       @Operation(desc = "Change the priority of the message corresponding to the given messageID", impact = MBeanOperationInfo.ACTION)
180       boolean changeMessagePriority(@Parameter(name = "messageID", desc = "A message ID") String messageID,
181                                     @Parameter(name = "newPriority", desc = "the new priority (between 0 and 9)") int newPriority) throws Exception;
182    
183       /**
184        * Changes the priority for all the message corresponding to the specified filter to the specified priority.
185        * <br>
186        * Using {@code null} or an empty filter will change <em>all</em> messages from this queue.
187        * 
188        * @return the number of changed messages
189        */
190       @Operation(desc = "Change the priority of the messages corresponding to the given filter", impact = MBeanOperationInfo.ACTION)
191       int changeMessagesPriority(@Parameter(name = "filter", desc = "A message filter") String filter,
192                                  @Parameter(name = "newPriority", desc = "the new priority (between 0 and 9)") int newPriority) throws Exception;
193    
194       /**
195        * Moves the message corresponding to the specified message ID to the specified other queue.
196        *
197        * @return {@code true} if the message was moved, {@code false} else
198        */
199       @Operation(desc = "Move the message corresponding to the given messageID to another queue", impact = MBeanOperationInfo.ACTION)
200       boolean moveMessage(@Parameter(name = "messageID", desc = "A message ID") String messageID,
201                           @Parameter(name = "otherQueueName", desc = "The name of the queue to move the message to") String otherQueueName) throws Exception;
202    
203       /**
204        * Moves all the message corresponding to the specified filter  to the specified other queue.
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)", 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        * Lists the message counter for this queue.
216        */
217       @Operation(desc = "List the message counters", impact = MBeanOperationInfo.INFO)
218       String listMessageCounter() throws Exception;
219    
220       /**
221        * Resets the message counter for this queue.
222        */
223       @Operation(desc = "Reset the message counters", impact = MBeanOperationInfo.INFO)
224       void resetMessageCounter() throws Exception;
225    
226    
227       /**
228        * Lists the message counter for this queue as a HTML table.
229        */
230       @Operation(desc = "List the message counters as HTML", impact = MBeanOperationInfo.INFO)
231       String listMessageCounterAsHTML() throws Exception;
232    
233       /**
234        * Lists the message counter history for this queue.
235        */
236       @Operation(desc = "List the message counters history", impact = MBeanOperationInfo.INFO)
237       String listMessageCounterHistory() throws Exception;
238    
239       /**
240        * Lists the message counter history for this queue as a HTML table.
241        */
242       @Operation(desc = "List the message counters history as HTML", impact = MBeanOperationInfo.INFO)
243       String listMessageCounterHistoryAsHTML() throws Exception;
244    
245       /**
246        * Pauses the queue. Messages are no longer delivered to its consumers.
247        */
248       @Operation(desc = "Pause the queue.", impact = MBeanOperationInfo.ACTION)
249       void pause() throws Exception;
250    
251       /**
252        * Returns whether the queue is paused.
253        */
254       @Operation(desc = "Returns true if the queue is paused.", impact = MBeanOperationInfo.INFO)
255       boolean isPaused() throws Exception;
256    
257       /**
258        * Resumes the queue. Messages are again delivered to its consumers.
259        */
260       @Operation(desc = "Resume the queue.", impact = MBeanOperationInfo.ACTION)
261       void resume() throws Exception;
262    
263    }