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.
It's 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. encodes with BASE64 binary fields values keeps objects identities
protected void	finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
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.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. all objects keeps identity.
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()

Description copied from class: java.lang.Object

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java^TM virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

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