StoreSystem


1   /**
2    * com.mckoi.database.StoreSystem  03 Feb 2003
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 com.mckoi.store.Store;
28  import java.io.IOException  ;
29  
30  /**
31   * An object that creates and manages the Store objects that the database engine 
32   * uses to represent itself on an external medium such as a disk, and that
33   * constitute the low level persistent data format.
34   * <p>
35   * This interface is an abstraction of the database persistence layer.  For
36   * example, an implementation could represent itself as 1 file per store on a
37   * disk, or as a number of stores in a single file, or as an entirely in-memory
38   * database.
39   *
40   * @author Tobias Downer
41   */
42  
43  interface StoreSystem {
44  
45    /**
46     * Returns true if the store with the given name exists within the system,
47     * or false otherwise.
48     */
49    boolean storeExists(String   name);
50    
51    /**
52     * Creates and returns a new persistent Store object given the unique name of
53     * the store.  If the system is read-only or the table otherwise can not be
54     * created then an exception is thrown.
55     * <p>
56     * At the most, you should assume that this will return an implementation of
57     * AbstractStore but you should not be assured of this fact.
58     *
59     * @param name a unique identifier string representing the name of the store.
60     */
61    Store createStore(String   name);
62  
63    /**
64     * Opens an existing persistent Store object in the system and returns the
65     * Store object that contains its data.  An exception is thrown if the store
66     * can not be opened.
67     * <p>
68     * At the most, you should assume that this will return an implementation of
69     * AbstractStore but you should not be assured of this fact.
70     *
71     * @param name a unique identifier string representing the name of the store.
72     */
73    Store openStore(String   name);
74  
75    /**
76     * Closes a store that has been either created or opened with the
77     * 'createStore' or 'openStore' methods.  Returns true if the
78     * store was successfully closed.
79     */
80    boolean closeStore(Store store);
81  
82    /**
83     * Permanently deletes a store from the system - use with care!  Returns
84     * true if the store was successfully deleted and the resources associated
85     * with it were freed.  Returns false if the store could not be deleted.  Note
86     * that it is quite likely that a store may fail to delete in which case the
87     * delete operation should be re-tried after a short timeout.
88     */
89    boolean deleteStore(Store store);
90  
91    /**
92     * Sets a new check point at the current state of this store system.  This is
93     * intended to help journalling check point and recovery systems.  A check
94     * point is set whenever data is committed to the database.  Some systems
95     * can be designed to be able to roll forward or backward to different
96     * check points.  Each check point represents a stable state in the database
97     * life cycle.
98     * <p>
99     * A checkpoint based system greatly improves stability because if a crash
100    * occurs in an intermediate state the changes can simply be rolled back to
101    * the last stable state.
102    * <p>
103    * An implementation may choose not to implement check points in which case
104    * this would be a no-op.
105    */
106   void setCheckPoint();
107 
108   
109   // ---------- Locking ----------
110 
111   /**
112    * Attempts to lock this store system exclusively so that no other process
113    * may access or change the persistent data in the store.  If this fails to
114    * lock, an IOException is generated, otherwise the lock is obtained and the
115    * method returns.
116    */
117   void lock(String   lock_name) throws IOException  ;
118 
119   /**
120    * Unlocks the exclusive access to the persistent store objects.  After this
121    * method completes, access to the store system by other processes is allowed.
122    */
123   void unlock(String   lock_name) throws IOException  ;
124 
125 }
126 
127
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags