View Javadoc

1   package net.obsearch.storage;
2   
3   import java.util.Iterator;
4   import net.obsearch.storage.CloseIterator;
5   import net.obsearch.exception.OBStorageException;
6   import net.obsearch.OperationStatus;
7   import java.nio.ByteBuffer;
8   
9   /*
10   OBSearch: a distributed similarity search engine This project is to
11   similarity search what 'bit-torrent' is to downloads. 
12   Copyright (C) 2008 Arnoldo Jose Muller Molina
13  
14   This program is free software: you can redistribute it and/or modify
15   it under the terms of the GNU General Public License as published by
16   the Free Software Foundation, either version 3 of the License, or
17   (at your option) any later version.
18  
19   This program is distributed in the hope that it will be useful,
20   but WITHOUT ANY WARRANTY; without even the implied warranty of
21   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
22   GNU General Public License for more details.
23  
24   You should have received a copy of the GNU General Public License
25   along with this program.  If not, see <http://www.gnu.org/licenses/>.
26   */
27  
28  /**
29   * OBStoreByte abstracts a generic storage system. The purpose of
30   * this class is to allow OBSearch to run on top of different storage
31   * systems (distributed, local, file system based, etc). The keys can
32   * be sorted, and range queries are possible. This interface provides
33   * utility methods for keys of type byte.
34   * @author Arnoldo Jose Muller Molina
35   */
36  
37  public interface OBStoreByte extends OBStore<TupleByte> {
38      
39  
40      /**
41       * Returns the associated value for the given key. If the underlying storage system can hold repeated keys, then
42       * an IllegalArgumentException is thrown.
43       * @param key the key that will be searched.
44       * @return the associated value for the given key.
45       * @throws IllegalArgumentException If the underlying storage system can hold multiple keys.
46       * @throws OBStorageException
47       *                 If an exception occurs at the underlying storage system.
48       *                 You can query the exception to see more details regarding
49       *                 the nature of the error.
50       */
51      byte[] getValue(byte  key) throws IllegalArgumentException, OBStorageException;
52      
53      /**
54       * Process the given range of items (from low to high), including low and high. The TupleProcessor's process
55       * method will be called for each value found within the range.
56       * @param low
57       * @param high
58  		 * @throws OBStorageException 
59  		 *                 If an exception occurs at the underlying storage system.
60       *                 You can query the exception to see more details regarding
61       *                 the nature of the error.
62       */
63      CloseIterator<TupleByte> processRange(byte low, byte high) throws OBStorageException;
64  
65  
66  		/**
67       * Process the given range of items (from high to low), including low and high. The TupleProcessor's process
68       * method will be called for each value found within the range.
69       * @param low
70       * @param high
71  		 * @throws OBStorageException 
72  		 *                 If an exception occurs at the underlying storage system.
73       *                 You can query the exception to see more details regarding
74       *                 the nature of the error.
75       */
76      CloseIterator<TupleByte> processRangeReverse(byte low, byte high) throws OBStorageException;
77      
78  		
79  		/**
80       * Inserts the key value pair. If the key existed, it will be overwritten.
81       * @param key
82       *                Key to insert
83       * @param value
84       *                The value that the key will hold after this operation
85       *                completes.
86       * @throws OBStorageException
87       *                 If an exception occurs at the underlying storage system.
88       *                 You can query the exception to see more details regarding
89       *                 the nature of the error.
90       * @return {@link net.obsearch.OperationStatus.Status#OK} the record
91       * was inserted/updated successfully.
92       *               {@link net.obsearch.OperationStatus.Status#ERROR} if
93       * the record could not be updated.
94       */
95      OperationStatus put(byte key, byte[] value) throws OBStorageException;
96  
97  		/**
98       * Deletes the given key and its corresponding value from the database.
99       * @param key
100      *                The key that will be deleted.
101      * @throws OBStorageException
102      *                 If an exception occurs at the underlying storage system.
103      *                 You can query the exception to see more details regarding
104      *                 the nature of the error.
105      * @return {@link net.obsearch.OperationStatus.Status#OK} if the key was found,
106      *         otherwise, {@link net.obsearch.OperationStatus.Status#NOT_EXISTS}.
107      */
108     OperationStatus delete(byte key)throws OBStorageException;
109 
110 
111 		/**
112 		 * Convert a byte entry into a byte.
113 		 */
114 		public byte bytesToValue(byte[] entry);
115     
116 }
117 
118 
119