db4o 2.0

com.db4o.config
Interface Configuration


public interface Configuration

configuration interface for db4o.

This interface contains methods to configure db4o. All methods should be called before starting the db4o engine.

Db4o.configure() returns the single global Configuration object.


Method Summary
 void activationDepth(int depth)
          sets the activation depth to the specified value.
 void automaticShutDown(boolean flag)
          turns automatic shutdown of the engine on and off.
 void callbacks(boolean flag)
          turns ObjectCallback methods on and off.
 void classActivationDepthConfigurable(boolean flag)
          turns individual class activation depth configuration on and off.
 void encrypt(boolean flag)
          configures the use of encryption.
 void exceptionsOnNotStorable(boolean flag)
          configures whether Exceptions are to be thrown, if objects can not be stored.
 MessageSender getMessageSender()
          returns the MessageSender for this Configuration context.
 void lockDatabaseFile(boolean flag)
          can be used to turn the database file locking thread off.
 void messageLevel(int level)
          sets the detail level of db4o messages.
 ObjectClass objectClass(java.lang.String className)
          returns an ObjectClass object to configure the specified class.
 void password(java.lang.String pass)
          protects the database file with a password.
 void readOnly(boolean flag)
          turns readOnly mode on and off.
 void refreshClasses()
          forces analysation of all Classes during a running session.
 void setBlobPath(java.lang.String path)
          configures the path to be used to store and read Blob data.
 void setClassLoader(java.lang.ClassLoader classLoader)
          configures db4o to use a custom ClassLoader.
 void setMessageRecipient(MessageRecipient messageRecipient)
          sets the MessageRecipient to receive Client Server messages.
 void setOut(java.io.PrintStream outStream)
          assigns a PrintStream where db4o is to print its event messages.
 void unicode(boolean flag)
          configures the storage format of Strings.
 void updateDepth(int depth)
          specifies the global updateDepth.
 

Method Detail

activationDepth

public void activationDepth(int depth)
sets the activation depth to the specified value.

Why activation?
During the instantiation of stored objects from persistent storage, the instantiation of members needs to be limited to a certain depth. Otherwise a possible root object would completely instantiate all stored objects to memory.

db4o uses a preconfigured "activation depth" of 5.

If an object is returned in an ObjectSet as a result of a query object.member1.member2.member3.member4.member5 will be instantiated. member5 will have all it's members set to null. Primitive types will have the default values respectively. In db4o terminology, the state of member5 is called DEACTIVATED. member5 can be activated by calling ObjectContainer#activate(member5, depth).

Note that raising the global activation depth will consume more memory and have negative effects on the performance of first-time retrievals. Lowering the global activation depth needs more individual activation work but can increase performance of queries.

ObjectContainer#deactivate(Object, depth) can be used to manually free memory by deactivating objects.

Examples: ../com/db4o/samples/activate.

Parameters:
depth - the desired global activation depth.
See Also:
configuring classes individually

automaticShutDown

public void automaticShutDown(boolean flag)
turns automatic shutdown of the engine on and off.

Depending on the JDK, db4o uses one of the following two methods to shut down, if no more references to the ObjectContainer are being held or the JVM terminates:
- JDK 1.3 and above: Runtime.addShutdownHook()
- JDK 1.2 and below: System.runFinalizersOnExit(true) and code in the finalizer.

Some JVMs have severe problems with both methods. For these rare cases the autoShutDown feature may be turned off.

The default and recommended setting is true.

Parameters:
flag - whether db4o should shut down automatically.

callbacks

public void callbacks(boolean flag)
turns ObjectCallback methods on and off.

Callbacks are turned on by default.

Parameters:
flag - false to turn callback methods off
See Also:
ObjectCallbacks

classActivationDepthConfigurable

public void classActivationDepthConfigurable(boolean flag)
turns individual class activation depth configuration on and off.

This feature is turned on by default.

Parameters:
flag - false to turn the possibility to individually configure class activation depths off
See Also:
Why activation?

encrypt

public void encrypt(boolean flag)
configures the use of encryption.

This method needs to be called before a database file is created with the first Db4o.openFile().

If encryption is set to true, you need to supply a password to seed the encryption mechanism.

db4o database files keep their encryption format after creation.

Parameters:
flag - true for turning encryption on, false for turning encryption off.
See Also:
password()

exceptionsOnNotStorable

public void exceptionsOnNotStorable(boolean flag)
configures whether Exceptions are to be thrown, if objects can not be stored.

db4o requires the presence of a constructor that can be used to instantiate objects. If no default public constructor is present, all available constructors are tested, whether an instance of the class can be instantiated. Null is passed to all constructor parameters. The first constructor that is successfully tested will be used throughout the running db4o session. If an instance of the class can not be instantiated, the object will not be stored. By default, execution will continue without any message or error. This method can be used to configure db4o to throw an ObjectNotStorableException if an object can not be stored.

The default for this setting is false.

Parameters:
flag - true to throw Exceptions if objects can not be stored.

getMessageSender

public MessageSender getMessageSender()
returns the MessageSender for this Configuration context.
Returns:
MessageSender the

messageLevel

public void messageLevel(int level)
sets the detail level of db4o messages.

Level 0 - no messages
Level 1 - open and close messages
Level 2 - messages for new, update and delete
Level 3 - messages for activate and deactivate

Parameters:
level - integer from 0 to 3
See Also:
Db4o.setOut(PrintStream)

lockDatabaseFile

public void lockDatabaseFile(boolean flag)
can be used to turn the database file locking thread off.

Since Java does not support file locking up to JDK 1.4, db4o uses an additional thread per open database file to prohibit concurrent access to the same database file by different db4o sessions in different VMs.

To improve performance and to lower ressource consumption, this method provides the possibility to prevent the locking thread from being started.

Caution!
If database file locking is turned off, concurrent write access to the same database file from different JVM sessions will corrupt the database file immediately.

This method has no effect on open ObjectContainers. It will only affect how ObjectContainers are opened.

The default setting is true.

Parameters:
flag - false to turn database file locking off.

objectClass

public ObjectClass objectClass(java.lang.String className)
returns an ObjectClass object to configure the specified class.

Parameters:
className - the fully qualified name of the class to be configured.

Returns:
an instance of an ObjectClass object for configuration.

password

public void password(java.lang.String pass)
protects the database file with a password.

To set a password for a database file, this method needs to be called before a database file is created with the first Db4o.openFile().

All further attempts to open the file, are required to set the same password.

The password is used to seed the encryption mechanism, which makes it impossible to read the database file without knowing the password.

Parameters:
String - the password to be used.

readOnly

public void readOnly(boolean flag)
turns readOnly mode on and off.

This method configures the mode in which subsequent calls to Db4o.openFile() will open files.

Readonly mode allows to open an unlimited number of reading processes on one database file. It is also convenient for deploying db4o database files on CD-ROM.

If mixed access using many readOnly and one readWrite session is used, there is no guarantee that the data in the readOnly sessions will be kept up-to-date.

Parameters:
flag - true for configuring readOnly mode for subsequent calls to Db4o.openFile().

refreshClasses

public void refreshClasses()
forces analysation of all Classes during a running session.

This method may be useful in combination with a modified ClassLoader and allows exchanging classes during a running db4o session.

Calling this method on the global Configuration context will refresh the classes in all db4o sessions in the running VM. Calling this method in an ObjectContainer Configuration context, only the classes of the respective ObjectContainer will be refreshed.

See Also:
setClassLoader

setBlobPath

public void setBlobPath(java.lang.String path)
                 throws java.io.IOException
configures the path to be used to store and read Blob data.

Parameters:
path - the path to be used

setClassLoader

public void setClassLoader(java.lang.ClassLoader classLoader)
configures db4o to use a custom ClassLoader.

Parameters:
ClassLoader - the ClassLoader to be used

setMessageRecipient

public void setMessageRecipient(MessageRecipient messageRecipient)
sets the MessageRecipient to receive Client Server messages.
Parameters:
MessageRecipient - the MessageRecipient to be used

setOut

public void setOut(java.io.PrintStream outStream)
assigns a PrintStream where db4o is to print its event messages.

Messages are useful for debugging purposes and for learning to understand, how db4o works. The message level can be raised with Db4o.configure().messageLevel() to produce more detailed messages.

Use setOut(System.out) to print messages to the console.

Parameters:
outStream - the new PrintStream for messages.

unicode

public void unicode(boolean flag)
configures the storage format of Strings.

This method needs to be called before a database file is created with the first Db4o.openFile(). db4o database files keep their string format after creation.

Turning Unicode support off reduces the file storage space for strings by factor 2 and improves performance.

Default settings
mobile edition: false
all other versions: true

Parameters:
flag - true for turning Unicode support on, false for turning Unicode support off.

updateDepth

public void updateDepth(int depth)
specifies the global updateDepth.

see the documentation of ObjectContainer.set() for further details.

The value be may be overridden for individual classes.

The default setting is 0: Only the object passed to ObjectContainer.set() will be updated.

Parameters:
depth - the depth of the desired update.
See Also:
ObjectClass#updateDepth(), ObjectClass#cascadeOnUpdate(),
Using callbacks

db4o 2.0