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