1 package net.obsearch.storage;
2
3 import hep.aida.bin.StaticBin1D;
4
5 import java.io.IOException;
6 import java.nio.ByteBuffer;
7 import java.util.Iterator;
8
9 import net.obsearch.OperationStatus;
10 import net.obsearch.Status;
11 import net.obsearch.exception.OBException;
12 import net.obsearch.exception.OBStorageException;
13 import net.obsearch.exception.OutOfRangeException;
14
15 /*
16 OBSearch: a distributed similarity search engine This project is to
17 similarity search what 'bit-torrent' is to downloads.
18 Copyright (C) 2008 Arnoldo Jose Muller Molina
19
20 This program is free software: you can redistribute it and/or modify
21 it under the terms of the GNU General Public License as published by
22 the Free Software Foundation, either version 3 of the License, or
23 (at your option) any later version.
24
25 This program is distributed in the hope that it will be useful,
26 but WITHOUT ANY WARRANTY; without even the implied warranty of
27 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
28 GNU General Public License for more details.
29
30 You should have received a copy of the GNU General Public License
31 along with this program. If not, see <http://www.gnu.org/licenses/>.
32 */
33
34 /**
35 * OBStore abstracts a generic storage system. The purpose of this class is to
36 * allow OBSearch to run on top of different storage systems (distributed,
37 * local, file system based, etc). The keys can be sorted, and range queries are
38 * possible. The base interface only allows operations on keys of arrays of
39 * bytes. Subclasses of this interface will provide specialized methods for
40 * Java's primitive types.
41 *
42 * @author Arnoldo Jose Muller Molina
43 */
44
45 public interface OBStore<T extends Tuple> {
46
47 /**
48 * Get the name of this storage system.
49 *
50 * @return the name of this storage system.
51 */
52 String getName();
53
54 /**
55 * Returns the associated value for the given key. If the underlying storage
56 * system can hold multiple keys, then an IllegalArgumentException is
57 * thrown.
58 *
59 * @param key
60 * The key that will be searched.
61 * @return the associated value for the given key or null if the key could
62 * not be found.
63 * @throws IllegalArgumentException
64 * If the underlying storage system can hold multiple keys (
65 * {@link #allowsDuplicatedData()} == true).
66 * @throws OBStorageException
67 * If an exception occurs at the underlying storage system. You
68 * can query the exception to see more details regarding the
69 * nature of the error.
70 * @throws OBException
71 * @throws IOException
72 */
73 byte[] getValue(byte[] key) throws IllegalArgumentException,
74 OBStorageException, OBException;
75
76 /**
77 * Inserts the key value pair. If the key existed, it will be overwritten.
78 *
79 * @param key
80 * Key to insert
81 * @param value
82 * The value that the key will hold after this operation
83 * completes.
84 * @throws OBStorageException
85 * If an exception occurs at the underlying storage system. You
86 * can query the exception to see more details regarding the
87 * nature of the error.
88 * @return {@link net.obsearch.Status#OK} the record was inserted/updated
89 * successfully. {@link net.obsearch.Status#ERROR} if the record
90 * could not be updated.
91 * @throws OBException
92 */
93 OperationStatus put(byte[] key, byte[] value) throws OBStorageException, OBException;
94
95
96
97
98
99
100
101 /**
102 * Deletes the given key and its corresponding value from the database.
103 * If the storage contains duplicates, then all the elements related
104 * to the key are removed.
105 * @param key
106 * The key that will be deleted.
107 * @throws OBStorageException
108 * If an exception occurs at the underlying storage system. You
109 * can query the exception to see more details regarding the
110 * nature of the error.
111 * @return {@link net.obsearch.Status#OK} if the key was found, otherwise,
112 * {@link net.obsearch.Status#NOT_EXISTS}.
113 * @throws OBException
114 * @throws IOException
115 * @throws IllegalAccessException
116 * @throws InstantiationException
117 * @throws OBException
118 * @throws OutOfRangeException
119 */
120 OperationStatus delete(byte[] key) throws OBStorageException, IOException, OBException;
121
122 /**
123 * Closes the storage system.
124 *
125 * @throws OBStorageException
126 * If an exception occurs at the underlying storage system. You
127 * can query the exception to see more details regarding the
128 * nature of the error.
129 * @throws OBException
130 * @throws OBException
131 */
132 void close() throws OBStorageException;
133
134 /**
135 * Deletes all the items in the storage system. Use with care!
136 *
137 * @throws OBStorageException
138 * If an exception occurs at the underlying storage system. You
139 * can query the exception to see more details regarding the
140 * nature of the error.
141 * @throws IllegalAccessException
142 * @throws InstantiationException
143 * @throws OBException
144 * @throws OutOfRangeException
145 */
146 void deleteAll() throws OBStorageException;
147
148 /**
149 * Returns the number of elements in the database.
150 *
151 * @return The number of elements in the database.
152 * @throws OBStorageException
153 * If an exception occurs at the underlying storage system. You
154 * can query the exception to see more details regarding the
155 * nature of the error.
156 * @throws OBException
157 */
158 long size() throws OBStorageException;
159
160 // TODO: put all the ids in longs and not in ints.
161 /**
162 * Returns the next id from the database (incrementing sequences).
163 *
164 * @return The next id that can be inserted.
165 */
166 long nextId() throws OBStorageException;
167
168 /**
169 * Returns the read stats, it contains the avg # of bytes read the std
170 * deviation and also the number of reads.
171 *
172 * @return
173 */
174 StaticBin1D getReadStats();
175
176 /**
177 * Sets the stats object to the given stats. If null, then we stop storing
178 * the stats info.
179 */
180 void setReadStats(StaticBin1D stats);
181
182
183 /**
184 * Return the stats of this object (to be printed for the user)
185 * @return
186 */
187 Object getStats() throws OBException;
188
189 /**
190 * Process the given range of items (from low to high), including low and
191 * high. The TupleProcessor's process method will be called for each value
192 * found within the range.
193 *
194 * @param low lowest key value to return.
195 * @param high highest key value to return.
196 * @throws OBStorageException
197 * If an exception occurs at the underlying storage system. You
198 * can query the exception to see more details regarding the
199 * nature of the error.
200 */
201 CloseIterator<TupleBytes> processRange(byte[] low, byte[] high)
202 throws OBStorageException;
203
204
205 /**
206 * Process the given range of items (from low to high), including low and
207 * high. The TupleProcessor's process method will be called for each value
208 * found within the range. No duplicate values will be returned.
209 *
210 * @param low lowest key value to return.
211 * @param high highest key value to return.
212 * @throws OBStorageException
213 * If an exception occurs at the underlying storage system. You
214 * can query the exception to see more details regarding the
215 * nature of the error.
216 */
217 CloseIterator<TupleBytes> processRangeNoDup(byte[] low, byte[] high)
218 throws OBStorageException;
219
220 /**
221 * Process the given range of items (from high to low), including low and
222 * high. The TupleProcessor's process method will be called for each value
223 * found within the range.
224 *
225 * @param low lowest key value to return.
226 * @param high highest key value to return.
227 * @throws OBStorageException
228 * If an exception occurs at the underlying storage system. You
229 * can query the exception to see more details regarding the
230 * nature of the error.
231 */
232 CloseIterator<TupleBytes> processRangeReverse(byte[] low, byte[] high)
233 throws OBStorageException;
234
235 /**
236 * Process the given range of items (from high to low), including low and
237 * high. The TupleProcessor's process method will be called for each value
238 * found within the range. No duplicate values will be returned.
239 *
240 * @param low lowest key value to return.
241 * @param high highest key value to return.
242 * @throws OBStorageException
243 * If an exception occurs at the underlying storage system. You
244 * can query the exception to see more details regarding the
245 * nature of the error.
246 */
247 CloseIterator<TupleBytes> processRangeReverseNoDup(byte[] low, byte[] high)
248 throws OBStorageException;
249
250 /**
251 * Process all the elements in the DB. Useful for debugging.
252 *
253 * @return An iterator that goes through all the data in the DB.
254 * @throws OBStorageException
255 * @throws OBException
256 */
257 CloseIterator<T> processAll() throws OBStorageException, OBException;
258
259
260
261 // TODO: For File mappings we might need to create a function that allows
262 // the user to expand the size of the buffer by some %.
263 // We don't need this right now but the current architecture will support
264 // this.
265 /**
266 * Return the factory associated to this storage device.
267 */
268 OBStoreFactory getFactory();
269
270
271 /**
272 * Transform Bytes in a format that can be used by the
273 * underlying index.
274 * @param in Input byte array
275 * @return transformed bytes ready to be sorted.`
276 */
277 byte[] prepareBytes(byte[] in);
278
279
280 /**
281 * Somehow optimizes the underlying storage representation.
282 * @throws OBStorageException
283 */
284 void optimize() throws OBStorageException;
285
286
287 }