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 |
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 |
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. |
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)
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. |
FreespaceConfiguration |
freespace()
returns the freespace configuration interface |
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 |
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. |
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 |
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. |
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
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
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
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.
freespace
FreespaceConfiguration freespace()
- returns the freespace configuration interface
- Returns:
- the freespace configuration interface
generateUUIDs
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
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
MessageSender getMessageSender()
- returns the MessageSender for this Configuration context.
- Returns:
- MessageSender
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
- 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.
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.ClassLoader)
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.ClassLoader classLoader)
- configures db4o to use a custom ClassLoader.
- Parameters:
classLoader
- the ClassLoader to be used
setMessageRecipient
void setMessageRecipient(MessageRecipient messageRecipient)
- sets the MessageRecipient to receive Client Server messages.
- Parameters:
messageRecipient
- the MessageRecipient 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)
singleThreadedClient
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
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
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
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
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:
singleThreadedClient(boolean)
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