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;
018    
019    import java.util.List;
020    import java.util.NoSuchElementException;
021    
022    /**
023     * Represents a container of persistent objects in the store Acts as a map, but
024     * values can be retrieved in insertion order
025     * 
026     * 
027     */
028    public interface ListContainer<V> extends List<V> {
029    
030        /**
031         * The container is created or retrieved in an unloaded state. load
032         * populates the container will all the indexes used etc and should be
033         * called before any operations on the container
034         */
035        void load();
036    
037        /**
038         * unload indexes from the container
039         * 
040         */
041        void unload();
042    
043        /**
044         * @return true if the indexes are loaded
045         */
046        boolean isLoaded();
047    
048        /**
049         * For homogenous containers can set a custom marshaller for loading values
050         * The default uses Object serialization
051         * 
052         * @param marshaller
053         */
054        void setMarshaller(Marshaller marshaller);
055    
056        /**
057         * @return the id the MapContainer was create with
058         */
059        Object getId();
060    
061        /**
062         * @return the number of values in the container
063         */
064        int size();
065    
066        /**
067         * Inserts the given element at the beginning of this list.
068         * 
069         * @param o the element to be inserted at the beginning of this list.
070         */
071        void addFirst(V o);
072    
073        /**
074         * Appends the given element to the end of this list. (Identical in function
075         * to the <tt>add</tt> method; included only for consistency.)
076         * 
077         * @param o the element to be inserted at the end of this list.
078         */
079        void addLast(V o);
080    
081        /**
082         * Removes and returns the first element from this list.
083         * 
084         * @return the first element from this list.
085         * @throws NoSuchElementException if this list is empty.
086         */
087        V removeFirst();
088    
089        /**
090         * Removes and returns the last element from this list.
091         * 
092         * @return the last element from this list.
093         * @throws NoSuchElementException if this list is empty.
094         */
095        V removeLast();
096    
097        /**
098         * remove an objecr from the list without retrieving the old value from the
099         * store
100         * 
101         * @param position
102         * @return true if successful
103         */
104        boolean doRemove(int position);
105    
106        /**
107         * add an Object to the list but get a StoreEntry of its position
108         * 
109         * @param object
110         * @return the entry in the Store
111         */
112        StoreEntry placeLast(V object);
113    
114        /**
115         * insert an Object in first position int the list but get a StoreEntry of
116         * its position
117         * 
118         * @param object
119         * @return the location in the Store
120         */
121        StoreEntry placeFirst(V object);
122    
123        /**
124         * Advanced feature = must ensure the object written doesn't overwrite other
125         * objects in the container
126         * 
127         * @param entry
128         * @param object
129         */
130        void update(StoreEntry entry, V object);
131    
132        /**
133         * Retrieve an Object from the Store by its location
134         * 
135         * @param entry
136         * @return the Object at that entry
137         */
138        V get(StoreEntry entry);
139    
140        /**
141         * Get the StoreEntry for the first item of the list
142         * 
143         * @return the first StoreEntry or null if the list is empty
144         */
145        StoreEntry getFirst();
146    
147        /**
148         * Get the StoreEntry for the last item of the list
149         * 
150         * @return the last StoreEntry or null if the list is empty
151         */
152        StoreEntry getLast();
153    
154        /**
155         * Get the next StoreEntry from the list
156         * 
157         * @param entry
158         * @return the next StoreEntry or null
159         */
160        StoreEntry getNext(StoreEntry entry);
161    
162        /**
163         * Get the previous StoreEntry from the list
164         * 
165         * @param entry
166         * @return the previous store entry or null
167         */
168        StoreEntry getPrevious(StoreEntry entry);
169    
170        /**
171         * remove the Object at the StoreEntry
172         * 
173         * @param entry
174         * @return true if successful
175         */
176        boolean remove(StoreEntry entry);
177    
178        /**
179         * It's possible that a StoreEntry could be come stale this will return an
180         * upto date entry for the StoreEntry position
181         * 
182         * @param entry old entry
183         * @return a refreshed StoreEntry
184         */
185        StoreEntry refresh(StoreEntry entry);
186    }