/** 
 * 
 * Copyright 2004 Protique Ltd
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); 
 * you may not use this file except in compliance with the License. 
 * You may obtain a copy of the License at 
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, 
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
 * See the License for the specific language governing permissions and 
 * limitations under the License. 
 * 
 **/
package org.codehaus.activemq.service;

import org.codehaus.activemq.message.ActiveMQMessage;

import javax.jms.JMSException;

/**
 * A Queue based {@link MessageContainer}
 *
 * @version $Revision: 1.2 $
 */
public interface QueueMessageContainer extends MessageContainer {

    /**
     * Some implementations may need to poll to fill subscriptions
     * this returns the next message in the container
     *
     * @return the next message
     * @throws javax.jms.JMSException
     */
    public ActiveMQMessage poll() throws JMSException;

    /**
     * Used for browsing a MessageContainer
     * this returns the next message in the container after the messageId
     *
     * @param messageIdentity the id if the message. If this is null, the first message will be retrieved
     * @return the next message without updating it's state to being dispatched
     * @throws JMSException
     */

    public ActiveMQMessage peekNext(MessageIdentity messageIdentity) throws JMSException;

    /**
     * After a poll() on the Container, if a message can't be dispatched, it is returned
     *
     * @param messageIdentity
     * @throws JMSException
     */
    public void returnMessage(MessageIdentity messageIdentity) throws JMSException;

    /**
     * called to reset dispatch pointers if a new Message Consumer joins
     *
     * @throws JMSException
     */
    public void reset() throws JMSException;

    /**
     * This container has just been loaded from disk and so it needs to be recovered,
     * that is iterate through all the message IDs in the persistent store and
     * add them to the in memory list of message IDs to be dispatched by consumers
     */
    public void start() throws JMSException;


    /**
     * Invoked during the recovery to add the given message to the end of
     * the messages to be delivered.
     */
    public void recoverMessageToBeDelivered(MessageIdentity messageIdentity) throws JMSException;
    
    
    /**
     * set this MessageContainer to be a dead letter queue
     * @param value
     */
    public void setDeadLetterQueue(boolean value);
}
