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 }