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: */package jdbm;
048:
049: import java.io.IOException;
050: import jdbm.helper.Serializer;
051:
052: /**
053: * An interface to manages records, which are uninterpreted blobs of data.
054: * <p>
055: * The set of record operations is simple: fetch, insert, update and delete.
056: * Each record is identified using a "rowid" and contains a byte[] data block.
057: * Rowids are returned on inserts and you can store them someplace safe
058: * to be able to get back to them. Data blocks can be as long as you wish,
059: * and may have lengths different from the original when updating.
060: *
061: * @author <a href="mailto:boisvert@intalio.com">Alex Boisvert</a>
062: * @author <a href="cg@cdegroot.com">Cees de Groot</a>
063: * @version $Id: RecordManager.java,v 1.3 2005/06/25 23:12:31 doomdark Exp $
064: */
065: public interface RecordManager {
066:
067: /**
068: * Reserved slot for name directory.
069: */
070: public static final int NAME_DIRECTORY_ROOT = 0;
071:
072: /**
073: * Inserts a new record using standard java object serialization.
074: *
075: * @param obj the object for the new record.
076: * @return the rowid for the new record.
077: * @throws IOException when one of the underlying I/O operations fails.
078: */
079: public abstract long insert(Object obj) throws IOException;
080:
081: /**
082: * Inserts a new record using a custom serializer.
083: *
084: * @param obj the object for the new record.
085: * @param serializer a custom serializer
086: * @return the rowid for the new record.
087: * @throws IOException when one of the underlying I/O operations fails.
088: */
089: public abstract long insert(Object obj, Serializer serializer)
090: throws IOException;
091:
092: /**
093: * Deletes a record.
094: *
095: * @param recid the rowid for the record that should be deleted.
096: * @throws IOException when one of the underlying I/O operations fails.
097: */
098: public abstract void delete(long recid) throws IOException;
099:
100: /**
101: * Updates a record using standard java object serialization.
102: *
103: * @param recid the recid for the record that is to be updated.
104: * @param obj the new object for the record.
105: * @throws IOException when one of the underlying I/O operations fails.
106: */
107: public abstract void update(long recid, Object obj)
108: throws IOException;
109:
110: /**
111: * Updates a record using a custom serializer.
112: *
113: * @param recid the recid for the record that is to be updated.
114: * @param obj the new object for the record.
115: * @param serializer a custom serializer
116: * @throws IOException when one of the underlying I/O operations fails.
117: */
118: public abstract void update(long recid, Object obj,
119: Serializer serializer) throws IOException;
120:
121: /**
122: * Fetches a record using standard java object serialization.
123: *
124: * @param recid the recid for the record that must be fetched.
125: * @return the object contained in the record.
126: * @throws IOException when one of the underlying I/O operations fails.
127: */
128: public abstract Object fetch(long recid) throws IOException;
129:
130: /**
131: * Fetches a record using a custom serializer.
132: *
133: * @param recid the recid for the record that must be fetched.
134: * @param serializer a custom serializer
135: * @return the object contained in the record.
136: * @throws IOException when one of the underlying I/O operations fails.
137: */
138: public abstract Object fetch(long recid, Serializer serializer)
139: throws IOException;
140:
141: /**
142: * Closes the record manager.
143: *
144: * @throws IOException when one of the underlying I/O operations fails.
145: */
146: public abstract void close() throws IOException;
147:
148: /**
149: * Returns the number of slots available for "root" rowids. These slots
150: * can be used to store special rowids, like rowids that point to
151: * other rowids. Root rowids are useful for bootstrapping access to
152: * a set of data.
153: */
154: public abstract int getRootCount();
155:
156: /**
157: * Returns the indicated root rowid.
158: *
159: * @see #getRootCount
160: */
161: public abstract long getRoot(int id) throws IOException;
162:
163: /**
164: * Sets the indicated root rowid.
165: *
166: * @see #getRootCount
167: */
168: public abstract void setRoot(int id, long rowid) throws IOException;
169:
170: /**
171: * Commit (make persistent) all changes since beginning of transaction.
172: */
173: public abstract void commit() throws IOException;
174:
175: /**
176: * Rollback (cancel) all changes since beginning of transaction.
177: */
178: public abstract void rollback() throws IOException;
179:
180: /**
181: * Obtain the record id of a named object. Returns 0 if named object
182: * doesn't exist.
183: */
184: public abstract long getNamedObject(String name) throws IOException;
185:
186: /**
187: * Set the record id of a named object.
188: */
189: public abstract void setNamedObject(String name, long recid)
190: throws IOException;
191:
192: }
|