FAQ
Frequently Asked Questions


Contents
I have a technical question. Whom do I ask?
How does db4o behave with large amounts of data?
I would like to license db4o for a commercial product. What are the costs?
Why can't I retrieve the objects that I stored?
Why are objects of certain classes not stored?
Where is the database driver?
What's "activation" and what is it for?
What is db4o actually doing with my objects?
How do I use db4o in a servlet environment or with JSPs?

I have a technical question. Whom do I ask?

Most questions reoccur. If you post to the db4o users group, you will minimize our work.
http://groups.yahoo.com/group/db4o_unmoderated
Other users reading along also get the chance to learn. They might also bring in their experiences.
The db4o team is monitoring the postings and usually answers questions on the same day.

If you do not wish to talk about your technical problems in public, please mail your questions to support@db4o.com.



How does db4o behave with large amounts of data?

We recommend a maximum size of 1 GB per database file. You may however use multiple database files and move and copy objects freely between them. Navigation access times to objects and the performance of access by internal IDs remains constant, no matter how large database files are. Query performance does
drop linearly with an increasing number of objects per class. Since db4o insert performance is extremely good, it is very little effort to conduct your own performance tests with large amounts of data.



I would like to license db4o for a commercial product. What are the costs?

db4o may be freely redistributed in non-commercial applications. As soon as you or someone else has a financial benefit from running the db4o engine, however indirect it may be, licensing costs become due. Since usecases, applications and turnovers differ widely, db4o license fees are negotiated individually. We try to provide equally fair offers to Fortune 100 companies and to shareware developers.
Please contact sales@db4o.com.



Why can't I retrieve the objects that I stored?

First you should check, that your objects have actually been stored, by using com.db4o.tools.Statistics. If the objects are not there, it's another FAQ.

If the objects are there:
Query-By-Example evaluates all non-null fields and all simple type variables that do not hold their default values against the stored objects. Check to make sure that you are not constraining the resultset by accidentally initialising variables on your template objects. Typical places could be:
- Constructors
- Constructors in ancestors of your class
- Static initialisation
- Static initialisation in ancestors of your class.



Why are objects of certain classes not stored?

db4o needs a constructor that it can use. Ideally this is a zero-parameter constructor, necessarily declared public if you are working on JDK versions prior to JDK 1.2. If db4o does not find a zero-parameter constructor, db4o iterates through all other constructors and internally attempts to create an instance of an object by passing appropriate null parameters. If this is successful with any of the present constructors, this constructor is used. Consult the sample code in com.db4o.samples.constructors for a documentation of this behaviour.

db4o supplies a configuration feature to detect problems with constructors. To analyse problems with your code, you may want to turn the following switch before starting the db4o engine:
   Db4o.configure().exceptionsOnNotStorable(true);
There are classes that do not have usable constructors, java.net.URL is an example from the JDK. In this case you have the following options:
- add a zero-parameter constructor specifically for db4o
- derive from the class and add a zero-parameter constructor
- add a custom translator. See the code in com.db4o.samples.translators for examples how this can be done.
If you need to quickly implement a solution for one of the JDK classes and querying members is not an issue, you may choose to use the built in serializable translator. Here is an example, how this is done for java.net.URL:
   Db4o.configure().
     objectClass("java.net.URL").
     translate(new com.db4o.config.TSerializable());
This code needs to be executed before every single start of the db4o engine.



Where is the database driver?

db4o does not need a database driver. All you need to do is add db4o.jar to your CLASSPATH and you are all set to program against the db4o API.



What's "activation" and what is it for?

Let's explain this with an example:
Consider that you retrieve an object from the database by using a query. This object might have 1000 members, all these 1000 objects might have 1000 members, these have 1000 members in turn and so on....
In the worst case, you have a single root object that indirectly references all other objects in the database. Creating all of these objects could take a very long time and you might experience OutOfMemory problems.

To solve this, db4o introduces a concept of "deactivated" objects:
All of the fields of a "deactivated" object are set to null.
The primitive types hold their default values respectively.

In db4o terms, loading the fields with the stored values from the database is called "activation".

db4o provides an API, to configure how activation is to behave. You can set a global activation depth and override the behaviour individually for specific classes:
Db4o.configure().activationDepth(int)
Db4o.configure().objectClass("yourClass").minimumActivationDepth(int)
Db4o.configure().objectClass("yourClass").maximumActivationDepth(int)
 By default, Db4o is configured with a standard activation depth of 5.

The term "depth" means:
"number of member references away from the original object"

Here is an example. Consider you have a default activation depth of 3. If you retrieve an object:
object.member1.member2.member3 will be instantiated.
"member3" will be present but deactivated.

You can use manual activation to instantiate individual objects:
ObjectContainer#activate(object, depth);
Manual deactivation may be used to save memory:
ObjectContainer#deactivate(object, depth);

By configuring db4o you have full control over how you want db4o to behave. The two extremes:
- using an activationDepth of Integer.MAX_VALUE let's you forget about manual activation but you might not have the best performance and memory footprint
- using an activationDepth of 0 and activating and deactivating all objects manually keeps memory consumption extremely low on a low-memory-device.



What is db4o actually doing with my objects?

Finding out is very simple:
Call Db4o.configure().messageLevel(4); before opening a database file and everything that is happening will be logged to the console. Use Db4o.configure().setOut(); to redirect output to a PrintStream of your choice.


How do I use db4o in a servlet environment or with JSPs?

db4o comes with a special interface for stateless servlet sessions:
ExtDb4o.objectContainer(ServletContext, HttpSession, databaseFile);
takes care of all issues:
- creating or opening the database file on demand
- associating the open file with the ServletContext and the running Session
- closing the database file when the last session is terminated
- closing and reopening the database file when the servlet application code is changed in a running session and db4o needs to adjust to a modified ClassLoader.

Since there may be problems with the reachability of classes from different ClassLoaders, we recommend to place db4o.jar into the ../WEB-INF/lib/ directory of the respective application.