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 */
017package org.apache.activemq.kaha.impl.index;
018
019import org.apache.activemq.kaha.StoreEntry;
020
021/**
022 * Inteface to LinkedList of Indexes
023 * 
024 * 
025 */
026public 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}