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 }