1 /** 2 * JDBM LICENSE v1.00 3 * 4 * Redistribution and use of this software and associated documentation 5 * ("Software"), with or without modification, are permitted provided 6 * that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain copyright 9 * statements and notices. Redistributions must also contain a 10 * copy of this document. 11 * 12 * 2. Redistributions in binary form must reproduce the 13 * above copyright notice, this list of conditions and the 14 * following disclaimer in the documentation and/or other 15 * materials provided with the distribution. 16 * 17 * 3. The name "JDBM" must not be used to endorse or promote 18 * products derived from this Software without prior written 19 * permission of Cees de Groot. For written permission, 20 * please contact cg@cdegroot.com. 21 * 22 * 4. Products derived from this Software may not be called "JDBM" 23 * nor may "JDBM" appear in their names without prior written 24 * permission of Cees de Groot. 25 * 26 * 5. Due credit should be given to the JDBM Project 27 * (http://jdbm.sourceforge.net/). 28 * 29 * THIS SOFTWARE IS PROVIDED BY THE JDBM PROJECT AND CONTRIBUTORS 30 * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT 31 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 32 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 33 * CEES DE GROOT OR ANY CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 34 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 35 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 36 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 37 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 38 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 39 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 40 * OF THE POSSIBILITY OF SUCH DAMAGE. 41 * 42 * Copyright 2000 (C) Cees de Groot. All Rights Reserved. 43 * Copyright 2000-2001 (C) Alex Boisvert. All Rights Reserved. 44 * Contributions are Copyright (C) 2000 by their associated contributors. 45 * 46 * $Id: RecordManager.java,v 1.3 2005/06/25 23:12:31 doomdark Exp $ 47 */ 48 49 package jdbm; 50 51 import java.io.IOException; 52 import jdbm.helper.Serializer; 53 54 /** 55 * An interface to manages records, which are uninterpreted blobs of data. 56 * <p> 57 * The set of record operations is simple: fetch, insert, update and delete. 58 * Each record is identified using a "rowid" and contains a byte[] data block. 59 * Rowids are returned on inserts and you can store them someplace safe 60 * to be able to get back to them. Data blocks can be as long as you wish, 61 * and may have lengths different from the original when updating. 62 * 63 * @author <a href="mailto:boisvert@intalio.com">Alex Boisvert</a> 64 * @author <a href="cg@cdegroot.com">Cees de Groot</a> 65 * @version $Id: RecordManager.java,v 1.3 2005/06/25 23:12:31 doomdark Exp $ 66 */ 67 public interface RecordManager 68 { 69 70 /** 71 * Reserved slot for name directory. 72 */ 73 public static final int NAME_DIRECTORY_ROOT = 0; 74 75 76 /** 77 * Inserts a new record using standard java object serialization. 78 * 79 * @param obj the object for the new record. 80 * @return the rowid for the new record. 81 * @throws IOException when one of the underlying I/O operations fails. 82 */ 83 public abstract long insert( Object obj ) 84 throws IOException; 85 86 87 /** 88 * Inserts a new record using a custom serializer. 89 * 90 * @param obj the object for the new record. 91 * @param serializer a custom serializer 92 * @return the rowid for the new record. 93 * @throws IOException when one of the underlying I/O operations fails. 94 */ 95 public abstract long insert( Object obj, Serializer serializer ) 96 throws IOException; 97 98 99 /** 100 * Deletes a record. 101 * 102 * @param recid the rowid for the record that should be deleted. 103 * @throws IOException when one of the underlying I/O operations fails. 104 */ 105 public abstract void delete( long recid ) 106 throws IOException; 107 108 109 /** 110 * Updates a record using standard java object serialization. 111 * 112 * @param recid the recid for the record that is to be updated. 113 * @param obj the new object for the record. 114 * @throws IOException when one of the underlying I/O operations fails. 115 */ 116 public abstract void update( long recid, Object obj ) 117 throws IOException; 118 119 120 /** 121 * Updates a record using a custom serializer. 122 * 123 * @param recid the recid for the record that is to be updated. 124 * @param obj the new object for the record. 125 * @param serializer a custom serializer 126 * @throws IOException when one of the underlying I/O operations fails. 127 */ 128 public abstract void update( long recid, Object obj, Serializer serializer ) 129 throws IOException; 130 131 132 /** 133 * Fetches a record using standard java object serialization. 134 * 135 * @param recid the recid for the record that must be fetched. 136 * @return the object contained in the record. 137 * @throws IOException when one of the underlying I/O operations fails. 138 */ 139 public abstract Object fetch( long recid ) 140 throws IOException; 141 142 143 /** 144 * Fetches a record using a custom serializer. 145 * 146 * @param recid the recid for the record that must be fetched. 147 * @param serializer a custom serializer 148 * @return the object contained in the record. 149 * @throws IOException when one of the underlying I/O operations fails. 150 */ 151 public abstract Object fetch( long recid, Serializer serializer ) 152 throws IOException; 153 154 155 /** 156 * Closes the record manager. 157 * 158 * @throws IOException when one of the underlying I/O operations fails. 159 */ 160 public abstract void close() 161 throws IOException; 162 163 164 /** 165 * Returns the number of slots available for "root" rowids. These slots 166 * can be used to store special rowids, like rowids that point to 167 * other rowids. Root rowids are useful for bootstrapping access to 168 * a set of data. 169 */ 170 public abstract int getRootCount(); 171 172 173 /** 174 * Returns the indicated root rowid. 175 * 176 * @see #getRootCount 177 */ 178 public abstract long getRoot( int id ) 179 throws IOException; 180 181 182 /** 183 * Sets the indicated root rowid. 184 * 185 * @see #getRootCount 186 */ 187 public abstract void setRoot( int id, long rowid ) 188 throws IOException; 189 190 191 /** 192 * Commit (make persistent) all changes since beginning of transaction. 193 */ 194 public abstract void commit() 195 throws IOException; 196 197 198 /** 199 * Rollback (cancel) all changes since beginning of transaction. 200 */ 201 public abstract void rollback() 202 throws IOException; 203 204 205 206 207 /** 208 * Obtain the record id of a named object. Returns 0 if named object 209 * doesn't exist. 210 */ 211 public abstract long getNamedObject( String name ) 212 throws IOException; 213 214 215 /** 216 * Set the record id of a named object. 217 */ 218 public abstract void setNamedObject( String name, long recid ) 219 throws IOException; 220 221 } 222