Package 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

      All Methods Instance Methods Abstract Methods Deprecated Methods 
      Modifier and Type Method 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 maximumDatabaseFileSize​(long bytes)
      Configures an upper limit for the maximum database file size.
      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.

      • 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

      • maximumDatabaseFileSize

        void maximumDatabaseFileSize​(long bytes)
        Configures an upper limit for the maximum database file size. There is an upper limit to the possible size: A value that is greater than Integer.MAX_VALUE * blockSize(int) will be ignored and this limit will be used instead.
        Parameters:
        bytes - - the number of bytes
        Since:
        8.1

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