001    /**
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  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    package org.apache.activemq.kaha.impl.index;
018    
019    import org.apache.activemq.kaha.StoreEntry;
020    
021    /**
022     * Inteface to LinkedList of Indexes
023     * 
024     * 
025     */
026    public interface IndexLinkedList {
027        
028        /**
029         * Set the new Root
030         * @param newRoot
031         */
032        void setRoot(IndexItem newRoot);
033    
034        /**
035         * @return the root used by the List
036         */
037        IndexItem getRoot();
038    
039        /**
040         * Returns the first element in this list.
041         * 
042         * @return the first element in this list.
043         */
044        IndexItem getFirst();
045    
046        /**
047         * Returns the last element in this list.
048         * 
049         * @return the last element in this list.
050         */
051        IndexItem getLast();
052    
053        /**
054         * Removes and returns the first element from this list.
055         * 
056         * @return the first element from this list.
057         */
058        StoreEntry removeFirst();
059    
060        /**
061         * Removes and returns the last element from this list.
062         * 
063         * @return the last element from this list.
064         */
065        Object removeLast();
066    
067        /**
068         * Inserts the given element at the beginning of this list.
069         * 
070         * @param item
071         */
072        void addFirst(IndexItem item);
073    
074        /**
075         * Appends the given element to the end of this list. (Identical in function
076         * to the <tt>add</tt> method; included only for consistency.)
077         * 
078         * @param item
079         */
080        void addLast(IndexItem item);
081    
082        /**
083         * Returns the number of elements in this list.
084         * 
085         * @return the number of elements in this list.
086         */
087        int size();
088    
089        /**
090         * is the list empty?
091         * 
092         * @return true if there are no elements in the list
093         */
094        boolean isEmpty();
095    
096        /**
097         * Appends the specified element to the end of this list.
098         * 
099         * @param item
100         * 
101         * @return <tt>true</tt> (as per the general contract of
102         *         <tt>Collection.add</tt>).
103         */
104        boolean add(IndexItem item);
105    
106        /**
107         * Removes all of the elements from this list.
108         */
109        void clear();
110    
111        // Positional Access Operations
112        /**
113         * Returns the element at the specified position in this list.
114         * 
115         * @param index index of element to return.
116         * @return the element at the specified position in this list.
117         * 
118         * @throws IndexOutOfBoundsException if the specified index is is out of
119         *                 range (<tt>index &lt; 0 || index &gt;= size()</tt>).
120         */
121        IndexItem get(int index);
122    
123        /**
124         * Inserts the specified element at the specified position in this list.
125         * Shifts the element currently at that position (if any) and any subsequent
126         * elements to the right (adds one to their indices).
127         * 
128         * @param index index at which the specified element is to be inserted.
129         * @param element element to be inserted.
130         * 
131         * @throws IndexOutOfBoundsException if the specified index is out of range (<tt>index &lt; 0 || index &gt; size()</tt>).
132         */
133        void add(int index, IndexItem element);
134    
135        /**
136         * Removes the element at the specified position in this list. Shifts any
137         * subsequent elements to the left (subtracts one from their indices).
138         * Returns the element that was removed from the list.
139         * 
140         * @param index the index of the element to removed.
141         * @return the element previously at the specified position.
142         * 
143         * @throws IndexOutOfBoundsException if the specified index is out of range (<tt>index &lt; 0 || index &gt;= size()</tt>).
144         */
145        Object remove(int index);
146    
147        // Search Operations
148        /**
149         * Returns the index in this list of the first occurrence of the specified
150         * element, or -1 if the List does not contain this element. More formally,
151         * returns the lowest index i such that
152         * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>, or -1 if there
153         * is no such index.
154         * 
155         * @param o element to search for.
156         * @return the index in this list of the first occurrence of the specified
157         *         element, or -1 if the list does not contain this element.
158         */
159        int indexOf(StoreEntry o);
160    
161        /**
162         * Retrieve the next entry after this entry
163         * 
164         * @param entry
165         * @return next entry
166         */
167        IndexItem getNextEntry(IndexItem entry);
168    
169        /**
170         * Retrive the prev entry after this entry
171         * 
172         * @param entry
173         * @return prev entry
174         */
175        IndexItem getPrevEntry(IndexItem entry);
176    
177        /**
178         * remove an entry
179         * 
180         * @param e
181         */
182        void remove(IndexItem e);
183    
184        /**
185         * Ensure we have the up to date entry
186         * 
187         * @param entry
188         * @return the entry
189         */
190        StoreEntry getEntry(StoreEntry entry);
191    
192        /**
193         * Update the indexes of a StoreEntry
194         * 
195         * @param current
196         * @return update StoreEntry
197         */
198        StoreEntry refreshEntry(StoreEntry current);
199    }