doc
documentation of the current features of db4o 1.0
...and how to use them

This file is a short tutorial to get a quick start.
20 samples in com.db4o.samples show the usage of all features in practice.
See the JavaDocs for the complete list of functions.

Contents
Installation
Compatible classes
Start
Storing, Retrieving and Updating Objects
Navigation
Data File
JDK
JDBC
Version
Updates
Legal notice
License
About

Installation
Extract the downloaded file db4o.zip to a directory of your choice.
This file readme.html will also be found there.
Add the file db4o.jar with it's complete path to your CLASSPATH setting.


Compatible classes
db4o stores objects of classes with public default constructors and their fields as follows:
objects of classes with public default constructors
interface
simple type
wrapper of simple type
java.util.Date
arrays of all of the above

All JDK 1.x versions of db4o:
Fields have to be declared public, to allow them to be found and modified by reflection. 

Declare members transient to avoid persistency.


Start
Start the engine by requesting an ObjectContainer from the Db4o factory class. Specifiy the full path to the database file as a parameter.

import com.db4o.*;
ObjectContainer db = Db4o.openFile("yourfile.yap");

The database file will be created, if is not present.

db.close();
stops the engine and flushes all data to the file.


Storing, Retrieving and Updating Objects
To store or update an object:

db.set(Object object);


To obtain an ObjectSet of objects that match a given template object:

ObjectSet set = db.get(Object template);

All members instantiated on the template will also be instantiated on retrieved objects.


Iterate through the ObjectSet to access single objects.

while(set.hasNext()){
   Object resultObject = set.next()
}


Navigation
Upon a call to ObjectContainer.get() object members not instantiated on the template are instantiated on the result objects in DEACTIVATED state.

In DEACTIVATED state, all members of a persistent object are NULL.

DEACTIVATED objects can be activated with subsequent calls to the ObjectContainer:
db.activate(Object);

During the activation of objects their members are also instantiated in DEACTIVATED state.

The mechanism is intended to allow control of instantiation and to traverse the entire graph of persistent objects.

Call  db.deactivate(Object); to save memory.


Data File
To migrate your data between versions and for connectivity to other worlds, we provide an interface to JDBC SQL databases. Further details can be found in the jdbc documentation.


JDK
db4o runs on all JDKs from JDK 1.1.x to present.
The special JDK 2 version supports storing private and protected fields.


JDBC
db4o provides an interface to export and import data via JDBC.
See the jdbc documentation.


Version
A call to Db4o.version() returns a string with the version of db4o, that you are using.


Updates
visit http://www.db4o.com
 Join the db4o mailing list to be kept informed.


Legal notice
IF YOU DO NOT AGREE TO THE TERMS OF THIS AGREEMENT, DO NOT USE THIS SOFTWARE

Software is copyrighted.

db4o software is the intellectual property of db4o, http://www.db4o.com, Carl Rosenberger, Happerger Strasse 18, 82547 Eurasburg, Germany. The author retains the copyright, title and ownership of the provided software.

The provided software may be used and redistributed in non-commercial applications. The right is limited to the current version of the software and does not include the right to upgrades, updates or further developed versions.

You are not permitted to sell, lease, decompile or modify db4o software or any portions thereof without the permission of the author.

db4o SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY OR LIABILITY.

THE ENTIRE RISK AS TO THE RESULTS OF THE USAGE OF THE SOFTWARE IS ASSUMED BY YOU.


License
Please contact sales@db4o.com if you plan to include db4o in a commercial product.
A price list is available on the website.


About
Should you have any questions, ideas or bugreports, please feel free to send an email.

---