001/**
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.activemq.broker.jmx;
018
019import javax.management.openmbean.CompositeData;
020import javax.management.openmbean.OpenDataException;
021
022public interface QueueViewMBean extends DestinationViewMBean {
023
024    /**
025     * Retrieve a message from the destination's queue.
026     * 
027     * @param messageId the message id of the message to retrieve
028     * @return A CompositeData object which is a JMX version of the messages
029     * @throws OpenDataException
030     */
031    @MBeanInfo("View a message from the destination by JMS message ID.")
032    CompositeData getMessage(@MBeanInfo("messageId") String messageId) throws OpenDataException;
033
034    /**
035     * Removes a message from the queue. If the message has already been
036     * dispatched to another consumer, the message cannot be deleted and this
037     * method will return false.
038     * 
039     * @param messageId
040     * @return true if the message was found and could be successfully deleted.
041     * @throws Exception
042     */
043    @MBeanInfo("Remove a message from the destination by JMS message ID.  If the message has been dispatched, it cannot be deleted and false is returned.")
044    boolean removeMessage(@MBeanInfo("messageId") String messageId) throws Exception;
045
046    /**
047     * Removes the messages matching the given selector
048     * 
049     * @return the number of messages removed
050     */
051    @MBeanInfo("Removes messages from the destination based on an SQL-92 selection on the message headers or XPATH on the body.")
052    int removeMatchingMessages(@MBeanInfo("selector") String selector) throws Exception;
053
054    /**
055     * Removes the messages matching the given selector up to the maximum number
056     * of matched messages
057     * 
058     * @return the number of messages removed
059     */
060    @MBeanInfo("Removes up to a specified number of messages from the destination based on an SQL-92 selection on the message headers or XPATH on the body.")
061    int removeMatchingMessages(@MBeanInfo("selector") String selector, @MBeanInfo("maximumMessages") int maximumMessages) throws Exception;
062
063    /**
064     * Removes all of the messages in the queue.
065     * 
066     * @throws Exception
067     */
068    @MBeanInfo("Removes all of the messages in the queue.")
069    void purge() throws Exception;
070
071    /**
072     * Copies a given message to another destination.
073     * 
074     * @param messageId
075     * @param destinationName
076     * @return true if the message was found and was successfully copied to the
077     *         other destination.
078     * @throws Exception
079     */
080    @MBeanInfo("Copies a message with the given JMS message ID into the specified destination.")
081    boolean copyMessageTo(@MBeanInfo("messageId") String messageId, @MBeanInfo("destinationName") String destinationName) throws Exception;
082
083    /**
084     * Copies the messages matching the given selector
085     * 
086     * @return the number of messages copied
087     */
088    @MBeanInfo("Copies messages based on an SQL-92 selecton on the message headers or XPATH on the body into the specified destination.")
089    int copyMatchingMessagesTo(@MBeanInfo("selector") String selector, @MBeanInfo("destinationName") String destinationName) throws Exception;
090
091    /**
092     * Copies the messages matching the given selector up to the maximum number
093     * of matched messages
094     * 
095     * @return the number of messages copied
096     */
097    @MBeanInfo("Copies up to a specified number of messages based on an SQL-92 selecton on the message headers or XPATH on the body into the specified destination.")
098    int copyMatchingMessagesTo(@MBeanInfo("selector") String selector, @MBeanInfo("destinationName") String destinationName, @MBeanInfo("maximumMessages") int maximumMessages) throws Exception;
099
100    /**
101     * Moves the message to another destination.
102     * 
103     * @param messageId
104     * @param destinationName
105     * @return true if the message was found and was successfully copied to the
106     *         other destination.
107     * @throws Exception
108     */
109    @MBeanInfo("Moves a message with the given JMS message ID into the specified destination.")
110    boolean moveMessageTo(@MBeanInfo("messageId") String messageId, @MBeanInfo("destinationName") String destinationName) throws Exception;
111
112    /**
113     * Moves a message back to its original destination
114     */
115    @MBeanInfo("Moves a message with the given JMS message back to its original destination")
116    boolean retryMessage(@MBeanInfo("messageId") String messageId) throws Exception;
117    
118    /**
119     * Moves the messages matching the given selector
120     * 
121     * @return the number of messages removed
122     */
123    @MBeanInfo("Moves messages based on an SQL-92 selecton on the message headers or XPATH on the body into the specified destination.")
124    int moveMatchingMessagesTo(@MBeanInfo("selector") String selector, @MBeanInfo("destinationName") String destinationName) throws Exception;
125
126    /**
127     * Moves the messages matching the given selector up to the maximum number
128     * of matched messages
129     */
130    @MBeanInfo("Moves up to a specified number of messages based on an SQL-92 selecton on the message headers or XPATH on the body into the specified destination.")
131    int moveMatchingMessagesTo(@MBeanInfo("selector") String selector, @MBeanInfo("destinationName") String destinationName, @MBeanInfo("maximumMessages") int maximumMessages) throws Exception;
132    
133    /**
134     * @return true if the message cursor has memory space available
135     * to page in more messages
136     */
137    @MBeanInfo("Message cursor has memory space available")
138    public boolean doesCursorHaveSpace();
139    
140    /**
141     * @return true if the cursor has reached its memory limit for
142     * paged in messages
143     */
144    @MBeanInfo("Message cusor has reached its memory limit for paged in messages")
145    public boolean isCursorFull();
146    
147    /**
148     * @return true if the cursor has messages buffered to deliver
149     */
150    @MBeanInfo("Message cursor has buffered messages to deliver")
151    public boolean doesCursorHaveMessagesBuffered();
152    
153    /**
154     * @return the cursor memory usage in bytes
155     */
156    @MBeanInfo("Message cursor memory usage, in bytes.")
157    public long getCursorMemoryUsage();
158    
159    /**
160     * @return the cursor memory usage as a percentage
161     */
162    @MBeanInfo("Percentage of memory limit used")
163    public int getCursorPercentUsage();
164    
165    /**
166     * @return the number of messages available to be paged in 
167     * by the cursor
168     */
169    @MBeanInfo("Number of messages available to be paged in by the cursor.")
170    public int cursorSize();
171
172    /**
173     * @return true if caching is currently enabled of for the destination
174     */
175    @MBeanInfo("Caching is enabled")
176    boolean isCacheEnabled();
177}