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
049 package jdbm;
050
051 import java.io.IOException;
052 import jdbm.helper.Serializer;
053
054 /**
055 * An interface to manages records, which are uninterpreted blobs of data.
056 * <p>
057 * The set of record operations is simple: fetch, insert, update and delete.
058 * Each record is identified using a "rowid" and contains a byte[] data block.
059 * Rowids are returned on inserts and you can store them someplace safe
060 * to be able to get back to them. Data blocks can be as long as you wish,
061 * and may have lengths different from the original when updating.
062 *
063 * @author <a href="mailto:boisvert@intalio.com">Alex Boisvert</a>
064 * @author <a href="cg@cdegroot.com">Cees de Groot</a>
065 * @version $Id: RecordManager.java,v 1.3 2005/06/25 23:12:31 doomdark Exp $
066 */
067 public interface RecordManager
068 {
069
070 /**
071 * Reserved slot for name directory.
072 */
073 public static final int NAME_DIRECTORY_ROOT = 0;
074
075
076 /**
077 * Inserts a new record using standard java object serialization.
078 *
079 * @param obj the object for the new record.
080 * @return the rowid for the new record.
081 * @throws IOException when one of the underlying I/O operations fails.
082 */
083 public abstract long insert( Object obj )
084 throws IOException;
085
086
087 /**
088 * Inserts a new record using a custom serializer.
089 *
090 * @param obj the object for the new record.
091 * @param serializer a custom serializer
092 * @return the rowid for the new record.
093 * @throws IOException when one of the underlying I/O operations fails.
094 */
095 public abstract long insert( Object obj, Serializer serializer )
096 throws IOException;
097
098
099 /**
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