com.db4o.config
Interface CommonConfiguration
public interface CommonConfiguration
Common configuration methods, applicable for
embedded, client and server use of db4o.
In Client/Server use it is good practice to configure the
client and the server in exactly the same way.
- Since:
- 7.5
Method Summary |
int |
activationDepth()
gets the configured activation depth. |
void |
activationDepth(int depth)
sets the activation depth to the specified value. |
void |
add(ConfigurationItem configurationItem)
adds ConfigurationItems to be applied when
an ObjectContainer or ObjectServer is opened. |
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 |
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 |
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. |
EnvironmentConfiguration |
environment()
|
void |
exceptionsOnNotStorable(boolean flag)
configures whether Exceptions are to be thrown, if objects can not be stored. |
void |
internStrings(boolean flag)
configures db4o to call #intern() on strings upon retrieval. |
void |
markTransient(java.lang.String attributeName)
allows to mark fields as transient with custom annotations/attributes. |
int |
maxStackDepth()
gets the configured max stack depth. |
void |
maxStackDepth(int maxStackDepth)
Sets the max stack depth that will be used for recursive storing and activating an object. |
void |
messageLevel(int level)
sets the detail level of db4o messages. |
void |
nameProvider(NameProvider provider)
Registers a NameProvider that assigns a custom name to the database to be used in
Object.toString() . |
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 |
outStream(java.io.PrintStream outStream)
Assigns a PrintStream where db4o is to print its event messages. |
QueryConfiguration |
queries()
returns the Query configuration interface. |
void |
reflectWith(Reflector reflector)
configures the use of a specially designed reflection implementation. |
void |
registerTypeHandler(TypeHandlerPredicate predicate,
TypeHandler4 typeHandler)
allows registering special TypeHandlers for customized marshalling
and customized comparisons. |
void |
removeAlias(Alias alias)
Removes an alias previously added with addAlias(Alias) . |
void |
stringEncoding(StringEncoding encoding)
configures the string encoding to be used. |
void |
testConstructors(boolean flag)
tuning feature: configures whether db4o should try to instantiate one instance
of each persistent class on system startup. |
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. |
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.
Examples of concrete usecases:
// Creating an Alias for a single class
EmbeddedConfiguration config = Db4oEmbedded.newConfiguration();
config.common().addAlias(
new TypeAlias("com.f1.Pilot", "com.f1.Driver"));
// Mapping a Java package onto another
config.common().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.
In client/server environment it is good practice to configure the
client and the server in exactly the same way.
removeAlias
void removeAlias(Alias alias)
- Removes an alias previously added with
addAlias(Alias)
.
- Parameters:
alias
- the alias to remove
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.
In client/server environment it is good practice to configure the
client and the server in exactly the same way.
- Parameters:
depth
- the desired global activation depth.- See Also:
configuring classes individually
activationDepth
int activationDepth()
- gets the configured activation depth.
- Returns:
- the configured activation depth.
add
void add(ConfigurationItem configurationItem)
- adds ConfigurationItems to be applied when
an ObjectContainer or ObjectServer is opened.
- Parameters:
configurationItem
- the ConfigurationItem
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.
In client/server environment it is good practice to configure the
client and the server in exactly the same way.
automaticShutDown
void automaticShutDown(boolean flag)
- turns automatic shutdown of the engine on and off.
The default and recommended setting is
true
.
- Parameters:
flag
- whether db4o should shut down automatically.
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.
In client/server environment it is good practice to configure the
client and the server in exactly the same way.
- Parameters:
size
- the number of elements held in one BTree node.
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.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
- 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.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
- Parameters:
flag
- - specify true, to request calling constructors, specify
false to request not calling constructors.- See Also:
ObjectClass.callConstructor(boolean)
detectSchemaChanges
void detectSchemaChanges(boolean flag)
- tuning feature: configures whether db4o checks all persistent classes upon system
startup, for added or removed fields.
If this configuration setting is set to false while a database is
being created, members of classes will not be detected and stored.
This setting can be set to false in a production environment after
all persistent classes have been stored at least once and classes will not
be modified any further in the future.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
Default value:
true
- Parameters:
flag
- the desired setting
diagnostic
DiagnosticConfiguration diagnostic()
- returns the configuration interface for diagnostics.
- Returns:
- the configuration interface for diagnostics.
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 be stopped with an Exception. This method can
be used to configure db4o to not throw an
ObjectNotStorableException
if an object can not be stored.
The default for this setting is true.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
- Parameters:
flag
- true to throw Exceptions if objects can not be stored.
internStrings
void internStrings(boolean flag)
- configures db4o to call #intern() on strings upon retrieval.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
- Parameters:
flag
- true to intern strings
markTransient
void markTransient(java.lang.String attributeName)
- allows to mark fields as transient with custom annotations/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.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
- 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.
In client-server environment this setting can be used on client or on server
depending on which information do you want to track (server side provides more
detailed information).
- Parameters:
level
- integer from 0 to 3- See Also:
TODO: replace int with enumeration
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
.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
- 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 true if Native Queries will be optimized
dynamically.
- See Also:
optimizeNativeQueries(boolean)
queries
QueryConfiguration queries()
- returns the Query configuration interface.
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.
In client-server environment this setting should be used on both the client and
the server side (reflector class must be available)
outStream
void outStream(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
Configuration.messageLevel(int)
to produce more detailed messages.
Use outStream(System.out)
to print messages to the
console.
In client-server environment this setting should be used on the same side
where Configuration.messageLevel(int)
is used.
- Parameters:
outStream
- the new PrintStream
for messages.- See Also:
messageLevel(int)
stringEncoding
void stringEncoding(StringEncoding encoding)
- configures the string encoding to be used.
The string encoding can not be changed in the lifetime of a
database file. To set up the database with the correct string encoding,
this configuration needs to be set correctly before a database
file is created with the first call to
Db4oEmbedded.openFile(com.db4o.config.EmbeddedConfiguration, java.lang.String)
or Db4oClientServer.openServer(com.db4o.cs.config.ServerConfiguration, java.lang.String, int)
.
For subsequent open calls, db4o remembers built-in
string encodings. If a custom encoding is used (an encoding that is
not supplied from within the db4o library), the correct encoding
needs to be configured correctly again for all subsequent calls
that open database files.
In a client-server mode, the server and all clients need to have the same string encoding.
Example:
config.stringEncoding(StringEncodings.utf8()));
- See Also:
StringEncodings
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.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
Default value:
true
- Parameters:
flag
- the desired setting
updateDepth
void updateDepth(int depth)
- specifies the global updateDepth.
see the documentation of
ObjectContainer.store(java.lang.Object)
for further details.
The value be may be overridden for individual classes.
The default setting is 1: Only the object passed to
ObjectContainer.store(java.lang.Object)
will be updated.
In a client/server environment it is good practice to configure the
client and the server in exactly the same way.
- 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
.
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.
- Parameters:
milliseconds
- the time in milliseconds
registerTypeHandler
void registerTypeHandler(TypeHandlerPredicate predicate,
TypeHandler4 typeHandler)
- allows registering special TypeHandlers for customized marshalling
and customized comparisons.
- Parameters:
predicate
- to specify for which classes and versions the
TypeHandler is to be used.typeHandler
- to be used for the classes that match the predicate.
environment
EnvironmentConfiguration environment()
- See Also:
Environment
nameProvider
void nameProvider(NameProvider provider)
- Registers a
NameProvider
that assigns a custom name to the database to be used in
Object.toString()
.
maxStackDepth
void maxStackDepth(int maxStackDepth)
Sets the max stack depth that will be used for recursive storing and activating an object.
The default value is set to Const4.DEFAULT_MAX_STACK_DEPTH
On Android platform, we recomend setting this to 2.
- Parameters:
depth
- the desired max stack depth.
maxStackDepth
int maxStackDepth()
- gets the configured max stack depth.
- Returns:
- the configured max stack depth.
Copyright 2009 Versant Corporation. All rights reserved.