HSQLDB example source code file (dbfiles.xml)

This example HSQLDB source code file (dbfiles.xml) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - HSQLDB tags/keywords

cached, create, hsqldb, if, if, in, shutdown, shutdown, sql, the, the, there, this, this

The HSQLDB dbfiles.xml source code

<!-- $Id: dbfiles.xml,v 1.3 2005/04/14 21:52:34 unsaved Exp $ -->

<appendix>

<title>Hsqldb Database Files and Recovery
<appendixinfo>
    <edition>$Revision: 1.3 $
    <pubdate>$Date: 2005/04/14 21:52:34 $
    <keywordset>
        <keyword>HSQLDB
        <keyword>Data
        <keyword>Files
    </keywordset>
    <legalnotice>
        This text is based on HypersonicSQL documentation, updated to reflect 
        the latest version 1.8.0 of HSQLDB.
    </para>
</appendixinfo>

<section>
    <para>
        The Standalone and Client/Server modes will in most cases use files to 
        store all data to disk in a persistent and safe way.
        This document describes the meaning of the files, the states and the 
        procedures followed by the engine to recover the data.
    </para> 
        A database named 'test' is used in this description.
        The database files will be as follows.
    </para>
</section>

<variablelist>
    <title>Database Files
    <varlistentry>test.properties
        Contains the entry 'modified'.
        If the entry 'modified' is set to 'yes' then the database is either 
        running or was not closed correctly (because the close algorithm sets 
        'modified' to 'no' at the end).
        </para>
    </varlistentry>
    <varlistentry>test.script
        This file contains the SQL statements that makes up the database up to 
        the last checkpoint - it is in synch with
        <filename>test.backup.
        </para>
    </varlistentry>
    <varlistentry>test.data
        This file contains the (binary) data records for CACHED tables only.
        </para>
    </varlistentry>
    <varlistentry>test.backup
        This is compressed file that contains the complete backup of the old 
        <filename>test.data file at the time of last checkpoint.
        </para>
    </varlistentry>
    <varlistentry>test.log
        This file contains the extra SQL statements that have modified the 
        database since the last checkpoint (something like the 'Redo-log' or 
        'Transaction-log', but just text).
        </para>
        In the above list, a checkpoint results from both a CHECKPOINT command 
        and a SHUTDOWN command.
        </para>
    </varlistentry>
</variablelist>

<section>
    <title>States
    <section>Database is closed correctly
    <itemizedlist>
        <title>State after using the command SHUTDOWN
        <listitem>
            The <filename>test.data file is fully updated.
        </para> 
            The <filename>test.backup contains the compressed 
            <filename>test.data file.
        </para> 
            The  <filename>test.script contains the information in 
            the database, excluding data for CACHED and TEXT tables. 
        </para> 
            The <filename>test.properties contains the entry 
            'modified'  set to 'no'.
        </para> 
            There is no <filename>test.log file.
        </para>
    </itemizedlist>
    <section>Database is closed correctly with SHUTDOWN SCRIPT
    <itemizedlist>
        <title>State after using the command SHUTDOWN SCRIPT
        <listitem>
            The <filename>test.data file does not exist; all CACHED 
            table data is in the <filename>test.script file
        </para> 
            The <filename>test.backup does not exist.
        </para> 
            The  <filename>test.script contains the information in 
            the database, including data for CACHED and TEXT tables.
        </para> 
            The <filename>test.properties contains the entry 
            'modified'  set to 'no'.
        </para> 
            There is no <filename>test.log file.
        </para>
    </itemizedlist>
    <section>Database is aborted
    <para>
        This may happen by sudden power off, Ctrl+C in Windows, but may be 
        simulated using the command SHUTDOWN IMMEDIATELY.
    </para>
    <itemizedlist>
        <title>Aborted Database state
        <listitem>
            The <filename>test.properties still containes 
            'modified=yes'.
        </para> 
            The <filename>test.script contains a snapshot of the 
            database at the last checkpoint and is OK.
        </para> 
            The <filename>test.data file may be corrupt because the 
            cache in memory was not written out completely.
        </para> 
            The <filename>test.backup file contains a snapshot of 
            <filename>test.data that corresponds to 
            <filename>test.script.
        </para> 
            The  <filename>test.log file contain all information to 
            re-do all changes since the snanapshot.
            As a result of abnormal termination, this file may be partially 
            corrupt.
        </para>
    </itemizedlist>
</section>

<section>
    <title>Procedures
    <para>
        The database engine performs the following procedures internally in 
        different circumstances. 
    </para>
    <section>
        <procedure>
            <title>Clean Hsqldb database shutdown
            <step>
                The <filename>test.data file is written completely 
                (all the modified cached table rows are witten out) and closed.
            </para> 
                The <filename>test.backup.new is created (containing 
                the compressed <filename>test.data file)
            </para> 
                The file <filename>test.script.new is created using 
                the information in the database (and thus shrinks because no 
                UPDATE and DELETE statements; only INSERT).
            </para> 
                The entry 'modified' in the properties file is set to 
                'yes-new-files'
            </para> 
                The file <filename>test.script is deleted
            </para> 
                The file <filename>test.script.new is renamed to 
                <filename>test.script
            </para> 
                The file <filename>test.backup is deleted
            </para> 
                The file <filename>test.backup.new is renamed to 
                <filename>test.backup
            </para> 
                The entry 'modified' in the properties file is set to 'no' 
            </para> 
                The file <filename>test.log is deleted
            </para>
        </procedure>
    </section>
    <section>
        <procedure>
            <title>Database is opened
            <step>
                Check if the database files are in use (by checking a special 
                <filename>test.lck file).
            </para> 
                See if the <filename>test.properties file exists,
                otherwise create it.
            </para> 
                If the <filename>test.properties did not exist, then 
                this is a new database.
                Create the empty <filename>test.log to append new 
                commands.
            </para> 
                If it is an existing database, check in the
                <filename>test.properties file if 'modified=yes'.
                This would mean last time it was not closed correctly, and thus 
                the <filename>test.data file may be corrupted or 
                incomplete.
                In this case the 'REPAIR' algorithm is executed (see below), 
                before the database is opened normally.
            </para> 
                Otherwise, if in the <filename>test.properties file
                'modified=yes-new-files', then the (old) 
                <filename>test.backup and 
                <filename>test.script files are deleted and the new 
                <filename>test.script.new file is renamed to 
                <filename>test.script.
                </para> 
                Open the <filename>test.script file and execute the 
                commands.
            </para> 
                Create the empty test.log to append new commands.
            </para>
        </procedure>
    </section>
    <section>
        <para>
            The current <filename>test.data file is corrupt, but 
            with the old <filename>test.data (from the 
            <filename>test.backup file and 
            <filename>test.script) and the current 
            <filename>test.log, the database is made up-to-date.
            The database engine takes these steps:
        </para>
        <procedure>
            <title>Database Repair
            <step>
                    Restore the old <filename>test.data file from 
                    the backup (uncompress the <filename>test.backup
                    and overwrite <filename>test.data).
            </para>
                Execute all commands in the <filename>test.script 
                file.
            </para>
                Execute all commands in the <filename>test.log file.
                If due to corruption, an exception is thrown, the rest of the 
                lines of command in the <filename>test.log file are 
                ignored.
            </para>
                Close the database correctly (including a backup).
            </para>
        </procedure>
    </section>
</section>
</appendix>