PageRenderTime 51ms CodeModel.GetById 20ms RepoModel.GetById 0ms app.codeStats 0ms

/src/jdbm/RecordManager.java

https://github.com/stefanvstein/monitor
Java | 324 lines | 51 code | 54 blank | 219 comment | 0 complexity | 1914983d7f536fc223124891f51a2777 MD5 | raw file
  1. /*******************************************************************************
  2. * Copyright 2010 Cees De Groot, Alex Boisvert, Jan Kotek
  3. *
  4. * Licensed under the Apache License, Version 2.0 (the "License");
  5. * you may not use this file except in compliance with the License.
  6. * You may obtain a copy of the License at
  7. *
  8. * http://www.apache.org/licenses/LICENSE-2.0
  9. *
  10. * Unless required by applicable law or agreed to in writing, software
  11. * distributed under the License is distributed on an "AS IS" BASIS,
  12. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13. * See the License for the specific language governing permissions and
  14. * limitations under the License.
  15. ******************************************************************************/
  16. package jdbm;
  17. import java.io.IOException;
  18. import java.util.Comparator;
  19. /**
  20. * An interface to manages records, which are objects serialized to byte[] on background.
  21. * <p>
  22. * The set of record operations is simple: fetch, insert, update and delete.
  23. * Each record is identified using a "rowid" and contains a byte[] data block serialized to object.
  24. * Rowids are returned on inserts and you can store them someplace safe
  25. * to be able to get back to them. Data blocks can be as long as you wish,
  26. * and may have lengths different from the original when updating.
  27. * <p>
  28. * RecordManager is responsible for handling transactions.
  29. * JDBM2 supports only single transaction for data store.
  30. * See <code>commit</code> and <code>roolback</code> methods for more details.
  31. * <p>
  32. * RecordManader is also factory for primary Maps.
  33. * <p>
  34. * @author <a href="mailto:opencoeli@gmail.com">Jan Kotek</a>
  35. * @author <a href="mailto:boisvert@intalio.com">Alex Boisvert</a>
  36. * @author <a href="cg@cdegroot.com">Cees de Groot</a>
  37. */
  38. public interface RecordManager
  39. {
  40. /**
  41. * Recid indicating no record (e.g. null)
  42. */
  43. public static final long NULL_RECID = 0;
  44. /**
  45. * Inserts a new record using standard java object serialization.
  46. *
  47. * @param obj the object for the new record.
  48. * @return the rowid for the new record.
  49. * @throws IOException when one of the underlying I/O operations fails.
  50. */
  51. public abstract long insert( Object obj )
  52. throws IOException;
  53. /**
  54. * Inserts a new record using a custom serializer.
  55. *
  56. * @param obj the object for the new record.
  57. * @param serializer a custom serializer
  58. * @return the rowid for the new record.
  59. * @throws IOException when one of the underlying I/O operations fails.
  60. */
  61. public abstract <A> long insert( A obj, Serializer<A> serializer )
  62. throws IOException;
  63. /**
  64. * Deletes a record.
  65. *
  66. * @param recid the rowid for the record that should be deleted.
  67. * @throws IOException when one of the underlying I/O operations fails.
  68. */
  69. public abstract void delete( long recid )
  70. throws IOException;
  71. /**
  72. * Updates a record using standard java object serialization.
  73. *
  74. * @param recid the recid for the record that is to be updated.
  75. * @param obj the new object for the record.
  76. * @throws IOException when one of the underlying I/O operations fails or given recid does not exists.
  77. */
  78. public abstract void update( long recid, Object obj )
  79. throws IOException;
  80. /**
  81. * Updates a record using a custom serializer.
  82. * If given recid does not exist, IOException will be thrown before/during commit (cache).
  83. *
  84. *
  85. * @param recid the recid for the record that is to be updated.
  86. * @param obj the new object for the record.
  87. * @param serializer a custom serializer
  88. * @throws IOException when one of the underlying I/O operations fails
  89. */
  90. public abstract <A> void update( long recid, A obj, Serializer<A> serializer )
  91. throws IOException;
  92. /**
  93. * Fetches a record using standard java object serialization.
  94. * If given recid does not exist, IOException will be thrown before/during commit (cache).
  95. *
  96. * @param recid the recid for the record that must be fetched.
  97. * @return the object contained in the record, null if given recid does not exist
  98. * @throws IOException when one of the underlying I/O operations fails.
  99. */
  100. public abstract Object fetch( long recid )
  101. throws IOException;
  102. /**
  103. * Fetches a record using a custom serializer.
  104. *
  105. * @param recid the recid for the record that must be fetched.
  106. * @param serializer a custom serializer
  107. * @return the object contained in the record, null if given recid does not exist
  108. * @throws IOException when one of the underlying I/O operations fails.
  109. */
  110. public abstract <A> A fetch( long recid, Serializer<A> serializer )
  111. throws IOException;
  112. /**
  113. * Fetches a record using a custom serializer and optionaly disabled cache
  114. *
  115. * @param recid the recid for the record that must be fetched.
  116. * @param serializer a custom serializer
  117. * @param disableCache true to disable any caching mechanism
  118. * @return the object contained in the record, null if given recid does not exist
  119. * @throws IOException when one of the underlying I/O operations fails.
  120. */
  121. public abstract <A> A fetch( long recid, Serializer<A> serializer, boolean disableCache )
  122. throws IOException;
  123. /**
  124. * Closes the record manager and release resources.
  125. * Record manager can not be used after it was closed
  126. *
  127. * @throws IOException when one of the underlying I/O operations fails.
  128. */
  129. public abstract void close()
  130. throws IOException;
  131. /**
  132. * Empty cache. This may be usefull if you need to release memory.
  133. *
  134. * @throws IOException
  135. */
  136. public abstract void clearCache() throws IOException;
  137. /**
  138. * Defragments storage, so it consumes less space.
  139. * This commits any uncommited data.
  140. *
  141. * @throws IOException
  142. */
  143. public abstract void defrag() throws IOException;
  144. /**
  145. * Commit (make persistent) all changes since beginning of transaction.
  146. * JDBM supports only single transaction.
  147. */
  148. public abstract void commit()
  149. throws IOException;
  150. /**
  151. * Rollback (cancel) all changes since beginning of transaction.
  152. * JDBM supports only single transaction.
  153. * This operations affects all maps created by this RecordManager.
  154. */
  155. public abstract void rollback()
  156. throws IOException;
  157. /**
  158. * Obtain the record id of a named object. Returns 0 if named object
  159. * doesn't exist.
  160. * Named objects are used to store Map views and other well known objects.
  161. */
  162. public abstract long getNamedObject( String name )
  163. throws IOException;
  164. /**
  165. * Set the record id of a named object.
  166. * Named objects are used to store Map views and other well known objects.
  167. */
  168. public abstract void setNamedObject( String name, long recid )
  169. throws IOException;
  170. /**
  171. * Creates or load existing Primary Hash Map which persists data into DB.
  172. *
  173. *
  174. * @param <K> Key type
  175. * @param <V> Value type
  176. * @param name record name
  177. * @return
  178. */
  179. public <K, V> PrimaryHashMap<K, V> hashMap(String name);
  180. /**
  181. * Creates or load existing Primary TreeMap which persists data into DB.
  182. *
  183. *
  184. * @param <K> Key type
  185. * @param <V> Value type
  186. * @param name record name
  187. * @return
  188. */
  189. @SuppressWarnings("unchecked")
  190. public <K extends Comparable, V> PrimaryTreeMap<K, V> treeMap(String name);
  191. /**
  192. * Creates or load existing TreeMap which persists data into DB.
  193. *
  194. * @param <K> Key type
  195. * @param <V> Value type
  196. * @param name record name
  197. * @param valueSerializer Serializer used for values. This may reduce disk space usage.
  198. * @return
  199. */
  200. @SuppressWarnings("unchecked")
  201. public <K extends Comparable, V> PrimaryTreeMap<K, V> treeMap(String name, Serializer<V> valueSerializer);
  202. /**
  203. * Creates or load existing TreeMap which persists data into DB.
  204. *
  205. * @param <K> Key type
  206. * @param <V> Value type
  207. * @param name record name
  208. * @param valueSerializer Serializer used for values. This may reduce disk space usage.
  209. * @param keySerializer Serializer used for keys. This may reduce disk space usage.
  210. * @return
  211. */
  212. @SuppressWarnings("unchecked")
  213. public <K extends Comparable, V> PrimaryTreeMap<K, V> treeMap(String name,
  214. Serializer<V> valueSerializer, Serializer<K> keySerializer);
  215. /**
  216. * Creates or load existing TreeMap which persists data into DB.
  217. *
  218. *
  219. * @param <K> Key type
  220. * @param <V> Value type
  221. * @param name record name
  222. * @param keyComparator Comparator used to sort keys
  223. * @return
  224. */
  225. public <K, V> PrimaryTreeMap<K, V> treeMap(String name, Comparator<K> keyComparator);
  226. /**
  227. * Creates or load existing TreeMap which persists data into DB.
  228. *
  229. *
  230. * @param <K> Key type
  231. * @param <V> Value type
  232. * @param name record name
  233. * @param keyComparator Comparator used to sort keys
  234. * @param valueSerializer Serializer used for values. This may reduce disk space usage
  235. * @return
  236. */
  237. public <K, V> PrimaryTreeMap<K, V> treeMap(String name,
  238. Comparator<K> keyComparator, Serializer<V> valueSerializer) ;
  239. /**
  240. * Creates or load existing TreeMap which persists data into DB.
  241. *
  242. * @param <K> Key type
  243. * @param <V> Value type
  244. * @param name record name
  245. * @param keyComparator Comparator used to sort keys
  246. * @param valueSerializer Serializer used for values. This may reduce disk space usage
  247. * @param keySerializer Serializer used for keys. This may reduce disk space usage *
  248. * @return
  249. */
  250. public <K, V> PrimaryTreeMap<K, V> treeMap(String name,
  251. Comparator<K> keyComparator, Serializer<V> valueSerializer, Serializer<K> keySerializer) ;
  252. /**
  253. * Creates or load existing StoreMap which persists data into DB.
  254. *
  255. * @param <V> Value type
  256. * @param name record name
  257. * @param valueSerializer Serializer used for values. This may reduce disk space usage
  258. * @return map
  259. */
  260. public <V> PrimaryStoreMap<Long, V> storeMap(String name,
  261. Serializer<V> valueSerializer) ;
  262. /**
  263. * Creates or load existing Primary StoreMap which persists data into DB.
  264. *
  265. * @param <V> Value type
  266. * @param name record name
  267. * @return map
  268. */
  269. public <V> PrimaryStoreMap<Long, V> storeMap(String name);
  270. }