net.sourceforge.pain.db
Class PainDB

java.lang.Object
  net.sourceforge.pain.db.PainDB

public final class PainDB

extends java.lang.Object

PAiN Db is a not thread safe semi-object oriented main memory and very buggy database.
PAiN Db is used by PAiN Mud Codebase as persistence engine.
However, PAiN DB is general purpose database, it has great performance,
it's simple, opensource and could be used in any java based opensource projects.
Distributed under the GPL licence

Field Summary

boolean	ALLOW_PLAIN_WRITE allows use setters outside from transactions -> could not be rolled back (performance issue) but if database will be closed before flush, this changes will be lost
static java.lang.String	DB_VERSION
boolean	MANUAL_FLUSH_MODE MANUAL_FLUSH mode is a kind of delayed commit, user should manually call flush (outside of transaction) to flush all data to disk, if MANUAL_FLUSH_MODE is false every time T1(upper level) transaction commited PainDB will automatically call flush method.

Constructor Summary

PainDB(java.lang.String fileName)
Opens specified database file.

Method Summary

void	backupTo(java.lang.String backupFileName, boolean withFlush) Creates database backup file withFlush should be false if this method is called inside of transaction (database image created with last flush will be used)
void	beginTransaction() starts the database transaction.
void	close() closes database.
void	commitTransaction() commits the database transaction.
java.lang.Object	execute(DbTransaction trans) same as execute(trans, null);
java.lang.Object	execute(DbTransaction trans, java.lang.Object[] params) Executes transaction.
void	exportToXml(java.lang.String fileName) Exports all database data to XML file.
java.util.Iterator	extentIterator(java.lang.Class clazz)
protected void	finalize()
void	flush() flushes all changes done after previous flush to disk Called automatically after each upper level transaction commit if MANUAL_FLUSH_MODE is false
void	forceClose() forces database to close.
DbClass	getClass(java.lang.Object classId)
DbClass	getDbClass(java.lang.Class javaClazz)
java.util.Iterator	getDbClassesIterator()
java.lang.String	getDbFileName()
long	getDBFileSize()
int	getNumberOfObjectsInDb()
DbObject	getObject(java.lang.Object objectId)
DbObject	getRoot() root is a simple mark on object, It's allowed to do not have root in DB.
static PainDB	importFromXml(java.lang.String xmlFileName, java.lang.String resultDbFileName) Creates new database instance, fills it with data from given XML file.
boolean	isClosed()
boolean	isDatabaseEmpty()
void	rollbackTransaction()
void	setRoot(DbObject obj) root is a simple mark on object, db could have not root at all, any time user can null this mark

Methods inherited from class java.lang.Object

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

Field Detail

DB_VERSION

public static final java.lang.String DB_VERSION

See Also:

Constant Field Values

ALLOW_PLAIN_WRITE

public boolean ALLOW_PLAIN_WRITE

allows use setters outside from transactions -> could not be rolled back (performance issue) but if database will be closed before flush, this changes will be lost

MANUAL_FLUSH_MODE

public boolean MANUAL_FLUSH_MODE

MANUAL_FLUSH mode is a kind of delayed commit, user should manually call flush (outside of transaction) to flush all data to disk, if MANUAL_FLUSH_MODE is false every time T1(upper level) transaction commited PainDB will automatically call flush method. 'plain writes' always should be flushed manually

Constructor Detail

PainDB

public PainDB(java.lang.String fileName)
       throws java.lang.Exception

Opens specified database file. Creates if file do not exists.

Parameters:

fileName - - name of database file

Throws:

java.lang.Exception - - if file is corrupted or is not paindb database file

Method Detail

flush

public void flush()
           throws java.io.IOException

flushes all changes done after previous flush to disk Called automatically after each upper level transaction commit if MANUAL_FLUSH_MODE is false

Throws:

java.io.IOException - if any IO error occurs.

java.lang.RuntimeException - if there is active transaction

getClass

public DbClass getClass(java.lang.Object classId)

Parameters:

classId - - OID of the DbClass

Returns:

DbClass instance or null if no DbClass with specified classId found

getObject

public DbObject getObject(java.lang.Object objectId)

Parameters:

objectId - - serialized unique object id

Returns:

DbObject for specified objectId or null if no object found

close

public void close()

closes database. All database objects are DETACHED after this method call flushes all changes if MANUAL_FLUSH_MODE = true; Database should not have active transaction during this method call

getDbClass

public DbClass getDbClass(java.lang.Class javaClazz)

getRoot

public DbObject getRoot()

root is a simple mark on object, It's allowed to do not have root in DB.

Returns:

database root object

setRoot

public void setRoot(DbObject obj)

root is a simple mark on object, db could have not root at all, any time user can null this mark

getDBFileSize

public long getDBFileSize()
                   throws java.io.IOException

Returns:

database file size

Throws:

java.io.IOException - if any IO error occured during this method call

isDatabaseEmpty

public boolean isDatabaseEmpty()

Returns:

true for just created database or for database without objects created

getNumberOfObjectsInDb

public int getNumberOfObjectsInDb()

Returns:

number of all objects, including classes.

finalize

protected void finalize()

beginTransaction

public void beginTransaction()

starts the database transaction. Recurrent calls of this method without commit will create subtransactions. Its recommended to use DbTransaction wrapper class and do not call this method manually

commitTransaction

public void commitTransaction()
                       throws java.io.IOException

commits the database transaction. Its recommended to use DbTransaction wrapper class and do not call this method manually This method will automatically flush all changes to disk if there no upperlevel transaction and MANUAL_FLUSH_MODE was not set

Throws:

java.io.IOException - if any IO problem occurs during flush

rollbackTransaction

public void rollbackTransaction()

execute

public java.lang.Object execute(DbTransaction trans)
                         throws java.lang.Exception

same as execute(trans, null);

Throws:

java.lang.Exception

execute

public java.lang.Object execute(DbTransaction trans,
                                java.lang.Object[] params)
                         throws java.lang.Exception

Executes transaction.

Parameters:

params - passed to DbTransaction.execute() method

Returns:

result of the DbTransaction execute method}

Throws:

java.lang.Exception - if it was thrown in DbTransaction.execute method or if write error on flush occurs

getDbFileName

public java.lang.String getDbFileName()

Returns:

database file name

isClosed

public boolean isClosed()

Returns:

true if database was closed

forceClose

public void forceClose()

forces database to close. All active transactions will be rolled back

backupTo

public void backupTo(java.lang.String backupFileName,
                     boolean withFlush)
              throws java.io.IOException

Creates database backup file
withFlush should be false if this method is called inside of
transaction (database image created with last flush will be used)

Parameters:

backupFileName - file name for backup

withFlush - - if true database flush precede to backup

Throws:

java.io.IOException

exportToXml

public void exportToXml(java.lang.String fileName)
                 throws java.io.IOException

Exports all database data to XML file.
encodes with BASE64 binary fields values
keeps objects identities

Parameters:

fileName - = XML file name to export

Throws:

java.io.IOException

importFromXml

public static PainDB importFromXml(java.lang.String xmlFileName,
                                   java.lang.String resultDbFileName)
                            throws java.lang.Exception

Creates new database instance, fills it with data from given XML file.
all objects keeps identity.

Parameters:

xmlFileName - - XML file with database image to import

resultDbFileName - - name if result database file.

Returns:

new database instance

Throws:

java.lang.Exception

getDbClassesIterator

public java.util.Iterator getDbClassesIterator()

extentIterator

public java.util.Iterator extentIterator(java.lang.Class clazz)