View Javadoc

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 &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 }