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.Collection;
020    import java.util.Map;
021    import 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     */
029    public 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    }