001: /**
002: * com.mckoi.store.Store 30 Aug 2002
003: *
004: * Mckoi SQL Database ( http://www.mckoi.com/database )
005: * Copyright (C) 2000, 2001, 2002 Diehl and Associates, Inc.
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License
009: * Version 2 as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
014: * GNU General Public License Version 2 for more details.
015: *
016: * You should have received a copy of the GNU General Public License
017: * Version 2 along with this program; if not, write to the Free Software
018: * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
019: *
020: * Change Log:
021: *
022: *
023: */package com.mckoi.store;
024:
025: import java.util.List;
026: import java.io.InputStream;
027: import java.io.OutputStream;
028: import java.io.IOException;
029:
030: /**
031: * A store is a resource where areas can be allocated and freed to store
032: * objects. A store can be backed by a file or main memory, or a combination of
033: * the two.
034: * <p>
035: * Some characteristics of implementations of Store may be separately
036: * specified. For example, a file based store that is intended to persistently
037: * store objects may have robustness as a primary requirement. A main memory
038: * based store, or other type of volatile store, may not require robustness.
039: *
040: * @author Tobias Downer
041: */
042:
043: public interface Store {
044:
045: /**
046: * Allocates a block of memory in the store of the specified size and returns
047: * an AreaWriter object that can be used to initialize the contents of the
048: * area. Note that an area in the store is undefined until the 'finish'
049: * method is called in AreaWriter.
050: *
051: * @param size the amount of memory to allocate.
052: * @return an AreaWriter object that allows the area to be setup.
053: * @throws IOException if not enough space available to create the area or
054: * the store is read-only.
055: */
056: AreaWriter createArea(long size) throws IOException;
057:
058: /**
059: * Deletes an area that was previously allocated by the 'createArea' method
060: * by the area id. Once an area is deleted the resources may be reclaimed.
061: * The behaviour of this method is undefined if the id doesn't represent a
062: * valid area.
063: *
064: * @param id the identifier of the area to delete.
065: * @throws IOException (optional) if the id is invalid or the area can not
066: * otherwise by deleted.
067: */
068: void deleteArea(long id) throws IOException;
069:
070: /**
071: * Returns an InputStream implementation that allows for the area with the
072: * given identifier to be read sequentially. The behaviour of this method,
073: * and InputStream object, is undefined if the id doesn't represent a valid
074: * area.
075: * <p>
076: * When 'id' is -1 then a fixed area (64 bytes in size) in the store is
077: * returned. The fixed area can be used to store important static
078: * static information.
079: *
080: * @param id the identifier of the area to read, or id = -1 is a 64 byte
081: * fixed area in the store.
082: * @return an InputStream that allows the area to be read from the start.
083: * @throws IOException (optional) if the id is invalid or the area can not
084: * otherwise be accessed.
085: */
086: InputStream getAreaInputStream(long id) throws IOException;
087:
088: /**
089: * Returns an object that allows for the contents of an area (represented by
090: * the 'id' parameter) to be read. The behaviour of this method, and Area
091: * object, is undefined if the id doesn't represent a valid area.
092: * <p>
093: * When 'id' is -1 then a fixed area (64 bytes in size) in the store is
094: * returned. The fixed area can be used to store important static
095: * static information.
096: *
097: * @param id the identifier of the area to read, or id = -1 is a 64 byte
098: * fixed area in the store.
099: * @return an Area object that allows access to the part of the store.
100: * @throws IOException (optional) if the id is invalid or the area can not
101: * otherwise be accessed.
102: */
103: Area getArea(long id) throws IOException;
104:
105: /**
106: * Returns an object that allows for the contents of an area (represented by
107: * the 'id' parameter) to be read and written. The behaviour of this method,
108: * and MutableArea object, is undefined if the id doesn't represent a valid
109: * area.
110: * <p>
111: * When 'id' is -1 then a fixed area (64 bytes in size) in the store is
112: * returned. The fixed area can be used to store important static
113: * static information.
114: *
115: * @param id the identifier of the area to access, or id = -1 is a 64 byte
116: * fixed area in the store.
117: * @return a MutableArea object that allows access to the part of the store.
118: * @throws IOException (optional) if the id is invalid or the area can not
119: * otherwise be accessed.
120: */
121: MutableArea getMutableArea(long id) throws IOException;
122:
123: // ---------- Check Point Locking ----------
124:
125: /**
126: * It is often useful to guarentee that a certain sequence of updates to a
127: * store is completed and not broken in the middle. For example, when
128: * inserting data into a table you don't want a record to be partially
129: * written when a check point is made. You want the entire sequence of
130: * modifications to be completed before the check point can run. This
131: * means that if a crash occurs, a check point will not recover to a
132: * possible corrupt file.
133: * <p>
134: * To achieve this, the 'lockForWrite' and 'unlockForWrite' methods are
135: * available. When 'lockForWrite' has been called, a check point can not
136: * created until there are no write locks obtained on the table.
137: */
138: void lockForWrite();
139:
140: /**
141: * See the 'lockForWrite' method description.
142: */
143: void unlockForWrite();
144:
145: // ---------- Diagnostic ----------
146:
147: /**
148: * Returns true if the store was closed cleanly. This is important
149: * information that may need to be considered when reading information from
150: * the store. This is typically used to issue a scan on the data in the
151: * store when it is not closed cleanly.
152: */
153: boolean lastCloseClean();
154:
155: /**
156: * Returns a complete list of pointers to all areas in the Store as Long
157: * objects sorted from lowest pointer to highest. This should be used for
158: * diagnostics only because it may be difficult for this to be generated
159: * with some implementations. It is useful in a repair tool to determine if
160: * a pointer is valid or not.
161: */
162: List getAllAreas() throws IOException;
163:
164: }
|