db4o 6.1

com.db4o.config
Interface Configuration


public interface Configuration

configuration interface.

This interface contains methods to configure db4o.

The global Configuration context is available with Db4o.configure(). When an ObjectContainer or ObjectServer is opened, the global Configuration context is cloned and copied into the ObjectContainer/ObjectServer. That means every ObjectContainer/ObjectServer gets it's own copy of configuration settings.

Most configuration settings should be set before opening an ObjectContainer/ObjectServer.

Some configuration settings can be modified on an open ObjectContainer/ObjectServer. The local Configuration context is available with ExtObjectContainer.configure() and ExtObjectServer.configure().


Method Summary
 void activationDepth(int depth)
          sets the activation depth to the specified value.
 void addAlias(Alias alias)
          adds a new Alias for a class, namespace or package.
 void allowVersionUpdates(boolean flag)
          turns automatic database file format version updates on.
 void automaticShutDown(boolean flag)
          turns automatic shutdown of the engine on and off.
 void blockSize(int bytes)
          sets the storage data blocksize for new ObjectContainers.
 void bTreeCacheHeight(int height)
          configures caching of BTree nodes.
 void bTreeNodeSize(int size)
          configures the size of BTree nodes in indexes.
 void callbacks(boolean flag)
          turns callback methods on and off.
 void callConstructors(boolean flag)
          advises db4o to try instantiating objects with/without calling constructors.
 void classActivationDepthConfigurable(boolean flag)
          turns individual class activation depth configuration on and off.
 ClientServerConfiguration clientServer()
          returns the freespace configuration interface.
 void detectSchemaChanges(boolean flag)
          tuning feature: configures whether db4o checks all persistent classes upon system startup, for added or removed fields.
 DiagnosticConfiguration diagnostic()
          returns the configuration interface for diagnostics.
 void disableCommitRecovery()
          turns commit recovery off.
 void discardFreeSpace(int byteCount)
          Deprecated. please call Db4o.configure().freespace().discardSmallerThan()
 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 flushFileBuffers(boolean flag)
          configures file buffers to be flushed during transaction commits.
 FreespaceConfiguration freespace()
          returns the freespace configuration interface.
 void generateUUIDs(ConfigScope setting)
          configures db4o to generate UUIDs for stored objects.
 void generateUUIDs(int setting)
          Deprecated. Use generateUUIDs(ConfigScope) instead.
 void generateVersionNumbers(ConfigScope setting)
          configures db4o to generate version numbers for stored objects.
 void generateVersionNumbers(int setting)
          Deprecated. Use generateVersionNumbers(ConfigScope) instead.
 void internStrings(boolean doIntern)
          Configures db4o to call intern() on strings upon retrieval.
 void io(IoAdapter adapter)
          allows to configure db4o to use a customized byte IO adapter.
 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.
 boolean optimizeNativeQueries()
          indicates whether Native Queries will be optimized dynamically.
 void optimizeNativeQueries(boolean optimizeNQ)
          If set to true, db4o will try to optimize native queries dynamically at query execution time, otherwise it will run native queries in unoptimized mode as SODA evaluations.
 void password(java.lang.String pass)
          protects the database file with a password.
 QueryConfiguration queries()
          returns the Query configuration interface.
 void readOnly(boolean flag)
          turns readOnly mode on and off.
 void reflectWith(Reflector reflector)
          configures the use of a specially designed reflection implementation.
 void refreshClasses()
          forces analysis of all Classes during a running session.
 void removeAlias(Alias alias)
          Removes an alias previously added with addAlias.
 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.Object classLoader)
          Deprecated. use reflectWith(new JdkReflector(classLoader)) instead
 void setOut(java.io.PrintStream outStream)
          Assigns a PrintStream where db4o is to print its event messages.
 void testConstructors(boolean flag)
          tuning feature: configures whether db4o should try to instantiate one instance of each persistent class on system startup.
 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

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

Why activation?
When objects are instantiated from the database, the instantiation of member objects needs to be limited to a certain depth. Otherwise a single object could lead to loading the complete database into memory, if all objects where reachable from a single root object.

db4o uses the concept "depth", the number of field-to-field hops an object is away from another object. The preconfigured "activation depth" db4o uses in the default setting is 5.

Whenever an application iterates through the ObjectSet of a query result, the result objects will be activated to the configured activation depth.

A concrete example with the preconfigured activation depth of 5:
 // Object foo is the result of a query, it is delivered by the ObjectSet 
 Object foo = objectSet.next();
foo.member1.member2.member3.member4.member5 will be a valid object
foo, member1, member2, member3 and member4 will be activated
member5 will be deactivated, all of it's members will be null
member5 can be activated at any time 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.

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

addAlias

void addAlias(Alias alias)
adds a new Alias for a class, namespace or package.

Aliases can be used to persist classes in the running application to different persistent classes in a database file or on a db4o server.

Two simple Alias implementations are supplied along with db4o:
- TypeAlias provides an #equals() resolver to match names directly.
- WildcardAlias allows simple pattern matching with one single '*' wildcard character.

It is possible to create own complex Alias constructs by creating own resolvers that implement the Alias interface.

Four examples of concrete usecases:

// Creating an Alias for a single class
Db4o.configure().addAlias(
  new TypeAlias("com.f1.Pilot", "com.f1.Driver"));


// Accessing a .NET assembly from a Java package
Db4o.configure().addAlias(
  new WildcardAlias(
    "com.f1.*, F1RaceAssembly",
    "com.f1.*"));


// Using a different local .NET assembly
Db4o.configure().addAlias(
  new WildcardAlias(
    "com.f1.*, F1RaceAssembly",
    "com.f1.*, RaceClient"));


// Mapping a Java package onto another
Db4o.configure().addAlias(
  new WildcardAlias(
    "com.f1.*",
    "com.f1.client*"));


Aliases that translate the persistent name of a class to a name that already exists as a persistent name in the database (or on the server) are not permitted and will throw an exception when the database file is opened.

Aliases should be configured before opening a database file or connecting to a server.


removeAlias

void removeAlias(Alias alias)
Removes an alias previously added with addAlias.

Parameters:
alias - the alias to remove

allowVersionUpdates

void allowVersionUpdates(boolean flag)
turns automatic database file format version updates on.

Upon db4o database file format version changes, db4o can automatically update database files to the current version. db4objects does not provide functionality to reverse this process. It is not ensured that updated database files can be read with older db4o versions. In some cases (Example: using ObjectManager) it may not be desirable to update database files automatically therefore automatic updating is turned off by default for security reasons.

Call this method to turn automatic database file version updating on.

If automatic updating is turned off, db4o will refuse to open database files that use an older database file format.


automaticShutDown

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.

blockSize

void blockSize(int bytes)
sets the storage data blocksize for new ObjectContainers.

The standard setting is 1 allowing for a maximum database file size of 2GB. This value can be increased to allow larger database files, although some space will be lost to padding because the size of some stored objects will not be an exact multiple of the block size. A recommended setting for large database files is 8, since internal pointers have this length.

Parameters:
bytes - the size in bytes from 1 to 127

bTreeNodeSize

void bTreeNodeSize(int size)
configures the size of BTree nodes in indexes.

Default setting: 100
Lower values will allow a lower memory footprint and more efficient reading and writing of small slots.
Higher values will reduce the overall number of read and write operations and allow better performance at the cost of more RAM use.

Parameters:
size - the number of elements held in one BTree node.

bTreeCacheHeight

void bTreeCacheHeight(int height)
configures caching of BTree nodes.

Clean BTree nodes will be unloaded on #commit and #rollback unless they are configured as cached here.

Default setting: 0
Possible settings: 1, 2 or 3

The potential number of cached BTree nodes can be calculated with the following forumula:
maxCachedNodes = bTreeNodeSize ^ bTreeCacheHeight

Parameters:
height - the height of the cache from the root

callbacks

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:
Using callbacks

callConstructors

void callConstructors(boolean flag)
advises db4o to try instantiating objects with/without calling constructors.

Not all JDKs / .NET-environments support this feature. db4o will attempt, to follow the setting as good as the enviroment supports. In doing so, it may call implementation-specific features like sun.reflect.ReflectionFactory#newConstructorForSerialization on the Sun Java 1.4.x/5 VM (not available on other VMs) and FormatterServices.GetUninitializedObject() on the .NET framework (not available on CompactFramework). This setting may also be overridden for individual classes in ObjectClass.callConstructor(boolean).

The default setting depends on the features supported by your current environment.

Parameters:
flag - - specify true, to request calling constructors, specify false to request not calling constructors.
See Also:
ObjectClass.callConstructor(boolean)

classActivationDepthConfigurable

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

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

diagnostic

DiagnosticConfiguration diagnostic()
returns the configuration interface for diagnostics.

Returns:
the configuration interface for diagnostics.

disableCommitRecovery

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

void discardFreeSpace(int byteCount)
Deprecated. please call Db4o.configure().freespace().discardSmallerThan()

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

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(java.lang.String)

exceptionsOnNotStorable

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.

flushFileBuffers

void flushFileBuffers(boolean flag)
configures file buffers to be flushed during transaction commits.

db4o uses a resume-commit-on-crash strategy to ensure ACID transactions. When a transaction commits,
- (1) a list "pointers that are to be modified" is written to the database file,
- (2) the database file is switched into "in-commit" mode,
- (3) the pointers are actually modified in the database file,
- (4) the database file is switched to "not-in-commit" mode.
If the system is halted by a hardware or power failure
- before (2)
all objects will be available as before the commit
- between (2) and (4) the commit is restarted when the database file is opened the next time, all pointers will be read from the "pointers to be modified" list and all of them will be modified to the state they are intended to have after commit
- after (4) no work is necessary, the transaction is committed.

In order for the above to be 100% failsafe, the order of writes to the storage medium has to be obeyed. On operating systems that use in-memory file caching, the OS cache may revert the order of writes to optimize file performance.

db4o enforces the correct write order by flushing file buffers after every single one of the above steps during transaction commit. Flush calls have a strong impact on performance. It is possible to tune an application by turning flushing off, at the risc of less security for hardware-, power- or operating system failures.

Parameters:
flag - true for flushing file buffers

freespace

FreespaceConfiguration freespace()
returns the freespace configuration interface.


generateUUIDs

void generateUUIDs(int setting)
Deprecated. Use generateUUIDs(ConfigScope) instead.

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

generateUUIDs

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

Parameters:
the - scope for UUID generation: disabled, generate for all classes, or configure individually

generateVersionNumbers

void generateVersionNumbers(int setting)
Deprecated. Use generateVersionNumbers(ConfigScope) instead.

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

generateVersionNumbers

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

Parameters:
the - scope for version number generation: disabled, generate for all classes, or configure individually

internStrings

void internStrings(boolean doIntern)
Configures db4o to call intern() on strings upon retrieval.

Parameters:
doIntern - intern strings on retrieval if true, don't otherwise

io

void io(IoAdapter adapter)
allows to configure db4o to use a customized byte IO adapter.

Derive from the abstract class IoAdapter to write your own. Possible usecases could be improved performance with a native library, mirrored write to two files or read-on-write fail-safety control.

Sample IoAdapters are supplied with the distribution as source code.

Parameters:
adapter - - the IoAdapter

markTransient

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

void messageLevel(int level)
sets the detail level of db4o messages. Messages will be output to the configured output PrintStream.

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

When using client-server and the level is set to 0, the server will override this and set it to 1. To get around this you can set the level to -1. This has the effect of not returning any messages.

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

lockDatabaseFile

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

ObjectClass objectClass(java.lang.Object clazz)
returns an ObjectClass object to configure the specified class.

The clazz parameter can be any of the following:
- a fully qualified classname as a String.
- a Class object.
- any other object to be used as a template.

Parameters:
clazz - class name, Class object, or example object.

Returns:
an instance of an ObjectClass object for configuration.

optimizeNativeQueries

void optimizeNativeQueries(boolean optimizeNQ)
If set to true, db4o will try to optimize native queries dynamically at query execution time, otherwise it will run native queries in unoptimized mode as SODA evaluations. On the Java platform the jars needed for native query optimization (db4o-X.x-nqopt.jar, bloat-X.x.jar) have to be on the classpath at runtime for this switch to have effect.

The default setting is true.

Parameters:
optimizeNQ - true, if db4o should try to optimize native queries at query execution time, false otherwise

optimizeNativeQueries

boolean optimizeNativeQueries()
indicates whether Native Queries will be optimized dynamically.

Returns:
boolean indicates whether Native Queries will be optimized dynamically.
See Also:
optimizeNativeQueries(boolean)

password

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:
pass - the password to be used.

queries

QueryConfiguration queries()
returns the Query configuration interface.


readOnly

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

void reflectWith(Reflector 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

void refreshClasses()
forces analysis 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(java.lang.Object)

reserveStorageSpace

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

Parameters:
byteCount - the number of bytes to reserve

setBlobPath

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

void setClassLoader(java.lang.Object classLoader)
Deprecated. use reflectWith(new JdkReflector(classLoader)) instead

configures db4o to use a custom ClassLoader.

Parameters:
classLoader - the ClassLoader to be used

setOut

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.
See Also:
messageLevel(int)

testConstructors

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

unicode

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

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 1: Only the object passed to ObjectContainer.set() will be updated.

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

weakReferences

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

This method must be called before opening a database.

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

Setting the value to false causes db4o to use hard references to objects, preventing the garbage collection process from disposing of unused objects.

The default setting is true.

Ignored on JDKs before 1.2.


weakReferenceCollectionInterval

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

clientServer

ClientServerConfiguration clientServer()
returns the freespace configuration interface.


db4o 6.1