db4o 4.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 callback methods on and off.
 void classActivationDepthConfigurable(boolean flag)
          turns individual class activation depth configuration on and off.
 void detectSchemaChanges(boolean flag)
          tuning feature: configures whether db4o checks all persistent classes upon system startup, for added or removed fields.
 void disableCommitRecovery()
          turns commit recovery off.
 void discardFreeSpace(int byteCount)
          tuning feature: configures the minimum size of free space slots in the database file that are to be reused.
 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.
 void generateUUIDs(int setting)
          configures db4o to generate UUIDs for stored objects.
 void generateVersionNumbers(int setting)
          configures db4o to generate version numbers for stored objects.
 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 markTransient(java.lang.String attributeName)
          allows to mark fields as transient with custom attributes.
 void messageLevel(int level)
          sets the detail level of db4o messages.
 ObjectClass objectClass(java.lang.Object clazz)
          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 reflectWith(IReflect reflector)
          configures the use of a specially designed reflection implementation.
 void refreshClasses()
          forces analysation of all Classes during a running session.
 void reserveStorageSpace(long byteCount)
          tuning feature only: reserves a number of bytes in database files.
 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 singleThreadedClient(boolean flag)
          configures the client messaging system to be single threaded or multithreaded.
 void testConstructors(boolean flag)
          tuning feature: configures whether db4o should try to instantiate one instance of each persistent class on system startup.
 void timeoutClientSocket(int milliseconds)
          configures the time a client waits for a message response from the server.
 void timeoutPingClients(int milliseconds)
          configures the delay time after which the server starts pinging connected clients to check the connection.
 void timeoutServerSocket(int milliseconds)
          configures the timeout of the serverside socket.
 void unicode(boolean flag)
          configures the storage format of Strings.
 void updateDepth(int depth)
          specifies the global updateDepth.
 void weakReferenceCollectionInterval(int milliseconds)
          configures the timer for WeakReference collection.
 void weakReferences(boolean flag)
          turns weak reference management on or off.
 

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 callback methods on and off.

Callbacks are turned on by default.

A tuning hint: If callbacks are not used, you can turn this feature off, to prevent db4o from looking for callback methods in persistent classes. This will increase the performance on system startup.

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?

detectSchemaChanges

public void detectSchemaChanges(boolean flag)
tuning feature: configures whether db4o checks all persistent classes upon system startup, for added or removed fields.

In a production environment this setting can be set to false, if all necessary classes have been stored to the database file and none of them have been modified since the last use.

Default value:
true

Parameters:
flag - the desired setting

disableCommitRecovery

public void disableCommitRecovery()
turns commit recovery off.

db4o uses a two-phase commit algorithm. In a first step all intended changes are written to a free place in the database file, the "transaction commit record". In a second step the actual changes are performed. If the system breaks down during commit, the commit process is restarted when the database file is opened the next time. On very rare occasions (possibilities: hardware failure or editing the database file with an external tool) the transaction commit record may be broken. In this case, this method can be used to try to open the database file without commit recovery. The method should only be used in emergency situations after consulting db4o support.


discardFreeSpace

public void discardFreeSpace(int byteCount)
tuning feature: configures the minimum size of free space slots in the database file that are to be reused.

When objects are updated or deleted, the space previously occupied in the database file is marked as "free", so it can be reused. db4o maintains two lists in RAM, sorted by address and by size. Adjacent entries are merged. After a large number of updates or deletes have been executed, the lists can become large, causing RAM consumption and performance loss for maintenance. With this method you can specify an upper bound for the byte slot size to discard.

Pass Integer.MAX_VALUE to this method to discard all free slots for the best possible startup time.

The downside of setting this value: Database files will necessarily grow faster.

Default value:
0 all space is reused

Parameters:
byteCount - Slots with this size or smaller will be lost.

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.

generateUUIDs

public void generateUUIDs(int setting)
configures db4o to generate UUIDs for stored objects.

Parameters:
setting - one of the following values:
-1 - off
1 - configure classes individually
Integer.MAX_Value - on for all classes

generateVersionNumbers

public void generateVersionNumbers(int setting)
configures db4o to generate version numbers for stored objects.

Parameters:
setting - one of the following values:
-1 - off
1 - configure classes individually
Integer.MAX_Value - on for all classes

getMessageSender

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

Returns:
MessageSender

markTransient

public void markTransient(java.lang.String attributeName)
allows to mark fields as transient with custom attributes.

.NET only: Call this method with the attribute name that you wish to use to mark fields as transient. Multiple transient attributes are possible by calling this method multiple times with different attribute names.

Parameters:
attributeName - - the fully qualified name of the attribute, including it's namespace

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.Object clazz)
returns an ObjectClass object to configure the specified class.

There are three options how to use this method.
Any of the following parameters are possible:
- a fully qualified classname.
- a Class object.
- any object to be used as a template.

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.


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().

reflectWith

public void reflectWith(IReflect reflector)
configures the use of a specially designed reflection implementation.

db4o internally uses java.lang.reflect.* by default. On platforms that do not support this package, customized implementations may be written to supply all the functionality of the interfaces in the com.db4o.reflect package. This method can be used to install a custom reflection implementation.


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

reserveStorageSpace

public void reserveStorageSpace(long byteCount)
tuning feature only: reserves a number of bytes in database files.

The global setting is used for the creation of new database files. Continous calls on an ObjectContainer Configuration context (see ExtObjectContainer.configure()) will continually allocate space.

The allocation of a fixed number of bytes at one time makes it more likely that the database will be stored in one chunk on the mass storage. Less read/write head movevement can result in improved performance.

Note:
Allocated space will be lost on abnormal termination of the database engine (hardware crash, VM crash). A Defragment run will recover the lost space. For the best possible performance, this method should be called before the Defragment run to configure the allocation of storage space to be slightly greater than the anticipated database file size.

Default configuration: 0


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
Throws:
java.io.IOException

setClassLoader

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


setMessageRecipient

public void setMessageRecipient(MessageRecipient messageRecipient)
sets the MessageRecipient to receive Client Server messages.


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.

singleThreadedClient

public void singleThreadedClient(boolean flag)
configures the client messaging system to be single threaded or multithreaded.

Recommended settings:
- true for low ressource systems.
- false for best asynchronous performance and fast GUI response.

Default value:
- .NET Compactframework: true
- all other plaforms: false

Parameters:
flag - the desired setting

testConstructors

public void testConstructors(boolean flag)
tuning feature: configures whether db4o should try to instantiate one instance of each persistent class on system startup.

In a production environment this setting can be set to false, if all persistent classes have public default constructors.

Default value:
true

Parameters:
flag - the desired setting

timeoutClientSocket

public void timeoutClientSocket(int milliseconds)
configures the time a client waits for a message response from the server.

Default value: 300000ms (5 minutes)

Parameters:
milliseconds - time in milliseconds

timeoutServerSocket

public void timeoutServerSocket(int milliseconds)
configures the timeout of the serverside socket.

All server connection threads jump out of the socket read statement on a regular interval to check if the server was shut down. Use this method to configure the duration of the interval.

Default value: 5000ms (5 seconds)

Parameters:
milliseconds - time in milliseconds

timeoutPingClients

public void timeoutPingClients(int milliseconds)
configures the delay time after which the server starts pinging connected clients to check the connection.

If no client messages are received by the server for the configured interval, the server sends a "PING" message to the client and wait's for an "OK" response. After 5 unsuccessful attempts, the client connection is closed.

This value may need to be increased for single-threaded clients, since they can't respond instantaneously.

Default value: 180000ms (3 minutes)

Parameters:
milliseconds - time in milliseconds
See Also:
{@link #singleThreadedClient(boolean)}

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 setting: 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

weakReferences

public void weakReferences(boolean flag)
turns weak reference management on or off.

Performance may be improved by running db4o without weak reference memory management at the cost of higher memory consumption or by alternatively implementing a manual memory management using ExtObjectContainer.purge(java.lang.Object)

The default setting is true.

Ignored on JDKs before 1.2.


weakReferenceCollectionInterval

public void weakReferenceCollectionInterval(int milliseconds)
configures the timer for WeakReference collection.

The default setting is 1000 milliseconds.

Configure this setting to zero to turn WeakReference collection off.

Ignored on JDKs before 1.2.

Parameters:
milliseconds - the time in milliseconds

db4o 4.0