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 }