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 javax.jms.JMSException;
021    
022    /**
023     * Represents a Queue with List like semantics, allowing addition and removal at
024     * any point in the queue. Typically this will be implemented using some kind of LinkedList
025     *
026     * @version $Revision: 1.1.1.1 $
027     */
028    public interface QueueList {
029        Object[] EMPTY_ARRAY = {};
030    
031        /**
032         * Returns the first element in this list.
033         *
034         * @return the first element in this list.
035         */
036        Object getFirst() throws JMSException;
037    
038        /**
039         * Returns the last element in this list.
040         *
041         * @return the last element in this list.
042         */
043        Object getLast() throws JMSException;
044    
045        /**
046         * Removes and returns the first element from this list.
047         *
048         * @return the first element from this list.
049         */
050        Object removeFirst() throws JMSException;
051    
052        /**
053         * Move the head of the list to the back of the list
054         */
055    
056        void rotate() throws JMSException;
057    
058        /**
059         * Removes and returns the last element from this list.
060         *
061         * @return the last element from this list.
062         */
063        Object removeLast() throws JMSException;
064    
065        /**
066         * Inserts the given element at the beginning of this list.
067         *
068         * @param o the element to be inserted at the beginning of this list.
069         * @return the DefaultQueueListEntry
070         */
071        QueueListEntry addFirst(Object o) throws JMSException;
072    
073        /**
074         * Appends the given element to the end of this list. (Identical in function to the <tt>add</tt> method; included
075         * only for consistency.)
076         *
077         * @param o the element to be inserted at the end of this list.
078         * @return the DefaultQueueListEntry
079         */
080        QueueListEntry addLast(Object o) throws JMSException;
081    
082        /**
083         * Returns <tt>true</tt> if this list contains the specified element. More formally, returns <tt>true</tt> if
084         * and only if this list contains at least one element <tt>e</tt> such that <tt>(o==null ? e==null
085         * : o.equals(e))</tt>.
086         *
087         * @param o element whose presence in this list is to be tested.
088         * @return <tt>true</tt> if this list contains the specified element.
089         */
090        boolean contains(Object o) throws JMSException;
091    
092        /**
093         * Returns the number of elements in this list.
094         *
095         * @return the number of elements in this list.
096         */
097        int size() throws JMSException;
098    
099        /**
100         * is the list empty?
101         *
102         * @return true if there are no elements in the list
103         */
104        boolean isEmpty() throws JMSException;
105    
106        /**
107         * Appends the specified element to the end of this list.
108         *
109         * @param o element to be appended to this list.
110         * @return the DefaultQueueListEntry
111         */
112        QueueListEntry add(Object o) throws JMSException;
113    
114        /**
115         * Removes the first occurrence of the specified element in this list. If the list does not contain the element, it
116         * is unchanged. More formally, removes the element with the lowest index <tt>i</tt> such that <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>
117         * (if such an element exists).
118         *
119         * @param o element to be removed from this list, if present.
120         * @return <tt>true</tt> if the list contained the specified element.
121         */
122        boolean remove(Object o) throws JMSException;
123    
124        /**
125         * Removes all of the elements from this list.
126         */
127        void clear() throws JMSException;
128    
129        /**
130         * Returns the element at the specified position in this list.
131         *
132         * @param index index of element to return.
133         * @return the element at the specified position in this list.
134         * @throws IndexOutOfBoundsException if the specified index is is out of range (<tt>index &lt; 0 || index &gt;= size()</tt>).
135         */
136        Object get(int index) throws JMSException;
137    
138        /**
139         * Replaces the element at the specified position in this list with the specified element.
140         *
141         * @param index   index of element to replace.
142         * @param element element to be stored at the specified position.
143         * @return the element previously at the specified position.
144         * @throws IndexOutOfBoundsException if the specified index is out of range (<tt>index &lt; 0 || index &gt;= size()</tt>).
145         */
146        Object set(int index, Object element) throws JMSException;
147    
148        /**
149         * Inserts the specified element at the specified position in this list. Shifts the element currently at that
150         * position (if any) and any subsequent elements to the right (adds one to their indices).
151         *
152         * @param index   index at which the specified element is to be inserted.
153         * @param element element to be inserted.
154         * @throws IndexOutOfBoundsException if the specified index is out of range (<tt>index &lt; 0 || index &gt; size()</tt>).
155         */
156        void add(int index, Object element) throws JMSException;
157    
158        /**
159         * Removes the element at the specified position in this list. Shifts any subsequent elements to the left
160         * (subtracts one from their indices). Returns the element that was removed from the list.
161         *
162         * @param index the index of the element to removed.
163         * @return the element previously at the specified position.
164         * @throws IndexOutOfBoundsException if the specified index is out of range (<tt>index &lt; 0 || index &gt;= size()</tt>).
165         */
166        Object remove(int index) throws JMSException;
167    
168        /**
169         * Returns the index in this list of the first occurrence of the specified element, or -1 if the List does not
170         * contain this element. More formally, returns the lowest index i such that <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,
171         * or -1 if there is no such index.
172         *
173         * @param o element to search for.
174         * @return the index in this list of the first occurrence of the specified element, or -1 if the list does not
175         *         contain this element.
176         */
177        int indexOf(Object o) throws JMSException;
178    
179        /**
180         * Returns the index in this list of the last occurrence of the specified element, or -1 if the list does not
181         * contain this element. More formally, returns the highest index i such that <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,
182         * or -1 if there is no such index.
183         *
184         * @param o element to search for.
185         * @return the index in this list of the last occurrence of the specified element, or -1 if the list does not
186         *         contain this element.
187         */
188        int lastIndexOf(Object o) throws JMSException;
189    
190        /**
191         * Retrieve the first entry for the linked list
192         *
193         * @return first entry or null
194         */
195        QueueListEntry getFirstEntry() throws JMSException;
196    
197        /**
198         * Retrieve the last entry for the linked list
199         *
200         * @return last entry or null
201         */
202        QueueListEntry getLastEntry() throws JMSException;
203    
204        /**
205         * Retrieve the next entry after this entry
206         *
207         * @param node
208         * @return
209         */
210        QueueListEntry getNextEntry(QueueListEntry node) throws JMSException;
211    
212        /**
213         * Retrive the previous entry after this entry
214         *
215         * @param node
216         * @return
217         */
218        QueueListEntry getPrevEntry(QueueListEntry node) throws JMSException;
219    
220        /**
221         * Insert an Entry before this entry
222         *
223         * @param o    the elment to insert
224         * @param node the Entry to insert the object before
225         * @return
226         */
227        QueueListEntry addBefore(Object o, QueueListEntry node) throws JMSException;
228    
229        /**
230         * Remove a DefaultQueueListEntry
231         *
232         * @param node the DefaultQueueListEntry
233         */
234        void remove(QueueListEntry node) throws JMSException;
235    
236        /**
237         * Returns an array containing all of the elements in this list in the correct order.
238         *
239         * @return an array containing all of the elements in this list in the correct order.
240         */
241        Object[] toArray() throws JMSException;
242    
243    }