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.Collection;
020import java.util.Map;
021import java.util.Set;
022
023/**
024 * Represents a container of persistent objects in the store Acts as a map, but
025 * values can be retrieved in insertion order
026 * 
027 * 
028 */
029public interface MapContainer<K, V> extends Map<K, V> {
030
031    /**
032     * The container is created or retrieved in an unloaded state. load
033     * populates the container will all the indexes used etc and should be
034     * called before any operations on the container
035     */
036    void load();
037
038    /**
039     * unload indexes from the container
040     * 
041     */
042    void unload();
043
044    /**
045     * @return true if the indexes are loaded
046     */
047    boolean isLoaded();
048
049    /**
050     * For homogenous containers can set a custom marshaller for loading keys
051     * The default uses Object serialization
052     * 
053     * @param keyMarshaller
054     */
055    void setKeyMarshaller(Marshaller<K> keyMarshaller);
056
057    /**
058     * For homogenous containers can set a custom marshaller for loading values
059     * The default uses Object serialization
060     * 
061     * @param valueMarshaller
062     * 
063     */
064    void setValueMarshaller(Marshaller<V> valueMarshaller);
065
066    /**
067     * @return the id the MapContainer was create with
068     */
069    Object getId();
070
071    /**
072     * @return the number of values in the container
073     */
074    int size();
075
076    /**
077     * @return true if there are no values stored in the container
078     */
079    boolean isEmpty();
080
081    /**
082     * @param key
083     * @return true if the container contains the key
084     */
085    boolean containsKey(Object key);
086
087    /**
088     * Get the value associated with the key
089     * 
090     * @param key
091     * @return the value associated with the key from the store
092     */
093    V get(Object key);
094
095    /**
096     * @param o
097     * @return true if the MapContainer contains the value o
098     */
099    boolean containsValue(Object o);
100
101    /**
102     * Add add entries in the supplied Map
103     * 
104     * @param map
105     */
106    void putAll(Map<? extends K, ? extends V> map);
107
108    /**
109     * @return a Set of all the keys
110     */
111    Set<K> keySet();
112
113    /**
114     * @return a collection of all the values - the values will be lazily pulled
115     *         out of the store if iterated etc.
116     */
117    Collection<V> values();
118
119    /**
120     * @return a Set of all the Map.Entry instances - the values will be lazily
121     *         pulled out of the store if iterated etc.
122     */
123    Set<Map.Entry<K, V>> entrySet();
124
125    /**
126     * Add an entry
127     * 
128     * @param key
129     * @param value
130     * @return the old value for the key
131     */
132    V put(K key, V value);
133
134    /**
135     * remove an entry associated with the key
136     * 
137     * @param key
138     * @return the old value assocaited with the key or null
139     */
140    V remove(Object key);
141
142    /**
143     * empty the container
144     */
145    void clear();
146
147    /**
148     * Add an entry to the Store Map
149     * 
150     * @param key
151     * @param Value
152     * @return the StoreEntry associated with the entry
153     */
154    StoreEntry place(K key, V value);
155
156    /**
157     * Remove an Entry from ther Map
158     * 
159     * @param entry
160     */
161    void remove(StoreEntry entry);
162
163    /**
164     * Get the Key object from it's location
165     * 
166     * @param keyLocation
167     * @return the key for the entry
168     */
169    K getKey(StoreEntry keyLocation);
170
171    /**
172     * Get the value from it's location
173     * 
174     * @param Valuelocation
175     * @return the Object
176     */
177    V getValue(StoreEntry valueLocation);
178
179    /**
180     * Get the StoreEntry for the first value in the Map
181     * 
182     * @return the first StoreEntry or null if the map is empty
183     */
184    StoreEntry getFirst();
185
186    /**
187     * Get the StoreEntry for the last value item of the Map
188     * 
189     * @return the last StoreEntry or null if the list is empty
190     */
191    StoreEntry getLast();
192
193    /**
194     * Get the next StoreEntry value from the map
195     * 
196     * @param entry
197     * @return the next StoreEntry or null
198     */
199    StoreEntry getNext(StoreEntry entry);
200
201    /**
202     * Get the previous StoreEntry from the map
203     * 
204     * @param entry
205     * @return the previous store entry or null
206     */
207    StoreEntry getPrevious(StoreEntry entry);
208
209    /**
210     * It's possible that a StoreEntry could be come stale this will return an
211     * upto date entry for the StoreEntry position
212     * 
213     * @param entry old entry
214     * @return a refreshed StoreEntry
215     */
216    StoreEntry refresh(StoreEntry entry);
217
218    /**
219     * Get the StoreEntry associated with the key
220     * 
221     * @param key
222     * @return the StoreEntry
223     */
224    StoreEntry getEntry(K key);
225    
226    /**
227     * Set the index bin size
228     * @param size
229     */
230    void setIndexBinSize(int size);
231    
232    /**
233     * @return index bin size
234     */
235    int getIndexBinSize();
236    
237    
238    /**
239     * Add the index key size
240     * @param size
241     */
242    void setIndexKeySize(int size);
243    
244    
245    /**
246     * @return the index key size
247     */
248    int getIndexKeySize();
249    
250   
251    /**
252     * Set the index page size
253     * @param size
254     */
255    void setIndexPageSize(int size);
256    
257    /**
258     * @return the index page size
259     */
260    int getIndexPageSize();
261    
262    /**
263     * set the meximum bin size
264     */
265    void setIndexMaxBinSize(int size);
266    
267    /**
268     * @return the maximum bin size
269     * @return
270     */
271    int getIndexMaxBinSize();
272    
273    /**
274     * @return the loadFactor
275     */
276    public int getIndexLoadFactor();
277    /**
278     * @param loadFactor the loadFactor to set
279     */
280    public void setIndexLoadFactor(int loadFactor);
281    
282    /**
283     * @return the Index MBean
284     */
285    IndexMBean getIndexMBean();
286
287    /**
288     * Clean up all state associated with this container.
289     */
290    void delete();
291}