arlut.csd.ganymede.server

Class DBJournal

java.lang.Object

arlut.csd.ganymede.server.DBJournal

All Implemented Interfaces:

ObjectStatus

public final class DBJournal
extends java.lang.Object
implements ObjectStatus

The DBJournal class is used to provide journalling of changes to the DBStore during operations. The Journal file will contain a complete list of all changes made since the last dump of the complete DBStore. The Journal file is composed of a header block followed by a number of transactions.

Each transaction consists of a number of object modification records, each record specifying the creation, deletion, or modification of a particular object. At the end of the transaction, a marker indicates the completion of the transaction. At DBStore startup time, the journal is read in and all complete transactions recorded are performed on the main DBStore.

Generally, if the DBStore was shut down correctly, the entire memory structure of the DBStore will be cleanly dumped out and the Journal will be removed. The Journal is intended to insure that the DBStore remains transaction consistent if the server running Ganymede crashes during runtime.

See the DBEditSet class for more information on Ganymede transactions.

Nota bene: this class includes synchronized methods which serialize operations on the Ganymede transaction journal. The DBJournal monitor is intended to be the innermost monitor for operations involving the DBStore and DBJournal objects. Synchronized methods in DBJournal must not call synchronized methods on DBStore, as synchronized DBStore methods can and will call methods on DBJournal.

Field Summary

Fields

Modifier and Type	Field and Description
(package private) static java.lang.String	CLOSETRANS
(package private) static byte	CREATE
(package private) static boolean	debug
(package private) static byte	DELETE
(package private) boolean	dirty
(package private) static byte	EDIT
(package private) short	file_dbstore_major_version
(package private) short	file_dbstore_minor_version
(package private) short	file_major_version
(package private) short	file_minor_version
(package private) java.lang.String	filename
(package private) static java.lang.String	FINALIZE
(package private) static java.lang.String	id_string
private DBJournalTransaction	incompleteTransaction
(package private) java.io.RandomAccessFile	jFile
(package private) static short	major_version
(package private) static short	minor_version
(package private) static java.lang.String	OPENTRANS
(package private) static DBStore	store
(package private) int	transactionsInJournal
(package private) static TranslationService	ts TranslationService object for handling string localization in the Ganymede server.

Fields inherited from interface arlut.csd.ganymede.common.ObjectStatus

CREATING, DELETING, DROPPING, EDITING

Constructor Summary

Constructors

Constructor and Description
DBJournal(DBStore store, java.lang.String filename) The DBJournal constructor takes a filename and creates a DBJournal object.

Method Summary

Methods

Modifier and Type	Method and Description
void	clearIncompleteTransaction() After the Ganymede main() method has tried to clean out any remaining bits of the non-finalized transaction, it will need to clear the incompleteTransaction record.
static void	debug(java.lang.String string) This is a convenience method used by server-side code to send debug output to stderr and to any attached admin consoles.
void	finalizeTransaction(DBJournalTransaction transRecord) The finalizeTransaction() method actually performs the full work of writing out a transaction to the DBStore Journal.
DBJournalTransaction	getIncompleteTransaction() If the journal contained a persisted but not finalized transaction when we tried to load it, this method will return a DBJournalTransaction containing enough information that the Ganymede main() method can iterate over the defined sync channels and clear out any lingering xml sync for that transaction.
(package private) static void	initialize(java.io.DataOutput out)
boolean	isAtLeast(int major, int minor) This method returns true if the disk file being loaded by this DBStore has a version number greater than major.minor.
boolean	isAtRev(int major, int minor) This method returns true if the disk file being loaded by this DBStore has a version number equal to major.minor.
boolean	isBetweenRevs(int major1, int minor1, int major2, int minor2) This method returns true if the disk file being loaded by this DBStore has a version number between greater than or equal to major1.minor1 and less than major2.minor2.
boolean	isClean() Returns true if the journal does not contain any transactions.
boolean	isLessThan(int major, int minor) This method returns true if the disk file being loaded by this DBStore has a version number earlier than major.minor.
boolean	load() The load() method reads in all transactions in the current DBStore Journal and makes the appropriate changes to the DBStore Object Bases.
private void	printObject(DBObject obj)
(package private) void	readHeaders() This method is used to read and check the first few fields of the journal as a sanity check on journal open/load.
void	reset() The reset() method is used to copy the journal file to a safe location and truncate it.
static void	setDebug(boolean val)
void	undoTransaction(DBJournalTransaction transRecord) The undoTransaction() method is responsible for rolling back the most recent transaction written to the journal, in the event that writing to the sync channels or finalizing the transaction fails (due to a lack of disk space, presumably).
DBJournalTransaction	writeTransaction(DBEditSet transaction) The writeTransaction() method performs the work of persisting a transaction to the DBStore Journal.

Methods inherited from class java.lang.Object

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

Field Detail

debug

static boolean debug

store

static DBStore store

ts

static final TranslationService ts

TranslationService object for handling string localization in the Ganymede server.

id_string

static final java.lang.String id_string

See Also:

Constant Field Values

major_version

static final short major_version

See Also:

Constant Field Values

minor_version

static final short minor_version

See Also:

Constant Field Values

OPENTRANS

static final java.lang.String OPENTRANS

See Also:

Constant Field Values

CLOSETRANS

static final java.lang.String CLOSETRANS

See Also:

Constant Field Values

FINALIZE

static final java.lang.String FINALIZE

See Also:

Constant Field Values

CREATE

static final byte CREATE

See Also:

Constant Field Values

EDIT

static final byte EDIT

See Also:

Constant Field Values

DELETE

static final byte DELETE

See Also:

Constant Field Values

filename

java.lang.String filename

jFile

java.io.RandomAccessFile jFile

dirty

boolean dirty

file_major_version

short file_major_version

file_minor_version

short file_minor_version

file_dbstore_major_version

short file_dbstore_major_version

file_dbstore_minor_version

short file_dbstore_minor_version

transactionsInJournal

int transactionsInJournal

incompleteTransaction

private DBJournalTransaction incompleteTransaction

Constructor Detail

DBJournal

public DBJournal(DBStore store,
         java.lang.String filename)
          throws java.io.IOException

The DBJournal constructor takes a filename and creates a DBJournal object. If the file named does not exist, the DBJournal constructor will create the file and write the DBJournal header, leaving the file pointer pointing to the end of the file. If the Journal file does exist, the constructor will advance the file pointer to the end of the file.

In either case, the file will be made ready for new transactions to be written.

Throws:

java.io.IOException

Method Detail

setDebug

public static void setDebug(boolean val)

initialize

static void initialize(java.io.DataOutput out)
                throws java.io.IOException

Throws:

java.io.IOException

isAtLeast

public boolean isAtLeast(int major,
                int minor)

This method returns true if the disk file being loaded by this DBStore has a version number greater than major.minor.

isLessThan

public boolean isLessThan(int major,
                 int minor)

This method returns true if the disk file being loaded by this DBStore has a version number earlier than major.minor.

isAtRev

public boolean isAtRev(int major,
              int minor)

This method returns true if the disk file being loaded by this DBStore has a version number equal to major.minor.

isBetweenRevs

public boolean isBetweenRevs(int major1,
                    int minor1,
                    int major2,
                    int minor2)

This method returns true if the disk file being loaded by this DBStore has a version number between greater than or equal to major1.minor1 and less than major2.minor2.

reset

public void reset()
           throws java.io.IOException

The reset() method is used to copy the journal file to a safe location and truncate it. reset() should be called immediately after the DBStore is dumped to disk and before the DumpLock is relinquished.

Throws:

java.io.IOException

load

public boolean load()
             throws java.io.IOException

The load() method reads in all transactions in the current DBStore Journal and makes the appropriate changes to the DBStore Object Bases. This method should be called after the main body of the DBStore is loaded and before the DBStore is put into production mode.

load() will return true if the on-disk journal was in a consistent state, with no incomplete transactions. If load() encounters EOF in the middle of attempting to read in a transaction record, load() will return false. In either case, any valid and complete transaction records will be processed and integrated into the DBStore.

Throws:

java.io.IOException

writeTransaction

public DBJournalTransaction writeTransaction(DBEditSet transaction)
                                      throws java.io.IOException

The writeTransaction() method performs the work of persisting a transaction to the DBStore Journal. writeTransaction() should be called before the changes are actually finalized in the DBStore Object Bases. If writeTransaction() is not able to successfully write the complete transaction log to the Journal file, an IOException will be thrown.

Note that writeTransaction() does not mark the transaction in the on-disk journal file as finalized. If the server is abnormally terminated (or if the disk fills) between the time that writeTransaction() is called and the time that finalizeTransaction() is called, the server on startup will not consider the transaction to have been finally put to rest, and the system will attempt to push the unfinalized change in the journal to the sync channels.

Returns:

On success, a DBJournalTransaction recording the transaction's time stamp and integral transaction number is returned. This DBJournalTransaction can be passed back to finalizeTransaction() when writes to the sync channels are completed.

Throws:

java.io.IOException

finalizeTransaction

public void finalizeTransaction(DBJournalTransaction transRecord)
                         throws java.io.IOException

The finalizeTransaction() method actually performs the full work of writing out a transaction to the DBStore Journal. writeTransaction() should be called before the changes are actually finalized in the DBStore Object Bases. If writeTransaction() is not able to successfully write the complete transaction log to the Journal file, an IOException will be thrown. The Journal entries are structured so that if a Journal entry can't be completed, the transaction's whole entry will be ignored at load time.

Throws:

java.io.IOException

undoTransaction

public void undoTransaction(DBJournalTransaction transRecord)
                     throws java.io.IOException

The undoTransaction() method is responsible for rolling back the most recent transaction written to the journal, in the event that writing to the sync channels or finalizing the transaction fails (due to a lack of disk space, presumably).

Throws:

java.io.IOException

getIncompleteTransaction

public DBJournalTransaction getIncompleteTransaction()

If the journal contained a persisted but not finalized transaction when we tried to load it, this method will return a DBJournalTransaction containing enough information that the Ganymede main() method can iterate over the defined sync channels and clear out any lingering xml sync for that transaction.

This can only happen if the server is abnormally terminated in a very narrow window, but in the one case in 10,000 where an abnormal shutdown hit right in that window, we'll go ahead and worry about it.

clearIncompleteTransaction

public void clearIncompleteTransaction()

After the Ganymede main() method has tried to clean out any remaining bits of the non-finalized transaction, it will need to clear the incompleteTransaction record. This method does that.

isClean

public boolean isClean()

Returns true if the journal does not contain any transactions.

readHeaders

void readHeaders()
           throws java.io.IOException

This method is used to read and check the first few fields of the journal as a sanity check on journal open/load.

This method MUST NOT be called after the journal is open and active, or else the journal will become corrupted.

Throws:

java.io.IOException

printObject

private void printObject(DBObject obj)

debug

public static void debug(java.lang.String string)

This is a convenience method used by server-side code to send debug output to stderr and to any attached admin consoles.