001    /** 
002     * 
003     * Copyright 2004 Protique Ltd
004     * 
005     * Licensed under the Apache License, Version 2.0 (the "License"); 
006     * you may not use this file except in compliance with the License. 
007     * 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     * 
017     **/
018    package org.activemq.service;
019    
020    import org.activemq.message.ActiveMQMessage;
021    
022    import javax.jms.JMSException;
023    
024    /**
025     * A Queue based {@link MessageContainer}
026     *
027     * @version $Revision: 1.1.1.1 $
028     */
029    public interface QueueMessageContainer extends MessageContainer {
030    
031        /**
032         * Some implementations may need to poll to fill subscriptions
033         * this returns the next message in the container
034         *
035         * @return the next message
036         * @throws javax.jms.JMSException
037         */
038        public ActiveMQMessage poll() throws JMSException;
039    
040        /**
041         * Used for browsing a MessageContainer
042         * this returns the next message in the container after the messageId
043         *
044         * @param messageIdentity the id if the message. If this is null, the first message will be retrieved
045         * @return the next message without updating it's state to being dispatched
046         * @throws JMSException
047         */
048    
049        public ActiveMQMessage peekNext(MessageIdentity messageIdentity) throws JMSException;
050    
051        /**
052         * After a poll() on the Container, if a message can't be dispatched, it is returned
053         *
054         * @param messageIdentity
055         * @throws JMSException
056         */
057        public void returnMessage(MessageIdentity messageIdentity) throws JMSException;
058    
059        /**
060         * called to reset dispatch pointers if a new Message Consumer joins
061         *
062         * @throws JMSException
063         */
064        public void reset() throws JMSException;
065    
066        /**
067         * This container has just been loaded from disk and so it needs to be recovered,
068         * that is iterate through all the message IDs in the persistent store and
069         * add them to the in memory list of message IDs to be dispatched by consumers
070         */
071        public void start() throws JMSException;
072    
073    
074        /**
075         * Invoked during the recovery to add the given message to the end of
076         * the messages to be delivered.
077         */
078        public void recoverMessageToBeDelivered(MessageIdentity messageIdentity) throws JMSException;
079        
080        
081        /**
082         * set this MessageContainer to be a dead letter queue
083         * @param value
084         */
085        public void setDeadLetterQueue(boolean value);
086    }