Java Object DBMS

Tom Gibson

October 11, 2002

SourceForge Logo

CVS link

Table of Contents

Goals 1

Current Architecture 1

Packages 1

Object details 2

Interobject references 2

GUI stuff 2

Pre-processors 3

Status of the code 3

Documentation 3

Programming tools 3

Roadmap 3


A simple object dbms, based on java serialization. Programmer ease of use is achieved via a simple API. A jodbms will hold multiple objects from multiple classes, automatically building keys to each stored object. Keys are defined at setup time, and are subsequently automatically maintained. Integrity constraints are maintained by key criteria, also defined at setup time.

Heavy use of introspection lightens the programmer burden on all this. Examples:

Keys are automatically maintained by invoking methods declared to provide key values.

A retrieved list of objects of one class are automatically made available as a TableModel by looking for appropriate get/is methods.

The keys declarations and all current key values can be retrieved as a TreeModel.

The code is well layered. Heavy layers are each in their own package, and lighter layering is within the packages.

Current Architecture


Package db has low level dbms functionality: buffers, pages, large and small binary objects. Its highest level is BlobStore which implements keyed binary large objects as java Input/OutputStreams. It keeps an available page list, always using these in preference to growing the file. And it keeps a root key, which is just a long integer that can be used any way a higher layer chooses. Its intended use, however, is the key to some root Blob.

Package odb builds on db to provide a keyed object store. Creating a new store creates a file, and initializes it to receive arbitrary unkeyed objects. Through its API you can add, remove, and modify objects. It keeps a valid OID list. Without keys, you would request that list and iterate through it to retrieve all objects.

Adding keys puts a bit of sanity on the object store. Through the API you declare key-criteria, keys, and assemble the keys into a rooted tree. That is done once at database create time, although subsequent modification to the key structure is possible. The key structure is stored into the database. Once established, then key maintainance is automatic. Adding an object adds values to the key structure, removal removes key values, and even modifying an object modifies key values by both addition and subtraction as necessary.

Keys accomplish two things: integrity and database partitioning.

Integrity: when keys are present, any object added must past muster with all key-criteria, or it is rejected and an appropriate exception thrown. These integrity constraints can be arbitrarily complex. Although a few simple key-criteria are provided, applications can provide there own as the API to both key's and key-criteria are defined as interfaces. The provided keys serve as models how to do this.

And partitioning is what we expect of keys. Given a key value, a subset of the database matches that criteria somehow and that subset is retrieved, or is subjected to further key-criteria.

Object details

Any serializable object can be put into a jodbms store. There is no requirement that it derive from a base class, or that it implement anything other than serializable. To work at this level you would use the OID's to manipulate the store.

That said, we do supply an interface that if implemented by your persistent objects can make a number of things easier. Without this interface you manipulate via OID's. With this interface implemented you can manipulate entirely via your objects and never need to even know about OID's.

A base class is supplied that implements the interface. If you can extend from the base class you have no work to do at all. But if you must implement the interface, then just copy the code from this base class into your object. Almost as easy.

Interobject references

Aprimary object in the database can have references to other primary objects by embedding an OID. Make the reference private (as all data should be) and include setters and getters that return the referenced object. The setters and getters turn out to be one-liners, so this is no big deal. Outside the referencing object, the OID is invisible so using code is unaware that a retrieval may occur.

GUI stuff

The gui stuff is modest, and will probably stay that way. Basically the key structure with current values can be retrieved as a TreeModel, and a Class object and List of OID's of that class can be wrapped into into a TableModel.


There is none. The code in your application is the code you write.

Status of the code

Its in sourceforge CVS, project jodbms. This includes extensive test scripts and expected results, so if you modify stuff you can quickly determine what you have broken. The tests are based on a test-engine-of-yore that predates JUnit, so you will need to also check out the test engine. Project jodbms has two root projects, Database and Test. Get and install them both. Test, by the way, is just the test engine. The database test scripts and expected results are all in Database.


There is an architecture document to help in reading and understanding the code. This is available in the sourceforge documents section for the project. The javadocs are extensive. For the API's for each package there is a tutorial.java interface in the package whose sole purpose is a javadoc on how to use the interface. There are a smattering of txt files here and there to explain technical issues in some depth.

Programming tools

A Makefile has the usual targets for unix/gnu/linux programming. When I worked on a win95 box I did not have a make, so I used a bunch of blah.bat files to compile, kick off tests, etc. These are still on sourceforge but I do not keep them up to date anymore. And it was a bit of a pain maintaining them. So if you are on a winXX box, study these and modify them until the work for you.

Additionally, of course, you need a standard JDK.


I believe we are ready for release 0.1. The code tests quite well, and the lower layers have not been revised for over a year. You could do significant single threaded, same box (not client server) stuff in its current state. Progressing from this I would propose the following roadmap where the indented items are prerequisite to the major items:

Implement rmi and soap clients. (Help needed):

Make thread safe. Basically a careful eyeball audit and an intelligently designed set of syncronize's is what is needed.

Add interface to permit multiple implementations of odb, specifically localImpl, rmiImpl, and soapImpl.

Transactions with one-level commit/rollback. Hooks are available in db to do this at the page level. (Help needed).


Move gui stuff from tgibson.odb to tgibson.odb.gui package. (Underway, tgibson)

Clean up the gui demo so it is not embarrasing. Base its replacement on the TreeModel and TableModel gui stuff. (Underway, tgibson)

Author a significant demo application. (Help needed).

Integrate into JBOSS. (Help needed).

Add to this roadmap. (Dialog among interested folk needed).