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     */
017    package org.apache.activemq.broker.region.cursors;
018    
019    import java.util.Collection;
020    import java.util.Iterator;
021    
022    import org.apache.activemq.broker.region.MessageReference;
023    
024    public interface PendingList extends Iterable<MessageReference> {
025    
026        /**
027         * Returns true if there are no Messages in the PendingList currently.
028         * @return true if the PendingList is currently empty.
029         */
030        public boolean isEmpty();
031    
032        /**
033         * Discards all Messages currently held in the PendingList.
034         */
035        public void clear();
036    
037        /**
038         * Adds the given message to the head of the list.
039         *
040         * @param message
041         *      The MessageReference that is to be added to this list.
042         *
043         * @return the PendingNode that contains the newly added message.
044         */
045        public PendingNode addMessageFirst(MessageReference message);
046    
047        /**
048         * Adds the given message to the tail of the list.
049         *
050         * @param message
051         *      The MessageReference that is to be added to this list.
052         *
053         * @return the PendingNode that contains the newly added message.
054         */
055        public PendingNode addMessageLast(MessageReference message);
056    
057        /**
058         * Removes the given MessageReference from the PendingList if it is
059         * contained within.
060         *
061         * @param message
062         *      The MessageReference that is to be removed to this list.
063         *
064         * @return the PendingNode that contains the removed message or null if the
065         *         message was not present in this list.
066         */
067        public PendingNode remove(MessageReference message);
068    
069        /**
070         * Returns the number of MessageReferences that are awaiting dispatch.
071         * @return current count of the pending messages.
072         */
073        public int size();
074    
075        /**
076         * Returns an iterator over the pending Messages.  The subclass controls how
077         * the returned iterator actually traverses the list of pending messages allowing
078         * for the order to vary based on factors like Message priority or some other
079         * mechanism.
080         *
081         * @return an Iterator that returns MessageReferences contained in this list.
082         */
083        public Iterator<MessageReference> iterator();
084    
085        /**
086         * Query the PendingList to determine if the given message is contained within.
087         *
088         * @param message
089         *      The Message that is the target of this query.
090         *
091         * @return true if the MessageReference is contained in this list.
092         */
093        public boolean contains(MessageReference message);
094    
095        /**
096         * Returns a new Collection that contains all the MessageReferences currently
097         * held in this PendingList.  The elements of the list are ordered using the
098         * same rules as the subclass uses for iteration.
099         *
100         * @return a new Collection containing this lists MessageReferences.
101         */
102        public Collection<MessageReference> values();
103    
104        /**
105         * Adds all the elements of the given PendingList to this PendingList.
106         *
107         * @param pendingList
108         *      The PendingList that is to be added to this collection.
109         */
110        public void addAll(PendingList pendingList);
111    }