com.db4o.config
Interface FileConfiguration
public interface FileConfiguration
File-related configuration methods, applicable
for db4o embedded use and on the server in a
Client/Server setup.
- Since:
- 7.5
- See Also:
FileConfigurationProvider.file()
Method Summary |
void |
asynchronousSync(boolean flag)
turns asynchronous sync on and off.
One of the most costly operations during commit is the call to
flush the buffers of the database file. |
void |
blobPath(java.lang.String path)
configures the path to be used to store and read
Blob data. |
void |
blockSize(int bytes)
sets the storage data blocksize for new ObjectContainers. |
void |
databaseGrowthSize(int bytes)
configures the size database files should grow in bytes, when no
free slot is found within. |
void |
disableCommitRecovery()
turns commit recovery off. |
FreespaceConfiguration |
freespace()
returns the freespace configuration interface. |
void |
generateCommitTimestamps(boolean flag)
Configures db4o to generate commit timestamps for all stored objects.
All the objects commited within a transaction will share the same commit timestamp. |
void |
generateUUIDs(ConfigScope setting)
configures db4o to generate UUIDs for stored objects. |
void |
generateVersionNumbers(ConfigScope setting)
Deprecated. As of version 8.0 please use generateCommitTimestamps(boolean) instead. |
void |
lockDatabaseFile(boolean flag)
can be used to turn the database file locking thread off. |
void |
readOnly(boolean flag)
turns readOnly mode on and off. |
void |
recoveryMode(boolean flag)
turns recovery mode on and off.
Recovery mode can be used to try to retrieve as much as possible
out of an already corrupted database. |
void |
reserveStorageSpace(long byteCount)
tuning feature only: reserves a number of bytes in database files. |
Storage |
storage()
returns the configured Storage . |
void |
storage(Storage storage)
allows to configure db4o to use a customized byte IO storage mechanism. |
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.
This setting is only effective when the database is first created.
- Parameters:
bytes
- the size in bytes from 1 to 127
databaseGrowthSize
void databaseGrowthSize(int bytes)
- configures the size database files should grow in bytes, when no
free slot is found within.
Tuning setting.
Whenever no free slot of sufficient length can be found
within the current database file, the database file's length
is extended. This configuration setting configures by how much
it should be extended, in bytes.
This configuration setting is intended to reduce fragmentation.
Higher values will produce bigger database files and less
fragmentation.
To extend the database file, a single byte array is created
and written to the end of the file in one write operation. Be
aware that a high setting will require allocating memory for
this byte array.
- Parameters:
bytes
- amount of bytes
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.
freespace
FreespaceConfiguration freespace()
- returns the freespace configuration interface.
generateUUIDs
void generateUUIDs(ConfigScope setting)
- configures db4o to generate UUIDs for stored objects.
This setting should be used when the database is first created.
- Parameters:
setting
- the scope for UUID generation: disabled, generate for all classes, or configure individually
generateVersionNumbers
@Deprecated
void generateVersionNumbers(ConfigScope setting)
- Deprecated. As of version 8.0 please use
generateCommitTimestamps(boolean)
instead.
- configures db4o to generate version numbers for stored objects.
This setting should be used when the database is first created.
- Parameters:
setting
- the scope for version number generation: disabled, generate for all classes, or configure individually
generateCommitTimestamps
void generateCommitTimestamps(boolean flag)
- Configures db4o to generate commit timestamps for all stored objects.
All the objects commited within a transaction will share the same commit timestamp.
This setting should be used when the database is first created.
Afterwards you can access the object's commit timestamp like this:
ObjectContainer container = ...;
ObjectInfo objectInfo = container.ext().getObjectInfo(obj);
long commitTimestamp = objectInfo.getVersion();
- Parameters:
flag
- if true, commit timetamps will be generated for all stored
objects. If you already have commit timestamps for stored
objects and later set this flag to false, although you wont be
able to access them, the commit timestamps will still be taking
space in your file container. The only way to free that space
is defragmenting the container.- Since:
- 8.0
storage
void storage(Storage storage)
throws GlobalOnlyConfigException
- allows to configure db4o to use a customized byte IO storage mechanism.
You can implement the interface Storage
to
write your own. Possible usecases could be improved performance
with a native library, mirrored write to two files, encryption or
read-on-write fail-safety control.
- Parameters:
storage
- - the storage
- Throws:
GlobalOnlyConfigException
- See Also:
FileStorage
,
CachingStorage
,
MemoryStorage
storage
Storage storage()
- returns the configured
Storage
.
- Returns:
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 resource 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.
reserveStorageSpace
void reserveStorageSpace(long byteCount)
throws DatabaseReadOnlyException,
com.db4o.foundation.NotSupportedException
- tuning feature only: reserves a number of bytes in database files.
The global setting is used for the creation of new database
files.
Without this setting, storage space will be allocated
continuously as required. However, 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 movement
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
- Throws:
DatabaseReadOnlyException
com.db4o.foundation.NotSupportedException
blobPath
void blobPath(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
readOnly
void readOnly(boolean flag)
- turns readOnly mode on and off.
This method configures the mode in which subsequent calls to
Db4oEmbedded.openFile(EmbeddedConfiguration, String)
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.
- Parameters:
flag
- true
for configuring readOnly mode for subsequent
calls to Db4o.openFile()
.
TODO: this is rather embedded + client than base?
recoveryMode
void recoveryMode(boolean flag)
- turns recovery mode on and off.
Recovery mode can be used to try to retrieve as much as possible
out of an already corrupted database. In recovery mode internal
checks are more relaxed. Null or invalid objects may be returned
instead of throwing exceptions.
Use this method with care as a last resort to get data out of a
corrupted database.
- Parameters:
flag
- true
to turn recover mode on.
asynchronousSync
void asynchronousSync(boolean flag)
- turns asynchronous sync on and off.
One of the most costly operations during commit is the call to
flush the buffers of the database file. In regular mode the
commit call has to wait until this operation has completed.
When asynchronous sync is turned on, the sync operation will
run in a dedicated thread, blocking all other file access
until it has completed. This way the commit call can return
immediately. This will allow db4o and other processes to
continue running side-by-side while the flush call executes.
Use this setting with care: It means that you can not be sure
when a commit call has actually made the changes of a
transaction durable (flushed through OS and file system
buffers). The latency time until flushing happens is extremely
short. The dedicated sync thread does nothing else
except for calling sync and writing the header of the database
file when needed. A setup with this option still guarantees
ACID transaction processing: A database file always will be
either in the state before commit or in the state after
commit. Corruption can not occur. You can just not rely
on the transaction already having been applied when the
commit() call returns.
Copyright 2009 Versant Corporation. All rights reserved.