DataTableFile


1   /**
2    * com.mckoi.database.DataTableFile  16 Dec 1999
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.database;
26  
27  import java.io.IOException  ;
28  
29  /**
30   * This interface handles the abstraction of retreiving information from a
31   * database file.  It knows the fixed length of the data fields and can
32   * deduce the topology of the file and retreive and store information to/
33   * from it.
34   * <p>
35   * The callee of this interface must ensure that all calls to implementations
36   * of this interface are sequential and not concurrent.  It is not expected
37   * that implementations are thread safe.
38   * <p>
39   * See VariableSizeDataTableFile for an implementation of this interface.
40   *
41   * @author Tobias Downer
42   */
43  
44  interface DataTableFile extends TableDataSource {
45  
46    /**
47     * Creates a new file of the given table.  The table is initialised and
48     * contains 0 row entries.  If the table already exists in the database then
49     * this will throw an exception.
50     * <p>
51     * On exit, the object will be initialised and loaded with the given table.
52     *
53     * @param def the definition of the table.
54     */
55    void create(DataTableDef def) throws IOException  ;
56  
57    /**
58     * Updates a file of the given table.  If the table does not exist, then it
59     * is created.  If the table already exists but is different, then the
60     * existing table is modified to incorporate the new fields structure.
61     * <p>
62     * The DataTableFile must have previously been 'load(table_name)' before
63     * this call.
64     * <p>
65     * Implementations of this method may choose to reorganise information that
66     * the relational schemes are dependant on (the row order for example).  If
67     * this method returns 'true' then we must also reindex the schemes.
68     * <p>
69     * <strong>NOTE:</strong> If the new format has columns that are not
70     *   included in the new format then the columns are deleted.
71     *
72     * @param def the definition of the table.
73     * @return true if the table topology has changed.
74     */
75    boolean update(DataTableDef def) throws IOException  ;
76  
77    /**
78     * This is called periodically when this data table file requires some
79     * maintenance.  It is recommended that this method is called every
80     * time the table is initialized (loaded).
81     * <p>
82     * The DataTableFile must have previously been 'load(table_name)' before
83     * this call.
84     * <p>
85     * This method may change the topology of the rows (delete rows that are
86     * marked as deleted), therefore if the method returns true you need to
87     * re-index the schemes.
88     *
89     * @return true if the table topology was changed.
90     */
91    boolean doMaintenance() throws IOException  ;
92  
93  //  /**
94  //   * A recovery method that returns a DataTableDef object for this data
95  //   * table file that was last used in a call to 'create' or 'update'.  This
96  //   * information should be kept in a secondary table topology store but it
97  //   * is useful to keep this information in the data table file just incase
98  //   * something bad happens, or tables are moved to another database.
99  //   */
100 //  DataTableDef recoverLastDataTableDef() throws IOException;
101 
102   /**
103    * Loads a previously created table.  A table can be loaded in read only
104    * mode, in which case any methods that write to the DataTableFile will
105    * throw an IOException.
106    *
107    * @param table_name the name of the table.
108    * @param read_only if true then the table file is opened as read-only.
109    */
110   void load(String   table_name, boolean read_only) throws IOException  ;
111 
112   /**
113    * Shuts down the table.  This is called when the table is closed and the
114    * resources it uses are to be freed back to the system.  This is called
115    * as part of the database shut down procedure or called when we want to
116    * free the resources associated with this table.
117    */
118   void shutdown() throws IOException  ;
119 
120   /**
121    * Deletes the data table file in the file system.  This is used to clear
122    * up resources after a table has been dropped.  The table must be shut
123    * down before this method is called.
124    * <p>
125    * NOTE: Use this with care.  All data is lost!
126    */
127   void drop();
128 
129   /**
130    * Flushes all information that may be cached in memory to disk.  This
131    * includes any relational data, any cached data that hasn't made it to
132    * the file system yet.  It will write out all persistant information
133    * and leave the table in a state where it is fully represented in the
134    * file system.
135    */
136   void updateFile() throws IOException  ;
137 
138   /**
139    * Locks the data in the file to prevent the system overwritting entries
140    * that have been marked as removed.  This is necessary so we may still
141    * safely read removed entries from the table while the table is locked.
142    */
143   void addRowsLock();
144 
145   /**
146    * Unlocks the data in the file to indicate that the system may safely
147    * overwrite removed entries in the file.
148    */
149   void removeRowsLock();
150 
151   /**
152    * Returns true if the file currently has all of its rows locked.
153    */
154   boolean hasRowsLocked();
155 
156 //  /**
157 //   * The number of rows that are currently stored in this table.  This number
158 //   * does not include the rows that have been marked as removed.
159 //   */
160 //  int rowCount();
161 
162   /**
163    * Returns true if the given row index points to a valid and available
164    * row entry.  Returns false if the row entry has been marked as removed,
165    * or the index goes outside the bounds of the table.
166    */
167   boolean isRowValid(int record_index) throws IOException  ;
168 
169   /**
170    * Adds a complete new row into the table.  If the table is in a row locked
171    * state, then this will always add a new entry to the end of the table.
172    * Otherwise, new entries are added where entries were previously removed.
173    * <p>
174    * This will update any column indices that are set.
175    *
176    * @returns the raw row index of the row that was added.
177    */
178   int addRow(RowData row_data) throws IOException  ;
179 
180   /**
181    * Removes a row from the table at the given index.  This will only mark
182    * the entry as removed, and will not actually remove the data.  This is
183    * because a process is allowed to read the data even after the row has been
184    * marked as removed (if the rows have been locked).
185    * <p>
186    * This will update any column indices that are set.
187    *
188    * @param row_index the raw row index of the entry to be marked as removed.
189    */
190   void removeRow(int row_index) throws IOException  ;
191 
192 //  /**
193 //   * Returns a DataCell object of the entry at the given column, row
194 //   * index in the table.  This will always work provided there was once data
195 //   * stored at that index, even if the row has been marked as deleted.
196 //   */
197 //  DataCell getCellAt(int column, int row) throws IOException;
198 
199   /**
200    * Returns a unique number.  This is incremented each time it is accessed.
201    */
202   long nextUniqueKey() throws IOException  ;
203 
204 }
205
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags