001 /** 002 * JDBM LICENSE v1.00 003 * 004 * Redistribution and use of this software and associated documentation 005 * ("Software"), with or without modification, are permitted provided 006 * that the following conditions are met: 007 * 008 * 1. Redistributions of source code must retain copyright 009 * statements and notices. Redistributions must also contain a 010 * copy of this document. 011 * 012 * 2. Redistributions in binary form must reproduce the 013 * above copyright notice, this list of conditions and the 014 * following disclaimer in the documentation and/or other 015 * materials provided with the distribution. 016 * 017 * 3. The name "JDBM" must not be used to endorse or promote 018 * products derived from this Software without prior written 019 * permission of Cees de Groot. For written permission, 020 * please contact cg@cdegroot.com. 021 * 022 * 4. Products derived from this Software may not be called "JDBM" 023 * nor may "JDBM" appear in their names without prior written 024 * permission of Cees de Groot. 025 * 026 * 5. Due credit should be given to the JDBM Project 027 * (http://jdbm.sourceforge.net/). 028 * 029 * THIS SOFTWARE IS PROVIDED BY THE JDBM PROJECT AND CONTRIBUTORS 030 * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT 031 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 032 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 033 * CEES DE GROOT OR ANY CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 034 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 035 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 036 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 037 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 038 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 039 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 040 * OF THE POSSIBILITY OF SUCH DAMAGE. 041 * 042 * Copyright 2000 (C) Cees de Groot. All Rights Reserved. 043 * Copyright 2000-2001 (C) Alex Boisvert. All Rights Reserved. 044 * Contributions are Copyright (C) 2000 by their associated contributors. 045 * 046 * $Id: RecordManager.java,v 1.3 2005/06/25 23:12:31 doomdark Exp $ 047 */ 048 package jdbm; 049 050 051 import java.io.IOException; 052 import jdbm.helper.Serializer; 053 054 055 /** 056 * An interface to manages records, which are uninterpreted blobs of data. 057 * <p> 058 * The set of record operations is simple: fetch, insert, update and delete. 059 * Each record is identified using a "rowid" and contains a byte[] data block. 060 * Rowids are returned on inserts and you can store them someplace safe 061 * to be able to get back to them. Data blocks can be as long as you wish, 062 * and may have lengths different from the original when updating. 063 * 064 * @author <a href="mailto:boisvert@intalio.com">Alex Boisvert</a> 065 * @author <a href="cg@cdegroot.com">Cees de Groot</a> 066 * @version $Id: RecordManager.java,v 1.3 2005/06/25 23:12:31 doomdark Exp $ 067 */ 068 public interface RecordManager 069 { 070 /** Reserved slot for name directory. */ 071 int NAME_DIRECTORY_ROOT = 0; 072 073 074 /** 075 * Inserts a new record using standard java object serialization. 076 * 077 * @param obj the object for the new record. 078 * @return the rowid for the new record. 079 * @throws IOException when one of the underlying I/O operations fails. 080 */ 081 long insert( Object obj ) throws IOException; 082 083 084 /** 085 * Inserts a new record using a custom serializer. 086 * 087 * @param obj the object for the new record. 088 * @param serializer a custom serializer 089 * @return the rowid for the new record. 090 * @throws IOException when one of the underlying I/O operations fails. 091 */ 092 long insert( Object obj, Serializer serializer ) throws IOException; 093 094 095 /** 096 * Deletes a record. 097 * 098 * @param recid the rowid for the record that should be deleted. 099 * @throws IOException when one of the underlying I/O operations fails. 100 */ 101 void delete( long recid ) throws IOException; 102 103 104 /** 105 * Updates a record using standard java object serialization. 106 * 107 * @param recid the recid for the record that is to be updated. 108 * @param obj the new object for the record. 109 * @throws IOException when one of the underlying I/O operations fails. 110 */ 111 void update( long recid, Object obj ) throws IOException; 112 113 114 /** 115 * Updates a record using a custom serializer. 116 * 117 * @param recid the recid for the record that is to be updated. 118 * @param obj the new object for the record. 119 * @param serializer a custom serializer 120 * @throws IOException when one of the underlying I/O operations fails. 121 */ 122 void update( long recid, Object obj, Serializer serializer ) throws IOException; 123 124 125 /** 126 * Fetches a record using standard java object serialization. 127 * 128 * @param recid the recid for the record that must be fetched. 129 * @return the object contained in the record. 130 * @throws IOException when one of the underlying I/O operations fails. 131 */ 132 Object fetch( long recid ) throws IOException; 133 134 135 /** 136 * Fetches a record using a custom serializer. 137 * 138 * @param recid the recid for the record that must be fetched. 139 * @param serializer a custom serializer 140 * @return the object contained in the record. 141 * @throws IOException when one of the underlying I/O operations fails. 142 */ 143 Object fetch( long recid, Serializer serializer ) throws IOException; 144 145 146 /** 147 * Closes the record manager. 148 * 149 * @throws IOException when one of the underlying I/O operations fails. 150 */ 151 void close() throws IOException; 152 153 154 /** 155 * Returns the number of slots available for "root" rowids. These slots 156 * can be used to store special rowids, like rowids that point to 157 * other rowids. Root rowids are useful for bootstrapping access to 158 * a set of data. 159 */ 160 int getRootCount(); 161 162 163 /** 164 * Returns the indicated root rowid. 165 * 166 * @see #getRootCount 167 */ 168 long getRoot( int id ) throws IOException; 169 170 171 /** 172 * Sets the indicated root rowid. 173 * 174 * @see #getRootCount 175 */ 176 void setRoot( int id, long rowid ) throws IOException; 177 178 179 /** Commit (make persistent) all changes since beginning of transaction. */ 180 void commit() throws IOException; 181 182 183 /** Rollback (cancel) all changes since beginning of transaction. */ 184 void rollback() throws IOException; 185 186 187 /** Obtain the record id of a named object. Returns 0 if named object doesn't exist. */ 188 long getNamedObject( String name ) throws IOException; 189 190 191 /** Set the record id of a named object. */ 192 void setNamedObject( String name, long recid ) throws IOException; 193 } 194