ewe.database
Class SafeDBAccess

java.lang.Object
  ewe.database.SafeDBAccess

public class SafeDBAccess

extends Object

Field Summary

protected EntriesView	anyView
protected File	directory
boolean	disableRestore Set this true to temporarily disable restoring from a backup.
boolean	isUpdating If the Database is open for updating, this will be true.
Lock	lock All operations are synchronized on this lock.
DatabaseMaker	maker This is the DatabaseMaker used to open the Database.
protected String	name
Database	opened This is the currently open Database.
String	openMode If the Database is opened, this is the mode it was opened in.
protected String	previousMode
protected String[]	sortNames
protected int	updateCount
protected Hashtable	views

Constructor Summary

SafeDBAccess(File directory, String dbName, String[] sortNames)
Create a SafeDBAccess object.

Method Summary

boolean	abortUpdate() Abort the update process, close the db and do not rename the temp file to ".db".
boolean	backupExists() Check if a backup for the database exists.
boolean	backupNow() This causes the database to be closed (if it is not open for updating) and then backed up.
boolean	close() Close the database if it is not open for updating.
void	closeCreate() Call this after initializing with openForCreate().
boolean	create(Object initializer) This calls openForCreate() and then calls closeCreate().
protected void	databaseClosed() This is called when the database has been closed.
boolean	databaseExists() Check if the database does exist.
protected void	databaseOpened(Database db, String mode, boolean forUpdate) This gets called when the DB has been successfully opened.
boolean	endUpdate() End the update process.
EntriesView	getAnyView()
Time	getBackupModifiedTime() Return the time the backup was last made.
Time	getDatabaseModifiedTime(Time dest) Return the time the dabase was last modified.
EntriesView	getView(String sortName) This gets the EntriesView created when the Database was opened for the specified sortName.
protected void	makeBackup() This makes a backup of the database.
Database	open(String mode) Open the database in either "r" or "rw" mode.
Database	openForCreate(Object initializer) Open the database for creation only if it does not already exist.
protected void	restore() This restores the dabase from the backup file if one exists.
Database	startUpdate() Close the database if it is open, make a backup and then open it in "rw" mode for updating.
long	timeSinceBackup(Time since) Return the time elapsed in milliseconds between the last backup time and the provided Time.
void	verifyBackup() If no backup exists at all, make it now.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Field Detail

directory

protected File directory

name

protected String name

sortNames

protected String[] sortNames

previousMode

protected String previousMode

updateCount

protected int updateCount

views

protected Hashtable views

anyView

protected EntriesView anyView

opened

public Database opened

This is the currently open Database. It is null if it is not open.

openMode

public String openMode

If the Database is opened, this is the mode it was opened in. If it is open for update, it will be "rw", otherwise it may be "r" or "rw".

isUpdating

public boolean isUpdating

If the Database is open for updating, this will be true.

lock

public Lock lock

All operations are synchronized on this lock.

maker

public DatabaseMaker maker

This is the DatabaseMaker used to open the Database. By default it is the value returned by DatabaseManager.getDefaultDatabaseMaker();, but you can replace it after calling the constructor.

disableRestore

public boolean disableRestore

Set this true to temporarily disable restoring from a backup. If this is true and open() or startUpdate() is called, and the database is either corrupt or missing then an IOException will be thrown instead of a restore from backup.

Constructor Detail

SafeDBAccess

public SafeDBAccess(File directory,
                    String dbName,
                    String[] sortNames)

Create a SafeDBAccess object. After creating it, use open() or startUpdate() to actually open the database.

Parameters:

directory - The directory which contains the database.

dbName - The root name (without the ".db" extension) of the database.

sortNames - an optional set of sortNames for which EntriesView objects will be created.

Method Detail

getView

public EntriesView getView(String sortName)

This gets the EntriesView created when the Database was opened for the specified sortName.

Parameters:

sortName - one of the sortNames provided in the constructor.

Returns:

the created EntriesView or null if the name is incorrect or if the database is not open.

getAnyView

public EntriesView getAnyView()

databaseOpened

protected void databaseOpened(Database db,
                              String mode,
                              boolean forUpdate)

This gets called when the DB has been successfully opened. By default this does nothing.

Parameters:

db - the open database.

mode - the mode it was opened in.

forUpdate - true if has been opened for updating.

databaseClosed

protected void databaseClosed()

This is called when the database has been closed. By default this does nothing.

restore

protected void restore()
                throws IOException

This restores the dabase from the backup file if one exists. The database must be closed before this is done.

Throws:

IOException - if disableRestore is true.

RestoreException - if there is any problem restoring the database, including a missing or invalid backup zip file.

makeBackup

protected void makeBackup()
                   throws BackupException

This makes a backup of the database. The database must be closed for this to work.

Throws:

BackupException - if an error occurs.

close

public boolean close()
              throws IOException

Close the database if it is not open for updating. endUpdate() should be used for when closing after an update.

Returns:

true on successful closing, false if it is currently open for updating.

Throws:

IOException - on an IOError.

open

public Database open(String mode)
              throws IOException

Open the database in either "r" or "rw" mode. This operation cannot be done if the databse is opened for update via startUpdate(). If it is opened for update it will return null.

Parameters:

mode - either "r" or "rw" - any other value will generate an IllegalArgumentException

Returns:

the opened database.

Throws:

IOException - on any IO error.

IllegalArgumentException - if the mode is invalid.

create

public boolean create(Object initializer)
               throws IOException

This calls openForCreate() and then calls closeCreate(). It is only useful if initializer is not null other wise a database with no fields would be created. A NullPointerException is thrown if initializer is null.

Parameters:

initializer - the initializer used to initialize the database, which must be non-null.

Returns:

true if the database was created, false if it was not because it already existed.

Throws:

IOException - if an IO error occurs during creation.

openForCreate

public Database openForCreate(Object initializer)
                       throws IOException

Open the database for creation only if it does not already exist. Make sure you call closeCreate() on the returned Database when complete.

Parameters:

initializer - an optional Object used to initialize the sorts and fields.

Returns:

the open database ready for initialization if it did not exist, or null if it did exist.

Throws:

IOException - if an error occurs.

closeCreate

public void closeCreate()
                 throws IOException

Call this after initializing with openForCreate(). If openForCreate() returned null then do not call this method.

Throws:

IOException

startUpdate

public Database startUpdate()
                     throws IOException

Close the database if it is open, make a backup and then open it in "rw" mode for updating. During the update process the db is renamed to have a ".db_" extension and will not be renamed back until the update is complete via endUpdate().

You can call startUpdate() multiple times but for each call to startUpdate() there must be a corresponding call to endUpdate(). Update mode is only exited when the last endUpdate() is called.

Returns:

the opened database.

Throws:

IOException - if an IO error occurs.

abortUpdate

public boolean abortUpdate()
                    throws IOException

Abort the update process, close the db and do not rename the temp file to ".db". The result of this is that the next time an open is done the backup file will be used.

Returns:

false if it is not in an update, true otherwise.

Throws:

IOException - if an IOException occurs.

endUpdate

public boolean endUpdate()
                  throws IOException

End the update process. This will close the database and rename the ".db_" file back to the ".db" file. After calling this you must call open() again to re-open the database.

Returns:

false if it is not in an update, true otherwise.

Throws:

IOException - if an IOException occurs.

backupNow

public boolean backupNow()
                  throws IOException

This causes the database to be closed (if it is not open for updating) and then backed up. If it was open before it will be re-opened in the same mode as before.

Returns:

true if a backup was done, false if no backup was done because it was in update mode.

Throws:

IOException - if an IO error occurs.

verifyBackup

public void verifyBackup()
                  throws IOException

If no backup exists at all, make it now.

Throws:

IOException - if an IO error occurs.

backupExists

public boolean backupExists()

Check if a backup for the database exists.

Returns:

true if a backup for the database exists.

getBackupModifiedTime

public Time getBackupModifiedTime()

Return the time the backup was last made.

Returns:

the time the backup was last made, or null if the backup does not exist.

timeSinceBackup

public long timeSinceBackup(Time since)

Return the time elapsed in milliseconds between the last backup time and the provided Time.

Parameters:

since - the Time to compare to the backup time, or null to use the current time.

Returns:

the time elapsed in milliseconds between the last backup time and the provided Time, or 0 if the backup time appears more recent than the "since" time or -1 if no backup exists.

databaseExists

public boolean databaseExists()

Check if the database does exist. This will only work if it is not open for update.

Returns:

true if the dabase exists, false if it does not exist or if it is open for update.

getDatabaseModifiedTime

public Time getDatabaseModifiedTime(Time dest)

Return the time the dabase was last modified. This will only work if it is not open for update.

Parameters:

dest - an optional destination Time.

Returns:

the time the database was last modified, or null if the database does not exist or is open for update.