readme

Please read this short file thoroughly.

It is recommended to work through the numbered samples in com.db4o.samples for a quick start with db4o.


Contents

Change Log
FAQ
Installation
JavaDocs
Directories
Compatible classes
Opening a database file
Storing and Updating Objects
Retrieving Objects
Deleting Objects
Navigation
JDBC
IDEs
Version
Updates
License
Licensing
Contact Us

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. db4o.jar contains the complete database engine and it is the only library you need to program against. 

All other sourcecode files supplied with the download are public domain and can be used freely.


Directories
bat - batch file examples
com.db4o.bench - benchmark code to compare against relational databases
com.db4o.jgen - class generation code for SQL import runs
com.db4o.lib - library classes needed in the other packages
com.db4o.samples - samples how to use db4o. Working through all the subfolders is highly recommended.
com.db4o.sql - code to export/import to/from SQL databases
com.db4o.test - db4o regression test code. Regression.java is the starting point for execution.
com.db4o.tools - maintenance tools and tools for statistics
doc - documentation files including JavaDocs



Compatible classes
db4o attempts to store all objects of any class. The code in com.db4o.test.types shows some possibilities.

db4o tries to use a public default constructor, if present. If not, db4o will use the first constructor found with getDeclaredConstructor that does not throw an exception upon creating a test instance. It is recommended to create a public zero-parameter constructor to prevent possible side effects. The behaviour is documented in the source code in com.db4o.samples.constructors.

db4o internally uses highly efficient wrappers for:
all simple types, all simple type wrappers, String, Date, arrays, Vector, Hashtable and all JDK2 Collection classes. Using typesafe declarations of the above, will result in better performance.

Limitations if you run your applications on JDK 1.1.x:
(this also includes PersonalJava and EPOC)
- A class needs to have at least one  public constructor.
- Fields have to be declared public, to allow values to be set by reflection. 

Declare members transient to avoid persistency.


Opening a database file
Open a database file by requesting an ObjectContainer from the Db4o factory class. Specify the full path to the database file as a parameter.

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


The database file will be created, if it does not exist.

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


Storing and Updating Objects
To store a new object or to update an existing object call:

container.set(Object object);

If the object has not been previously stored to the database it will be newly added.
If the object was previously stored, it will be updated.

In the default configuration member objects will not be updated but you may
modify this behaviour with the following configuration features:

Db4o.configure().updateDepth();
Db4o.configure().objectClass("yourClass").updateDepth();
Db4o.configure().objectClass("yourClass").cascadeOnUpdate();
Db4o.configure().objectClass("yourClass").objectField("yourField").cascadeOnUpdate();


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

ObjectSet results = container.get(Object template);

All non-null members on the template will be evaluated against stored objects.
Arrays and Collections are evaluated using "contains" comparisons:
A stored Array/Collection will be included in the resulting ObjectSet, if it contains all the values in the template Array/Collection.

Iterate through the ObjectSet to access single objects.

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


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

container.delete(object);

In the default configuration only the object itself and the simple type members will be deleted.
You may configure the behaviour of classes:

Db4o.configure().objectClass("yourClass").cascadeOnDelete();


Navigation
Upon a call to ObjectContainer#get() members are instantiated and activated to a default depth of 5. You may use the following methods to configure the activation depth:

Db4o.configure().activationDepth();
Db4o.configure().objectClass("yourClass").minimumActivationDepth();
Db4o.configure().objectClass("yourClass").maximumActivationDepth();
Db4o.configure().objectClass("yourClass").cascadeOnActivate();
Db4o.configure().objectClass("yourClass").objectField("yourField").cascadeOnActivate();

Members further down the hierarchy will be DEACTIVATED. In DEACTIVATED state, all Object members of an object are NULL, primitive types have the default value of 0.

DEACTIVATED objects can be activated with calls to
ObjectContainer#activate(Object object, int depth)

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

Call ObjectContainer#deactivate(Object object, int depth) to save memory.


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


IDEs  
We recommend the usage of integrated development environments like Eclipse, JBuilder Personal or NetBeans. Remember to add db4o.jar to your project CLASSPATH. Some IDEs like IBM Visual Age disassemble Jar files internally and attempt to compile all sources. In this case you may also need to add Sun's Java Web Start Jar javaws.jar to work with db4o.


Version
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.
The unmoderated users mailing list is open for all discussions around db4o.


Licensing
Visit the db4o website for the most recent pricing policy. As of March 31st 2002:
Access to unrestricted db4o developer versions is available through membership in the db4o developers network. The membership fee for individuals is USD 100.00 per person per year. The company membership fee is USD 1000.00 per company per year. Membership in the db4o developers network entitles to:
- use db4o for development projects and for testing
- download all updates that are released during the membership period.
Redistribution in non-commercial applications is free of charge. Licenses for commercial use and redistribution are negotiated individually. Please contact sales@db4o.com if you plan to include db4o in a commercial product.


Contact Us
Should you have any questions, ideas or bug reports, you are always very welcome to send an email.

---