com.marringtons.object
Class Database

java.lang.Object
  com.marringtons.object.Database

public class Database

extends Object

The DAO system uses this class for database wide control for procedures such as DAO association, opening, closing and backing up.It can also be used to manipulate a single open database. It also has a method for DAO access so that the DAO object can be pure data transfer.

 
  Database db;
  db = Database.resetDefaultDatabase();	// go back to primary database for new objects as default
  db = Database.defaultDatabase();	// retrieve the current default database
  Database db2 = Database.get( Database.defaultDatabase().dataFile.file.file.getAbsolutePath());
  assertTrue( db == db2);
 
  db = associateDatabase( "myStaticDB", true);	// set a default to a new known database file - used by associate();
  db.associate( myReferenceData.class);	// to the above read-only database, index size 1 million or from ini file
  db.associate( myReferenceData.class, 10000);	// same as above, but assuming a small number of records
 
  String[] dbs = Database.listDatabases();
  assertTrue( dbs[0].endsWith( "primary.database");
 
  if (atMidnight)
  	 Database.flushDatabases();	// write all to disk (closes all to reopen when needed)
 
  db.backup();	// backs up the default database
  Database.backupAll();	// backs up all open databases
 
  ZipOutputStream zip = new ZipOutputStream( Output.makeUnique( "testBackup", "zip"), false);
  db.backup( zip);	// backs up the default database to an archive
 
  db.restore( "mydb.xml");
  db.restore( myFileReader);
 
  Access access = Dabatase.access( myDAO);
  access.commit();
 
  Database.closeDatabases();	// always call before program exits.
  
 

Author:

Paul Marrington

Field Summary

String

fileName Name of the file that contains this database.

Method Summary

com.marringtons.object.Database.Association	associate(Class dataClass) Associate a DAO with a known database database.
com.marringtons.object.Database.Association	associate(Class dataClass, int indexSizeEstimate) Associate a DAO with a known database database.
String	backup() Back up the complete default database
String	backup(ZipOutputStream zip) Back up the complete default database to a unique file as XML.
void	clear() Empty database of contents.
static void	closeDatabases() Called before program exits to make sure all systems are flushed.
static void	flushDatabases() Make sure changes on all open databases are committed to disk for perpetuity.
static Database	get(String name) retrieve the database for a known file from the cache.
static Database	get(String name, boolean readOnly) Let the DAO system know of databases that will be used by the program.
boolean	isOpen() Check to see if the database supplied exists and is open.
static String[]	listDatabases() Retrieve an array of open databases.
static Database	resetDefaultDatabase() All new DAOs after this point will be placed back in the default database.
void	restore(FileReader fileReader) Restore a database from an XML backup file.
void	restore(String name) Restore a database from an XML backup file.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

fileName

public String fileName

Name of the file that contains this database.

Method Detail

resetDefaultDatabase

public static Database resetDefaultDatabase()
                                     throws IOException

All new DAOs after this point will be placed back in the default database. Needed as associateDatabase() will set the specified base as the new default.

Returns:

the default database object.

Throws:

IOException

isOpen

public boolean isOpen()

Check to see if the database supplied exists and is open. It is a static method because the database supplied may be null.

Returns:

True if database and underlying dataFile exist and the latter is open.

get

public static Database get(String name)
                    throws IOException

retrieve the database for a known file from the cache.

Parameters:

name - File name for the database.

Returns:

object database pointer or null if not already open.

Throws:

IOException

get

public static Database get(String name,
                           boolean readOnly)
                    throws IOException

Let the DAO system know of databases that will be used by the program. If it is not in the cache, open it on disk. If it is not on disk (and not read-only) create it.

Parameters:

name - path name of database.

readOnly - true if database for reading only (dictionary).

Returns:

The database retrieved or opened.

Throws:

IOException

listDatabases

public static String[] listDatabases()

Retrieve an array of open databases. Typically used to dump or back up database contents.

Returns:

A string array of open databases.

closeDatabases

public static void closeDatabases()

Called before program exits to make sure all systems are flushed.

flushDatabases

public static void flushDatabases()

Make sure changes on all open databases are committed to disk for perpetuity.

associate

public com.marringtons.object.Database.Association associate(Class dataClass)

Associate a DAO with a known database database. The index size defaults to 1 million items or a value retrieve from the properties with a key of the class name .indexSize (i.e. com.marringtons.myPackage.myClass.indexSize).

Parameters:

dataClass - class of the object to be persisted in the database

Returns:

association for use.

associate

public com.marringtons.object.Database.Association associate(Class dataClass,
                                                             int indexSizeEstimate)

Associate a DAO with a known database database. Setting the index size only works when the object is first introduced to the database.

Parameters:

dataClass - class of the object to be persisted in the database

indexSizeEstimate - a guess on number of records that require indexing.

Returns:

association for use.

backup

public String backup()
              throws IllegalArgumentException,
                     IOException,
                     IllegalAccessException,
                     InstantiationException

Back up the complete default database

Returns:

file name of file created.

Throws:

IOException

InstantiationException

IllegalAccessException

IllegalArgumentException

backup

public String backup(ZipOutputStream zip)
              throws IllegalArgumentException,
                     IOException,
                     IllegalAccessException,
                     InstantiationException

Back up the complete default database to a unique file as XML.

Parameters:

zip - stream to write XML to backup to using the database name

Returns:

file name of file created.

Throws:

IOException

InstantiationException

IllegalAccessException

IllegalArgumentException

restore

public void restore(FileReader fileReader)
             throws XMLexception,
                    IOException

Restore a database from an XML backup file. The database is closed then deleted before the restore. Next time an item from the database is accessed it will be reopened. It is essential that this routine be called in a single-user environment without any chance of another thread requiring the data. Note that a restore not only restores a database to a known state, it also cleans it up - compressing and defragmenting the resident data. The file may be inside an archive or part of the file system.

Parameters:

fileReader - stream containing XML backup

Throws:

IOException

XMLexception

clear

public void clear()
           throws IOException

Empty database of contents. Used by tests and restore to start fresh.

Throws:

IOException

restore

public void restore(String name)
             throws XMLexception,
                    IOException

Restore a database from an XML backup file. The database is closed then deleted before the restore. Next time an item from the database is accessed it will be reopened. It is essential that this routine be called in a single-user environment without any chance of another thread requiring the data. Note that a restore not only restores a database to a known state, it also cleans it up - compressing and defragmenting the resident data. The file may be inside an archive or part of the file system.

Parameters:

name - of XML backup file

Throws:

IOException

XMLexception