Welcome
db4o is the native Java, .NET and Mono open source object database.
This documentation and tutorial is intended to get you started with db4o and to be a reliable
companion while you develop with db4o. Before you start, please make sure that you have downloaded
the latest db4o distribution from the db4objects website.
You are invited to join the db4o community in the public db4o newsgroup at
news://news.db4odev.com/db4o.users and to ask for help at any time. A searchable archive of
previous postings is available here . You may also find the db4o knowledgebase helpful for keyword
searches.
The db4o Java distribution comes as one zip file, db4o-4.5-java.zip. When you unzip this file, you get
the following directory structure:
This tutorial comes in multiple versions. Make sure that you use the right one for the right purpose.
PDF by iText, generated by Doctor, courtesy of db4objects Inc.
db4o-4.5/doc/tutorial/index.html
This is the interactive HTML tutorial. Examples can be run "live" against a db4o database from within
the browser. In order to use the interactive functionality a Java JRE 1.3 or above needs to be installed
and integrated into the browser. Java security settings have to allow applets to be run.
db4o-4.5/doc/tutorial/db4o-4.5-tutorial.pdf
The PDF version of the tutorial allows best fulltext search capabilities.
Java, .NET and Mono
db4o is available for Java, for .NET and for Mono. This tutorial was written for Java. The structure of
the other distributions may be considerably different, so please use the tutorial for the version that
you plan to experiment with first.
1. First Glance
Before diving straight into the first source code samples let's get you familiar with some basics.
1.1. The db4o engine...
The db4o object database engine consists of one single jar file. This is all that you need to program
against. The versions supplied with the distribution can be found in /db4o-4.0/lib/.
db4o-4.0-java1.1.jar
will run with most Java JDKs that supply JDK 1.1.x functionality such as reflection and Exception
handling. That includes many IBM J9 configurations, Symbian and Savaje.
db4o-4.0-java1.4.jar
is built for all Java JDKs between 1.2 and 5.0.
1.2. Installation
If you add one of the above db4o-*.jar files to your CLASSPATH db4o is installed. In case you work
with an integrated development environment like Eclipse (We really recommend Eclipse, it's free.) you
would copy the db4o-*.jar to a /lib/ folder under your project and add db4o to your project as a
library.
Here is how to add the db4o to an Eclipse project
- create a folder named "lib" under your project directory, if it doesn't exist yet
- copy db4o-*.jar to this folder
- Right-click on your project in the Package Explorer and choose "refresh"
- Right-click on your project in the Package Explorer again and choose "properties"
- select "Java Build Path" in the treeview on the left
PDF by iText, generated by Doctor, courtesy of db4objects Inc.
- select the "Libraries" tabpage.
- click "Add Jar"
- the "lib" folder should appear below your project
- choose db4o-*.jar in this folder
- hit OK twice
PDF by iText, generated by Doctor, courtesy of db4objects Inc.
1.3. Object Manager
1.3.1. Installation
The db4o Object Manager, a GUI tool to browse and query database files, is packaged separately for
each supported platform. Choose from the following links in the db4o Download Center for your
platform:
- db4o ObjectManager for Windows IKVM (Java VM included)
- db4o ObjectManager for Windows no Java VM
- db4o ObjectManager for Linux
Once you have downloaded the appropriate Object Manager build, create a folder called Object
Manager in an appropriate location and unpack the downloaded zip file there.
1.3.2. Running
1.3.2.1. Windows IKVM
Object Manager for Windows IKVM includes the open-source IKVM Java virtual machine in the
download. Simply double-click the objectmanager.bat file to start Object Manager.
1.3.2.2. Windows no Java VM
This build assumes that your computer already has a Sun Java Virtual Machine version 1.3 or later
installed and that your operating system path already lists the directory containing your java.exe file.
If this is true, you can simply double-click the objectmanager.bat file to start Object Manager.
Otherwise, you will need to edit objectmanager.bat and specify the full path and file name for your
java.exe file on the first line.
1.3.2.3. Linux
This build assumes that your computer already has a Sun Java Virtual Machine version 1.3 or later
installed and that your PATH variable already lists the directory containing the java binary. If this is
not the case, you will
need to edit the objectmanager.sh file and specify the full path and file name of the Java binary on the
"export VMEXE" line". Since the zip archive does not preserve the executable permissions for
objectmanager.sh, you will need
to `chmod +x objectmanager.sh`. Once this is complete, running objectmanager.sh will start Object
Manager.
PDF by iText, generated by Doctor, courtesy of db4objects Inc.
1.4. API
The API documentation for db4o is supplied as JavaDocs in
db4o-4.0/doc/api/index.html. While you read through this tutorial it may be helpful to look into the API
documentation occasionaly. For the start, the packages com.db4o and com.db4o.query are all that you
need to worry about.
Let's take a first brief look at one of the most important interfaces:
com.db4o.ObjectContainer
This will be your view of a db4o database:
- An ObjectContainer can either be a database in single-user mode or a client to a db4o server.
- Every ObjectContainer owns one transaction. All work is transactional. When you open an
ObjectContainer, you are in a transaction, when you commit() or rollback(), the next transaction is
started immediately.
- Every ObjectContainer maintains it's own references to stored and instantiated objects. In doing so, it
manages object identities.
In case you wonder why you only see very few methods in an ObjectContainer, here is why: The db4o
interface is supplied in two steps in two packages, com.db4o and com.db4o.ext for the following
reasons:
- It's easier to get started, because the important methods are emphasized.
- It will be easier for other products to copy the basic db4o interface.
- We hint how a very-light-version of db4o should look like.
Every com.db4o.ObjectContainer object also always is a com.db4o.ext.ExtObjectContainer. You can
cast to ExtObjectContainer or you can call the #ext() method if you want to use advanced features.
