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;
018
019import java.util.List;
020import 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 */
028public 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}