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 }