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
014package org.hornetq.api.core.management;
015
016import java.util.Map;
017
018import 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 */
026public 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}