1 /***
2 *
3 * Copyright 2004 Protique Ltd
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 **/
18 package org.codehaus.activemq.service;
19
20 import javax.jms.JMSException;
21
22 /***
23 * Represents a Queue with List like semantics, allowing addition and removal at
24 * any point in the queue. Typically this will be implemented using some kind of LinkedList
25 *
26 * @version $Revision: 1.4 $
27 */
28 public interface QueueList {
29 Object[] EMPTY_ARRAY = {};
30
31 /***
32 * Returns the first element in this list.
33 *
34 * @return the first element in this list.
35 */
36 Object getFirst() throws JMSException;
37
38 /***
39 * Returns the last element in this list.
40 *
41 * @return the last element in this list.
42 */
43 Object getLast() throws JMSException;
44
45 /***
46 * Removes and returns the first element from this list.
47 *
48 * @return the first element from this list.
49 */
50 Object removeFirst() throws JMSException;
51
52 /***
53 * Move the head of the list to the back of the list
54 */
55
56 void rotate() throws JMSException;
57
58 /***
59 * Removes and returns the last element from this list.
60 *
61 * @return the last element from this list.
62 */
63 Object removeLast() throws JMSException;
64
65 /***
66 * Inserts the given element at the beginning of this list.
67 *
68 * @param o the element to be inserted at the beginning of this list.
69 * @return the DefaultQueueListEntry
70 */
71 QueueListEntry addFirst(Object o) throws JMSException;
72
73 /***
74 * Appends the given element to the end of this list. (Identical in function to the <tt>add</tt> method; included
75 * only for consistency.)
76 *
77 * @param o the element to be inserted at the end of this list.
78 * @return the DefaultQueueListEntry
79 */
80 QueueListEntry addLast(Object o) throws JMSException;
81
82 /***
83 * Returns <tt>true</tt> if this list contains the specified element. More formally, returns <tt>true</tt> if
84 * and only if this list contains at least one element <tt>e</tt> such that <tt>(o==null ? e==null
85 * : o.equals(e))</tt>.
86 *
87 * @param o element whose presence in this list is to be tested.
88 * @return <tt>true</tt> if this list contains the specified element.
89 */
90 boolean contains(Object o) throws JMSException;
91
92 /***
93 * Returns the number of elements in this list.
94 *
95 * @return the number of elements in this list.
96 */
97 int size() throws JMSException;
98
99 /***
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 }