KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > mckoi > database > MutableTableDataSource


1 /**
2  * com.mckoi.database.MutableTableDataSource 19 Nov 2000
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 /**
28  * A mutable data source that allows for the addition and removal of rows.
29  *
30  * @author Tobias Downer
31  */
32
33 public interface MutableTableDataSource extends TableDataSource {
34
35   /**
36    * Adds a row to the source. This will add a permanent record into the
37    * the underlying data structure. It will also update the indexing
38    * schemes as appropriate, and also add the row into the set returned by
39    * the 'rowEnumeration' iterator.
40    * <p>
41    * It returns a row index that is used to reference this data in future
42    * queries. Throws an exception if the row additional was not possible
43    * because of IO reasons.
44    */
45   int addRow(RowData row_data);
46
47   /**
48    * Completely removes a row from the source. This will permanently remove
49    * the record from the underlying data structure. It also updates the
50    * indexing schemes and removes the row index from the set returned by
51    * the 'rowEnumeration' iterator.
52    * <p>
53    * Throws an exception if the row index does not reference a valid row within
54    * the context of this data source.
55    */
56   void removeRow(int row_index);
57
58   /**
59    * Updates a row in the source. This will make a permanent change to the
60    * underlying data structure. It will update the indexing schemes as
61    * appropriate, and also add the row into the set returned by the
62    * 'rowEnumeration' iterator.
63    * <p>
64    * It returns a row index for the new updated records. Throws an exception
65    * if the row update was not possible because of IO reasons or the row
66    * index not being a valid reference to a record in this data source.
67    */
68   int updateRow(int row_index, RowData row_data);
69
70   /**
71    * Flushes all changes made on this MutableTableDataSource to the backing
72    * index scheme (IndexSet). This is used during the commit phase of this
73    * objects lifetime. The transaction control mechanism has found that there
74    * are no clashes and now we need to commit the current table view to the
75    * conglomerate. Because this object may not update index information
76    * immediately, we call this to flush all the changes to the table to the
77    * backing index set.
78    * <p>
79    * When this method returns, the backing IndexSet of this view will be
80    * completely up to date.
81    */
82   void flushIndexChanges();
83
84   /**
85    * Performs all constraint integrity checks and actions to any modifications
86    * based on any changes that happened to the table since that last call to
87    * this method. It is important that is called after any call to 'addRow',
88    * 'removeRow' or 'updateRow'.
89    * <p>
90    * Any constraints that are marked as INITIALLY_IMMEDIATE are checked when
91    * this is called, otherwise the constraint is checked at commit time.
92    * <p>
93    * Any referential actions are performed when this method is called. If a
94    * referential action causes a modification to another table, this method
95    * is recursively called on the table modified.
96    * <p>
97    * If a referential integrity constraint is violated and a referential action
98    * is unable to maintain the integrity of the database, any changes made to
99    * the table are reverted.
100    */
101   void constraintIntegrityCheck();
102   
103   /**
104    * Returns a journal that details the changes to this data source since it
105    * was created. This method may return a 'null' object to denote that no
106    * logging is being done. If this returns a MasterTableJournal, then all
107    * 'addRow' and 'removeRow' method calls and their relative order will be
108    * described in this journal.
109    */
110   MasterTableJournal getJournal();
111
112   /**
113    * Disposes this table data source. After this method is called, most use
114    * of this object is undefined, except for the 'getCellContent' and
115    * 'compareCellContent' methods which are valid provided the source is
116    * under a root lock.
117    */
118   void dispose();
119
120   /**
121    * Puts this source under a 'root lock'. A root lock means the root row
122    * structure of this object must not change. A root lock is obtained on
123    * a table when a ResultSet keeps hold of an object outside the life of
124    * the transaction that created the table. It is important that the order
125    * of the rows stays constant (committed deleted rows are not really
126    * deleted and reused, etc) while a table holds at least 1 root lock.
127    */
128   void addRootLock();
129
130   /**
131    * Removes a root lock from this source.
132    */
133   void removeRootLock();
134
135 }
136
Popular Tags