Module org.cojen.tupl
Package org.cojen.tupl

Class DatabaseConfig

java.lang.Object
org.cojen.tupl.DatabaseConfig
All Implemented Interfaces:
Cloneable
public class DatabaseConfig extends Object implements Cloneable
Configuration options used when opening a database.

  • Constructor Details

    • DatabaseConfig

      public DatabaseConfig()

  • Method Details

    • baseFile

      public DatabaseConfig baseFile(File file)
      Set the base file name for the database, which must reside in an ordinary file directory. If no base file is provided, database is non-durable and cannot exceed the size of the cache.

    • baseFilePath

      public DatabaseConfig baseFilePath(String path)
      Set the base file name for the database, which must reside in an ordinary file directory. If no base file is provided, database is non-durable and cannot exceed the size of the cache.

    • createFilePath

      public DatabaseConfig createFilePath(boolean mkdirs)
      Set true to create directories for the base and data file, if they don't already exist. Default is true.

    • dataFile

      public DatabaseConfig dataFile(File file)
      Set the data file for the database, which by default resides in the same directory as the base file. The data file can be in a separate directory, and it can even be a raw block device.

    • dataFiles

      public DatabaseConfig dataFiles(File... files)
      Stripe the database data file across several files, expected to be on separate devices. The data files can refer to ordinary files or to raw block devices.

    • mapDataFiles

      public DatabaseConfig mapDataFiles(boolean mapped)
      Enable memory mapping of the data files. Not recommended for 32-bit platforms or for databases which don't fit entirely in main memory. Memory mapped files tend to exhibit poor performance when they don't fit in main memory.

      If the data file is fixed in size, consider calling dataPageArray with MappedPageArray for best memory mapping performance. Combine with StripedPageArray when using multiple data files.

    • dataPageArray

      public DatabaseConfig dataPageArray(PageArray array)
      Use a custom storage layer instead of the default data file.

    • minCacheSize

      public DatabaseConfig minCacheSize(long minBytes)
      Set the minimum cache size, overriding the default.
      Parameters:
      minBytes - cache size, in bytes

    • maxCacheSize

      public DatabaseConfig maxCacheSize(long maxBytes)
      Set the maximum cache size, overriding the default.
      Parameters:
      maxBytes - cache size, in bytes

    • cacheSize

      public DatabaseConfig cacheSize(long size)
      Convenience method which sets the minimum and maximum cache size, overriding the default.
      Parameters:
      size - cache size, in bytes

    • durabilityMode

      public DatabaseConfig durabilityMode(DurabilityMode durabilityMode)
      Set the default transaction durability mode, which is SYNC if not overridden. If database itself is non-durable, durability modes are ignored.

    • lockUpgradeRule

      public DatabaseConfig lockUpgradeRule(LockUpgradeRule lockUpgradeRule)
      Set the default lock upgrade rule, which is STRICT if not overridden.

    • lockTimeout

      public DatabaseConfig lockTimeout(long timeout, TimeUnit unit)
      Set the default lock acquisition timeout, which is 1 second if not overridden. A negative timeout is infinite.
      Parameters:
      unit - required unit if timeout is more than zero

    • checkpointRate

      public DatabaseConfig checkpointRate(long rate, TimeUnit unit)
      Set the rate at which checkpoints are automatically performed. Default rate is 1 second. Pass a negative value to disable automatic checkpoints.
      Parameters:
      unit - required unit if rate is more than zero

    • checkpointSizeThreshold

      public DatabaseConfig checkpointSizeThreshold(long bytes)
      Set the minimum redo log size required for an automatic checkpoint to actually be performed. Default is 100 MiB. If database is used primarily for non-transactional operations, the threshold should be set to zero.

    • checkpointDelayThreshold

      public DatabaseConfig checkpointDelayThreshold(long delay, TimeUnit unit)
      Set the maximum delay before an automatic checkpoint is performed, regardless of the redo log size threshold. Default is 1 minute, and a negative delay is infinite. If database is used primarily for non-transactional operations, the threshold should be set to zero.
      Parameters:
      unit - required unit if delay is more than zero

    • maxCheckpointThreads

      public DatabaseConfig maxCheckpointThreads(int num)
      Specify the maximum number of threads for performing checkpointing, to speed it up. This option is most useful when combined with the syncWrites option, or when using DIRECT_IO. The default number of threads is one. If a negative number is provided, the actual number applied is (-num * availableProcessors).

    • eventListener

      public DatabaseConfig eventListener(EventListener listener)
      Set a listener which receives notifications of actions being performed by the database. Listener implementation must be thread-safe.

    • eventListeners

      public DatabaseConfig eventListeners(EventListener... listeners)
      Set multiple listeners which receive notifications of actions being performed by the database. Listener implementations must be thread-safe.

    • syncWrites

      public DatabaseConfig syncWrites(boolean fileSync)
      Set true to ensure all writes to the main database file are immediately durable, although not checkpointed. This option typically reduces overall performance, but checkpoints complete more quickly. As a result, the main database file requires less pre-allocated pages and is smaller. Also consider specifying more checkpoint threads when using this option.

    • readOnly

      public DatabaseConfig readOnly(boolean readOnly)
      Open the database file in read only mode. Writes to the database are permitted until the cache fills up, but nothing is persisted.

    • pageSize

      public DatabaseConfig pageSize(int size)
      Set the page size, which is 4096 bytes by default.

    • directPageAccess

      public DatabaseConfig directPageAccess(boolean direct)
      Set true to allocate all pages off the Java heap, offering increased performance and reduced garbage collection activity. By default, direct page access is enabled if supported.

    • cachePriming

      public DatabaseConfig cachePriming(boolean priming)
      Enable automatic cache priming, which writes a priming set into a special file when the process is cleanly shutdown. When opened again, the priming set is applied and the file is deleted. Option has no effect if database is non-durable.
      See Also:

    • cleanShutdown

      public DatabaseConfig cleanShutdown(boolean shutdown)
      When the process is cleanly shutdown, attempt to issue a full database shutdown. This ensures full durability of all modifications. Setting this option prevents the process from exiting until a final checkpoint completes.

    • replicate

      public DatabaseConfig replicate(ReplicatorConfig config)
      Enable replication using the given configuration. When the database is opened, the given config object is cloned and the base file and event listener are assigned to it.

    • replicate

      public DatabaseConfig replicate(StreamReplicator repl)
      Enable replication with an explicit StreamReplicator instance.

    • maxReplicaThreads

      public DatabaseConfig maxReplicaThreads(int num)
      If replication is enabled, specify the maximum number of threads to process incoming changes. Default is the number of available processors. If a negative number is provided, the actual number applied is (-num * availableProcessors). When the local member is the leader, these threads are used for background processing of transactions which weren't committed with SYNC durability.

      If replication isn't enabled, this option controls the number of threads used to recover transactions from the redo log during startup.

    • enableJMX

      public DatabaseConfig enableJMX(boolean enable)

    • encrypt

      public DatabaseConfig encrypt(Crypto crypto)
      Enable full encryption of the data files, transaction logs, snapshots, and cache priming sets. Option has no effect if database is non-durable. If replication is enabled, encryption is not applied to the replication stream. A StreamReplicator implementation must perform its own encryption.

      Allocated but never used pages within the data files are unencrypted, although they contain no information. Temporary files used by in-progress snapshots contain encrypted content.

    • checksumPages

      public DatabaseConfig checksumPages(Supplier<Checksum> factory)
      Enable 32-bit checksums for all of the underlying database pages. The page size reported by the database will be 4 bytes smaller, to make room for the checksum.
      Parameters:
      factory - creates new checksum instances; CRC32C::new is recommended

    • compressPages

      public DatabaseConfig compressPages(int fullPageSize, long cacheSize, Supplier<PageCompressor> factory)
      Compress the underlying database pages, reducing overall size at the cost of performance. To be effective, the given full page size must be larger than physical page size. A full page size of 65536 bytes paired with the default physical page size of 4096 bytes achieves the best compression. A full page size which is smaller than the physical page size is generally a poor choice.

      The compression layer itself needs its own cache when accessing pages, although it can be much smaller than the primary cache size. Setting it to be 1% of the primary cache size should be sufficient. For a non-durable database, the compression cache should be much larger to avoid running out of space.

      Parameters:
      fullPageSize - full size of pages when uncompressed
      cacheSize - cache size (in bytes) for the compression layer
      factory - creates new page compressor instances

    • customHandlers

      public DatabaseConfig customHandlers(Map<String,? extends CustomHandler> handlers)
      Provide handlers for recovering custom transactional operations. The name assigned to each handler must be unique and never change.

    • prepareHandlers

      public DatabaseConfig prepareHandlers(Map<String,? extends PrepareHandler> handlers)
      Provide handlers for recovering prepared transactions. The name assigned to each handler must be unique and never change.

    • debugOpen

      public void debugOpen(PrintStream out, Map<String,?> properties) throws IOException
      Opens the database in read-only mode for debugging purposes, and then closes it. The format of the printed messages and the supported properties are subject to change.
      • traceUndo=true to print all recovered undo log messages
      • traceRedo=true to print all recovered redo log messages
      Parameters:
      out - pass null to print to standard out
      properties - optional
      Throws:
      IOException

    • clone

      public DatabaseConfig clone()
      Overrides:
      clone in class Object