arlut.csd.ganymede
Class DBStore

java.lang.Object
  |
  +--arlut.csd.ganymede.DBStore

public final class DBStore

extends java.lang.Object

DBStore is the main Ganymede database class. DBStore is responsible for actually handling the Ganymede database, and manages database loads and dumps, locking (in conjunction with DBSession and DBLock), the journal, and schema dumping.

The DBStore class holds the server's namespace and schema dictionaries, in the form of a collection of DBNameSpace and DBObjectBase objects. Each DBObjectBase contains schema information for an object type, including field definitions for all fields that may be stored in objects of that type.

In addition to holding schema information, each DBObjectBase contains an Invid-keyed hash of DBObject's of that type in memory after the database loading is complete at start-up. Changes made to the DBStore are done in transactional contexts using DBSession, which is responsible for initiating journal changes when individual transactions are committed to the database. Periodically, the Ganymede server's GanymedeScheduler task engine will schedule a full dump to consolidate the journal and update the on-disk database file. The server will also do a dump when the server's admin console GanymedeAdmin interface initiates a server shutdown.

DBStore was originally written with the intent of being able to serve as a stand-alone in-process transactional object storage system, but in practice, DBStore is now thoroughly integrated with the rest of the Ganymede server, and particularly with GanymedeSession. Various component classes (DBSession, DBObject, and DBField), assume that there is usually an associated GanymedeSession to be consulted for permissions and the like.

Field Summary

(package private) java.util.Hashtable	backPointers hash mapping Invid's to Hashtables of Invid's.
(package private) static arlut.csd.ganymede.DBStore	db We're going to just have a singleton
(package private) static boolean	debug Enable/disable debug in the DBStore methods
(package private) byte	file_major Major revision number of the database file loaded by this DBStore object.
(package private) byte	file_minor Minor revision number of the database file loaded by this DBStore object.
(package private) static java.lang.String	id_string All ganymede.db and ganymede.schema files will start with this string
(package private) arlut.csd.ganymede.DBJournal	journal The Journal for this database, initialized when the database is loaded.
(package private) boolean	loading if true, DBObjectBase set methods will be enabled
arlut.csd.ganymede.DBLockSync	lockSync A separate object to act as a synchronization monitor for DBLock code.
(package private) static byte	major_version Major file version id..
(package private) static byte	major_xml_version XML version major id
(package private) static byte	minor_version Minor file version id..
(package private) static byte	minor_xml_version XML version minor id
(package private) java.util.Vector	nameSpaces A collection of DBNameSpaces registered in this DBStore.
(package private) java.util.Hashtable	objectBases hash mapping object type to DBObjectBase's
(package private) int	objectsCheckedOut A count of how many database objects in this DBStore are currently checked out for creation, editing, or removal.
(package private) arlut.csd.ganymede.DBBaseCategory	rootCategory Root of the category tree defined in this database

Constructor Summary

DBStore()
This is the constructor for DBStore.

Method Summary

(package private) void	addLock() Increments the count of held locks for the admin consoles.
(package private) void	checkIn() Decrements the count of checked-out objects for the admin consoles.
(package private) void	checkOut() Increments the count of checked-out objects for the admin consoles.
private arlut.csd.ganymede.DBEditObject	createSysEventObj(arlut.csd.ganymede.DBSession session, java.lang.String token, java.lang.String name, java.lang.String description, boolean ccAdmin) Convenience method for initializeObjects().
void	debugBackPointers()
private java.lang.String	describe(arlut.csd.ganymede.Invid x)
void	dump(java.lang.String filename, boolean releaseLock, boolean archiveIt) Dumps the database to disk
void	dumpXML(java.io.OutputStream outStream, boolean dumpDataObjects, boolean dumpSchema) Dumps the database and/or database schema to an OutputStream as an XML file
void	dumpXML(java.lang.String filename, boolean dumpDataObjects, boolean dumpSchema) Dumps the database to disk as an XML file
private boolean	exists(arlut.csd.ganymede.DBSession session, arlut.csd.ganymede.Invid invid) Convenience method for initializeObjects().
java.util.Vector	getBaseNameList() Returns a vector of Strings, the names of the bases currently defined in this DBStore.
java.util.Vector	getBases() Returns a vector of DBObjectBases currently defined in this DBStore.
arlut.csd.ganymede.CategoryNode	getCategoryNode(java.lang.String pathName) Method to get a category from the category list, by it's full path name.
arlut.csd.ganymede.DBNameSpace	getNameSpace(java.lang.String name) Method to locate a registered namespace by name.
arlut.csd.ganymede.DBObjectBase	getObjectBase(short id) Returns the object definition class for the id class.
arlut.csd.ganymede.DBObjectBase	getObjectBase(java.lang.Short id) Returns the object definition class for the id class.
arlut.csd.ganymede.DBObjectBase	getObjectBase(java.lang.String baseName) Returns the object definition class for the id class.
(package private) void	initializeObjects() Creates required objects when a new database is created from scratch, or if a pre-existing but damaged database file is loaded..
(package private) void	initializeSchema() Initialization method for a newly created DBStore..
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	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.
void	load(java.lang.String filename) Load the database from disk.
void	load(java.lang.String filename, boolean loadJournal) Load the database from disk.
void	printBases(java.io.PrintWriter out) Do a printable dump of the object databases
void	printCategoryTree(java.io.PrintWriter out) Dumps a text representation of this database's category hierarchy, starting at the root DBBaseCategory.
void	printCategoryTreeHTML(java.io.PrintWriter out) Dumps an HTML representation of this database's category hierarchy, starting at the root DBBaseCategory.
(package private) void	removeLock() Decrements the count of held locks for the admin consoles.
void	setBase(arlut.csd.ganymede.DBObjectBase base) Method to replace/add a DBObjectBase in the DBStore.
private static boolean	setDBSingleton(arlut.csd.ganymede.DBStore store) Convenience synchronized function to set the singleton DBStore db member in the DBStore class.
static arlut.csd.ganymede.DBObject	viewDBObject(arlut.csd.ganymede.Invid invid) Convenience function to find and return objects from the database without having to go through the GanymedeSession and DBSession layers.

Methods inherited from class java.lang.Object

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

Field Detail

id_string

static final java.lang.String id_string

All ganymede.db and ganymede.schema files will start with this string

See Also:

Constant Field Values

major_version

static final byte major_version

Major file version id.. will be first byte in ganymede.db/ganymede.schema after id_string

See Also:

Constant Field Values

minor_version

static final byte minor_version

Minor file version id.. will be second byte in ganymede.db/ganymede.schema after id_string

See Also:

Constant Field Values

major_xml_version

static final byte major_xml_version

XML version major id

See Also:

Constant Field Values

minor_xml_version

static final byte minor_xml_version

XML version minor id

See Also:

Constant Field Values

debug

static boolean debug

Enable/disable debug in the DBStore methods

db

static arlut.csd.ganymede.DBStore db

We're going to just have a singleton

objectBases

java.util.Hashtable objectBases

hash mapping object type to DBObjectBase's

backPointers

java.util.Hashtable backPointers

hash mapping Invid's to Hashtables of Invid's. Used to record the set of Invids that point to a given Invid.

That is, backPointers.get(anInvid) returns a hashtable whose keys are the Invid's that point to that Invid via an asymmetric link.

nameSpaces

java.util.Vector nameSpaces

A collection of DBNameSpaces registered in this DBStore.

loading

boolean loading

if true, DBObjectBase set methods will be enabled

rootCategory

arlut.csd.ganymede.DBBaseCategory rootCategory

Root of the category tree defined in this database

file_major

byte file_major

Major revision number of the database file loaded by this DBStore object.

file_minor

byte file_minor

Minor revision number of the database file loaded by this DBStore object.

journal

arlut.csd.ganymede.DBJournal journal

The Journal for this database, initialized when the database is loaded.

lockSync

public arlut.csd.ganymede.DBLockSync lockSync

A separate object to act as a synchronization monitor for DBLock code.

objectsCheckedOut

int objectsCheckedOut

A count of how many database objects in this DBStore are currently checked out for creation, editing, or removal.

Constructor Detail

DBStore

public DBStore()

This is the constructor for DBStore.

Currently, once you construct a DBStore object, all you can do to initialize it is call load(). This API needs to be extended to provide for programmatic bootstrapping, or another tool needs to be produced for the purpose.

Method Detail

viewDBObject

public static arlut.csd.ganymede.DBObject viewDBObject(arlut.csd.ganymede.Invid invid)

Convenience function to find and return objects from the database without having to go through the GanymedeSession and DBSession layers.

This method provides a direct reference to an object in the DBStore, without exporting it for remote RMI reference and without doing any permissions setting.

setDBSingleton

private static boolean setDBSingleton(arlut.csd.ganymede.DBStore store)

Convenience synchronized function to set the singleton DBStore db member in the DBStore class.

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.

load

public void load(java.lang.String filename)

Load the database from disk.

This method loads both the database type definition and database contents from a single disk file.

Parameters:

filename - Name of the database file

See Also:

DBJournal

load

public void load(java.lang.String filename,
                 boolean loadJournal)

Load the database from disk.

This method loads both the database type definition and database contents from a single disk file.

Parameters:

filename - Name of the database file

loadJournal - if true, process and consolidate the journal on loading.

See Also:

DBJournal

dump

public void dump(java.lang.String filename,
                 boolean releaseLock,
                 boolean archiveIt)
          throws java.io.IOException

Dumps the database to disk

This method dumps the entire database to disk. The thread that calls the dump method will be suspended until there are no threads performing update writes to the in-memory database. In practice this will likely never be a long interval. Note that this method *will* dump the database, even if no changes have been made. You should check the DBStore journal's isClean() method to determine whether or not a dump is really needed, if you're not sure.

The dump is guaranteed to be transaction consistent.

Parameters:

filename - Name of the database file to emit

releaseLock - boolean. If releaseLock==false, dump() will not release the dump lock when it is done with the dump. This is intended to allow for a clean shut down. For non-terminal dumps, releaseLock should be true.

archiveIt - If true, dump will create a zipped copy of the previously existing ganymede.db file in an 'old' directory under the location where ganymede.db is held.

java.io.IOException

See Also:

DBEditSet, DBJournal

dumpXML

public void dumpXML(java.lang.String filename,
                    boolean dumpDataObjects,
                    boolean dumpSchema)
             throws java.io.IOException

Dumps the database to disk as an XML file

This method dumps the entire database to disk. The thread that calls the dump method will be suspended until there are no threads performing update writes to the in-memory database. In practice this will likely never be a long interval. Note that this method *will* dump the database, even if no changes have been made. You should check the DBStore journal's isClean() method to determine whether or not a dump is really needed, if you're not sure.

The dump is guaranteed to be transaction consistent.

Parameters:

filename - Name of the database file to emit

dumpDataObjects - If true, the emitted file will include the objects in the Ganymede database.

dumpSchema - If true, the emitted file will include the schema definition

java.io.IOException

See Also:

DBEditSet, DBJournal

dumpXML

public void dumpXML(java.io.OutputStream outStream,
                    boolean dumpDataObjects,
                    boolean dumpSchema)
             throws java.io.IOException

Dumps the database and/or database schema to an OutputStream as an XML file

This method dumps the entire database to the OutputStream. The thread that calls the dump method will be suspended until there are no threads performing update writes to the in-memory database. In practice this will likely never be a long interval. Note that this method *will* dump the database, even if no changes have been made. You should check the DBStore journal's isClean() method to determine whether or not a dump is really needed, if you're not sure.

The dump is guaranteed to be transaction consistent.

Parameters:

outStream - Stream to write the XML to @param dumpDataObjects if false, only the schema definition will be written

dumpDataObjects - If true, the emitted file will include the objects in the Ganymede database.

dumpSchema - If true, the emitted file will include the schema definition

java.io.IOException

See Also:

DBEditSet, DBJournal

printCategoryTreeHTML

public void printCategoryTreeHTML(java.io.PrintWriter out)

Dumps an HTML representation of this database's category hierarchy, starting at the root DBBaseCategory.

Parameters:

out - PrintStream to print to

printCategoryTree

public void printCategoryTree(java.io.PrintWriter out)

Dumps a text representation of this database's category hierarchy, starting at the root DBBaseCategory.

Parameters:

out - PrintStream to print to

printBases

public void printBases(java.io.PrintWriter out)

Do a printable dump of the object databases

Parameters:

out - PrintStream to print to

getBaseNameList

public java.util.Vector getBaseNameList()

Returns a vector of Strings, the names of the bases currently defined in this DBStore.

getBases

public java.util.Vector getBases()

Returns a vector of DBObjectBases currently defined in this DBStore.

getObjectBase

public arlut.csd.ganymede.DBObjectBase getObjectBase(java.lang.Short id)

Returns the object definition class for the id class.

Parameters:

id - Type id for the base to be returned

getObjectBase

public arlut.csd.ganymede.DBObjectBase getObjectBase(short id)

Returns the object definition class for the id class.

Parameters:

id - Type id for the base to be returned

getObjectBase

public arlut.csd.ganymede.DBObjectBase getObjectBase(java.lang.String baseName)

Returns the object definition class for the id class.

Parameters:

baseName - Name of the base to be returned

setBase

public void setBase(arlut.csd.ganymede.DBObjectBase base)

Method to replace/add a DBObjectBase in the DBStore.

getNameSpace

public arlut.csd.ganymede.DBNameSpace getNameSpace(java.lang.String name)

Method to locate a registered namespace by name.

getCategoryNode

public arlut.csd.ganymede.CategoryNode getCategoryNode(java.lang.String pathName)

Method to get a category from the category list, by it's full path name.

initializeSchema

void initializeSchema()

Initialization method for a newly created DBStore.. this method creates a new Schema from scratch, defining the mandatory Ganymede object types, registering their customization classes, defining fields, and all the rest.

Note that we don't go through a DBSchemaEdit here, we just initialize the DBObjectBase/ DBObjectBaseField structures manually.

initializeObjects

void initializeObjects()

Creates required objects when a new database is created from scratch, or if a pre-existing but damaged database file is loaded..

exists

private boolean exists(arlut.csd.ganymede.DBSession session,
                       arlut.csd.ganymede.Invid invid)

Convenience method for initializeObjects().

createSysEventObj

private arlut.csd.ganymede.DBEditObject createSysEventObj(arlut.csd.ganymede.DBSession session,
                                                          java.lang.String token,
                                                          java.lang.String name,
                                                          java.lang.String description,
                                                          boolean ccAdmin)

Convenience method for initializeObjects().

checkOut

void checkOut()

Increments the count of checked-out objects for the admin consoles.

checkIn

void checkIn()

Decrements the count of checked-out objects for the admin consoles.

addLock

void addLock()

Increments the count of held locks for the admin consoles.

removeLock

void removeLock()

Decrements the count of held locks for the admin consoles.

debugBackPointers

public void debugBackPointers()

describe

private final java.lang.String describe(arlut.csd.ganymede.Invid x)