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