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 }