Store


1   /**
2    * com.mckoi.store.Store  30 Aug 2002
3    *
4    * Mckoi SQL Database ( http://www.mckoi.com/database )
5    * Copyright (C) 2000, 2001, 2002  Diehl and Associates, Inc.
6    *
7    * This program is free software; you can redistribute it and/or
8    * modify it under the terms of the GNU General Public License
9    * Version 2 as published by the Free Software Foundation.
10   *
11   * This program is distributed in the hope that it will be useful,
12   * but WITHOUT ANY WARRANTY; without even the implied warranty of
13   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14   * GNU General Public License Version 2 for more details.
15   *
16   * You should have received a copy of the GNU General Public License
17   * Version 2 along with this program; if not, write to the Free Software
18   * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
19   *
20   * Change Log:
21   * 
22   * 
23   */
24  
25  package com.mckoi.store;
26  
27  import java.util.List  ;
28  import java.io.InputStream  ;
29  import java.io.OutputStream  ;
30  import java.io.IOException  ;
31  
32  /**
33   * A store is a resource where areas can be allocated and freed to store
34   * objects.  A store can be backed by a file or main memory, or a combination of
35   * the two.
36   * <p>
37   * Some characteristics of implementations of Store may be separately
38   * specified.  For example, a file based store that is intended to persistently
39   * store objects may have robustness as a primary requirement.  A main memory
40   * based store, or other type of volatile store, may not require robustness.
41   *
42   * @author Tobias Downer
43   */
44  
45  public interface Store {
46  
47    /**
48     * Allocates a block of memory in the store of the specified size and returns
49     * an AreaWriter object that can be used to initialize the contents of the
50     * area.  Note that an area in the store is undefined until the 'finish'
51     * method is called in AreaWriter.
52     *
53     * @param size the amount of memory to allocate.
54     * @return an AreaWriter object that allows the area to be setup.
55     * @throws IOException if not enough space available to create the area or
56     *   the store is read-only.
57     */
58    AreaWriter createArea(long size) throws IOException  ;
59  
60    /**
61     * Deletes an area that was previously allocated by the 'createArea' method
62     * by the area id.  Once an area is deleted the resources may be reclaimed.
63     * The behaviour of this method is undefined if the id doesn't represent a
64     * valid area.
65     *
66     * @param id the identifier of the area to delete.
67     * @throws IOException (optional) if the id is invalid or the area can not
68     *   otherwise by deleted.
69     */
70    void deleteArea(long id) throws IOException  ;
71  
72    /**
73     * Returns an InputStream implementation that allows for the area with the
74     * given identifier to be read sequentially.  The behaviour of this method,
75     * and InputStream object, is undefined if the id doesn't represent a valid
76     * area.
77     * <p>
78     * When 'id' is -1 then a fixed area (64 bytes in size) in the store is
79     * returned.  The fixed area can be used to store important static
80     * static information.
81     *
82     * @param id the identifier of the area to read, or id = -1 is a 64 byte
83     *   fixed area in the store.
84     * @return an InputStream that allows the area to be read from the start.
85     * @throws IOException (optional) if the id is invalid or the area can not
86     *   otherwise be accessed.
87     */
88    InputStream   getAreaInputStream(long id) throws IOException  ;
89    
90    /**
91     * Returns an object that allows for the contents of an area (represented by
92     * the 'id' parameter) to be read.  The behaviour of this method, and Area
93     * object, is undefined if the id doesn't represent a valid area.
94     * <p>
95     * When 'id' is -1 then a fixed area (64 bytes in size) in the store is
96     * returned.  The fixed area can be used to store important static
97     * static information.
98     *
99     * @param id the identifier of the area to read, or id = -1 is a 64 byte
100    *   fixed area in the store.
101    * @return an Area object that allows access to the part of the store.
102    * @throws IOException (optional) if the id is invalid or the area can not
103    *   otherwise be accessed.
104    */
105   Area getArea(long id) throws IOException  ;
106 
107   /**
108    * Returns an object that allows for the contents of an area (represented by
109    * the 'id' parameter) to be read and written.  The behaviour of this method,
110    * and MutableArea object, is undefined if the id doesn't represent a valid
111    * area.
112    * <p>
113    * When 'id' is -1 then a fixed area (64 bytes in size) in the store is
114    * returned.  The fixed area can be used to store important static
115    * static information.
116    *
117    * @param id the identifier of the area to access, or id = -1 is a 64 byte
118    *   fixed area in the store.
119    * @return a MutableArea object that allows access to the part of the store.
120    * @throws IOException (optional) if the id is invalid or the area can not
121    *   otherwise be accessed.
122    */
123   MutableArea getMutableArea(long id) throws IOException  ;
124 
125   // ---------- Check Point Locking ----------
126 
127   /**
128    * It is often useful to guarentee that a certain sequence of updates to a
129    * store is completed and not broken in the middle.  For example, when
130    * inserting data into a table you don't want a record to be partially
131    * written when a check point is made.  You want the entire sequence of
132    * modifications to be completed before the check point can run.  This
133    * means that if a crash occurs, a check point will not recover to a
134    * possible corrupt file.
135    * <p>
136    * To achieve this, the 'lockForWrite' and 'unlockForWrite' methods are
137    * available.  When 'lockForWrite' has been called, a check point can not
138    * created until there are no write locks obtained on the table.
139    */
140   void lockForWrite();
141 
142   /**
143    * See the 'lockForWrite' method description.
144    */
145   void unlockForWrite();
146 
147   // ---------- Diagnostic ----------
148 
149   /**
150    * Returns true if the store was closed cleanly.  This is important
151    * information that may need to be considered when reading information from
152    * the store.  This is typically used to issue a scan on the data in the
153    * store when it is not closed cleanly.
154    */
155   boolean lastCloseClean();
156 
157   /**
158    * Returns a complete list of pointers to all areas in the Store as Long
159    * objects sorted from lowest pointer to highest.  This should be used for
160    * diagnostics only because it may be difficult for this to be generated
161    * with some implementations.  It is useful in a repair tool to determine if
162    * a pointer is valid or not.
163    */
164   List   getAllAreas() throws IOException  ;
165 
166 }
167 
168
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags