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 < 0 || index >= 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 < 0 || index >= 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 < 0 || index > 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 < 0 || index >= 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 }