readme |
![]() |
Please do read this very short file completely.
For the fastest start with code, work through the numbered samples in ../com/db4o/samples/
Reading along in the newsgroup at
news://news.db4odev.com/db4o.users
may provide lots of helpful information that is not covered in the
documentation.
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 .java files supplied with the download are public domain and can be used
freely.
Directories
bin | - script 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 |
soda | - 580 test cases for the S.O.D.A. API |
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().objectClass("yourClass").cascadeOnUpdate();
Db4o.configure().updateDepth();
Db4o.configure().objectClass("yourClass").updateDepth();
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").cascadeOnActivate();
Db4o.configure().objectClass("yourClass").minimumActivationDepth();
Db4o.configure().objectClass("yourClass").maximumActivationDepth();
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.
---