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

Methods

Modifier and Type	Method and Description
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.

Method Detail

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

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.