Package one.microstream.storage.configuration

Interface Configuration

All Known Implementing Classes:
Configuration.Default
public interface Configuration

Mutable configuration type, which serves as a template for an EmbeddedStorageFoundation.

Its purposes are:
- To offer all possible settings of the MicroStream Storage in one place.
- And to enable external configuration.

Code example: 

 EmbeddedStorageManager storageManager = Configuration.Default()
 .setBaseDirectoryInUserHome("data-dir")
 .setBackupDirectory("backup-dir")
 .setChannelCount(4)
 .createEmbeddedStorageFoundation()
 .createEmbeddedStorageManager();

External configuration example with properties file

 baseDirectory = ~/data-dir
 backupDirectory = backup-dir
 channelCount = 4
 Configuration configuration = Configuration.LoadIni(
 "path-to-properties-file"
 );

See Also:
ConfigurationLoader, ConfigurationParser, ConfigurationPropertyNames, MicroStream Reference Manual

  • Method Details

    • PathProperty

      static String PathProperty()
      The property name which is used to hand the external configuration file path to the application.

      Either as system property or in the context's configuration, e.g. Spring's application.properties.

      Returns:
      "microstream.storage.configuration.path"

    • DefaultResourceName

      static String DefaultResourceName()
      The default name of the storage configuration resource.
      Returns:
      "microstream-storage.properties"
      See Also:
      Load()

    • Load

      static Configuration Load()
      Tries to load the default configuration properties file.

      The search order is as follows:

      • The path set in the system property "microstream.storage.configuration.path"
      • The file named "microstream-storage.properties" in
        • The classpath
        • The application's directory
        • The user home directory
      Returns:
      the loaded configuration or null if none was found
      See Also:
      PathProperty(), DefaultResourceName()

    • Load

      static Configuration Load​(Charset charset)
      Tries to load the default configuration properties file.

      The search order is as follows:

      • The path set in the system property "microstream.storage.configuration.path"
      • The file named "microstream-storage.properties" in
        • The classpath
        • The application's directory
        • The user home directory
      Parameters:
      charset - the charset used to load the configuration
      Returns:
      the loaded configuration or null if none was found
      See Also:
      PathProperty(), DefaultResourceName()

    • Load

      static Configuration Load​(String path)
      Tries to load the configuration file from path. Depending on the file suffix either the XML or the INI loader is used.

      The load order is as follows:

      • The classpath
      • As an URL
      • As a file
      Parameters:
      path - a classpath resource, a file path or an URL
      Returns:
      the configuration or null if none was found

    • Load

      static Configuration Load​(String path, Charset charset)
      Tries to load the configuration file from path. Depending on the file suffix either the XML or the INI loader is used.

      The load order is as follows:

      • The classpath
      • As an URL
      • As a file
      Parameters:
      path - a classpath resource, a file path or an URL
      charset - the charset used to load the configuration
      Returns:
      the configuration or null if none was found

    • LoadIni

      static Configuration LoadIni​(String path)
      Tries to load the configuration INI file from path.

      The load order is as follows:

      • The classpath
      • As an URL
      • As a file
      Parameters:
      path - a classpath resource, a file path or an URL
      Returns:
      the configuration or null if none was found

    • LoadIni

      static Configuration LoadIni​(String path, Charset charset)
      Tries to load the configuration INI file from path.

      The load order is as follows:

      • The classpath
      • As an URL
      • As a file
      Parameters:
      path - a classpath resource, a file path or an URL
      charset - the charset used to load the configuration
      Returns:
      the configuration or null if none was found

    • LoadIni

      static Configuration LoadIni​(Path path)
      Tries to load the configuration INI file from path.
      Parameters:
      path - file system path
      Returns:
      the configuration
      Throws:
      StorageConfigurationException - if the configuration couldn't be loaded

    • LoadIni

      static Configuration LoadIni​(Path path, Charset charset)
      Tries to load the configuration INI file from path.
      Parameters:
      path - file system path
      charset - the charset used to load the configuration
      Returns:
      the configuration
      Throws:
      StorageConfigurationException - if the configuration couldn't be loaded

    • LoadIni

      static Configuration LoadIni​(File file)
      Tries to load the configuration INI from the file file.
      Parameters:
      file - file path
      Returns:
      the configuration
      Throws:
      StorageConfigurationException - if the configuration couldn't be loaded

    • LoadIni

      static Configuration LoadIni​(File file, Charset charset)
      Tries to load the configuration INI from the file file.
      Parameters:
      file - file path
      charset - the charset used to load the configuration
      Returns:
      the configuration
      Throws:
      StorageConfigurationException - if the configuration couldn't be loaded

    • LoadIni

      static Configuration LoadIni​(URL url)
      Tries to load the configuration INI from the URL url.
      Parameters:
      url - URL path
      Returns:
      the configuration
      Throws:
      StorageConfigurationException - if the configuration couldn't be loaded

    • LoadIni

      static Configuration LoadIni​(URL url, Charset charset)
      Tries to load the configuration INI from the URL url.
      Parameters:
      url - URL path
      charset - the charset used to load the configuration
      Returns:
      the configuration
      Throws:
      StorageConfigurationException - if the configuration couldn't be loaded

    • LoadIni

      static Configuration LoadIni​(InputStream inputStream)
      Tries to load the configuration INI from the InputStream inputStream.

      Note that the given inputStream will not be closed by this method.

      Parameters:
      inputStream - the stream to read from
      Returns:
      the configuration
      Throws:
      StorageConfigurationException - if the configuration couldn't be loaded

    • LoadIni

      static Configuration LoadIni​(InputStream inputStream, Charset charset)
      Tries to load the configuration INI from the InputStream inputStream.

      Note that the given inputStream will not be closed by this method.

      Parameters:
      inputStream - the stream to read from
      charset - the charset used to load the configuration
      Returns:
      the configuration
      Throws:
      StorageConfigurationException - if the configuration couldn't be loaded

    • LoadXml

      static Configuration LoadXml​(String path)
      Tries to load the configuration XML file from path.

      The load order is as follows:

      • The classpath
      • As an URL
      • As a file
      Parameters:
      path - a classpath resource, a file path or an URL
      Returns:
      the configuration or null if none was found

    • LoadXml

      static Configuration LoadXml​(String path, Charset charset)
      Tries to load the configuration XML file from path.

      The load order is as follows:

      • The classpath
      • As an URL
      • As a file
      Parameters:
      path - a classpath resource, a file path or an URL
      charset - the charset used to load the configuration
      Returns:
      the configuration or null if none was found

    • LoadXml

      static Configuration LoadXml​(Path path)
      Tries to load the configuration XML file from path.
      Parameters:
      path - file system path
      Returns:
      the configuration
      Throws:
      StorageConfigurationException - if the configuration couldn't be loaded

    • LoadXml

      static Configuration LoadXml​(Path path, Charset charset)
      Tries to load the configuration XML file from path.
      Parameters:
      path - file system path
      charset - the charset used to load the configuration
      Returns:
      the configuration
      Throws:
      StorageConfigurationException - if the configuration couldn't be loaded

    • LoadXml

      static Configuration LoadXml​(File file)
      Tries to load the configuration XML from the file file.
      Parameters:
      file - file path
      Returns:
      the configuration
      Throws:
      StorageConfigurationException - if the configuration couldn't be loaded

    • LoadXml

      static Configuration LoadXml​(File file, Charset charset)
      Tries to load the configuration XML from the file file.
      Parameters:
      file - file path
      charset - the charset used to load the configuration
      Returns:
      the configuration
      Throws:
      StorageConfigurationException - if the configuration couldn't be loaded

    • LoadXml

      static Configuration LoadXml​(URL url)
      Tries to load the configuration XML from the URL url.
      Parameters:
      url - URL path
      Returns:
      the configuration
      Throws:
      StorageConfigurationException - if the configuration couldn't be loaded

    • LoadXml

      static Configuration LoadXml​(URL url, Charset charset)
      Tries to load the configuration XML from the URL url.
      Parameters:
      url - URL path
      charset - the charset used to load the configuration
      Returns:
      the configuration
      Throws:
      StorageConfigurationException - if the configuration couldn't be loaded

    • LoadXml

      static Configuration LoadXml​(InputStream inputStream)
      Tries to load the configuration XML from the InputStream inputStream.

      Note that the given inputStream will not be closed by this method.

      Parameters:
      inputStream - the stream to read from
      Returns:
      the configuration
      Throws:
      StorageConfigurationException - if the configuration couldn't be loaded

    • LoadXml

      static Configuration LoadXml​(InputStream inputStream, Charset charset)
      Tries to load the configuration XML from the InputStream inputStream.

      Note that the given inputStream will not be closed by this method.

      Parameters:
      inputStream - the stream to read from
      charset - the charset used to load the configuration
      Returns:
      the configuration
      Throws:
      StorageConfigurationException - if the configuration couldn't be loaded

    • exportXml

      default void exportXml​(OutputStream outputStream)
      Exports this configuration as XML.

      Note that the given outputStream will not be closed by this method.

      Parameters:
      outputStream - the outputStream to write to
      Since:
      3.1

    • exportXml

      default void exportXml​(OutputStream outputStream, Charset charset)
      Exports this configuration as XML.

      Note that the given outputStream will not be closed by this method.

      Parameters:
      outputStream - the outputStream to write to
      charset - the charset used to export the configuration
      Since:
      3.1

    • exportXml

      default void exportXml​(Path path)
      Exports this configuration as a XML file to the specified path.
      Parameters:
      path - the path to write to
      Since:
      3.1

    • exportXml

      default void exportXml​(Path path, Charset charset)
      Exports this configuration as a XML file to the specified path.
      Parameters:
      path - the path to write to
      charset - the charset used to export the configuration
      Since:
      3.1

    • exportXml

      default void exportXml​(File file)
      Exports this configuration as a XML file.
      Parameters:
      file - the file to write to
      Since:
      3.1

    • exportXml

      default void exportXml​(File file, Charset charset)
      Exports this configuration as a XML file.
      Parameters:
      file - the file to write to
      charset - the charset used to export the configuration
      Since:
      3.1

    • exportXml

      default void exportXml​(URL url)
      Exports this configuration as a XML file.
      Parameters:
      url - the URL to write to
      Since:
      3.1

    • exportXml

      default void exportXml​(URL url, Charset charset)
      Exports this configuration as a XML file.
      Parameters:
      url - the URL to write to
      charset - the charset used to export the configuration
      Since:
      3.1

    • exportIni

      default void exportIni​(OutputStream outputStream)
      Exports this configuration as INI.

      Note that the given outputStream will not be closed by this method.

      Parameters:
      outputStream - the outputStream to write to
      Since:
      3.1

    • exportIni

      default void exportIni​(OutputStream outputStream, Charset charset)
      Exports this configuration as INI.

      Note that the given outputStream will not be closed by this method.

      Parameters:
      outputStream - the outputStream to write to
      charset - the charset used to export the configuration
      Since:
      3.1

    • exportIni

      default void exportIni​(Path path)
      Exports this configuration as an INI file to the specified path.
      Parameters:
      path - the path to write to
      Since:
      3.1

    • exportIni

      default void exportIni​(Path path, Charset charset)
      Exports this configuration as an INI file to the specified path.
      Parameters:
      path - the path to write to
      charset - the charset used to export the configuration
      Since:
      3.1

    • exportIni

      default void exportIni​(File file)
      Exports this configuration as a INI file.
      Parameters:
      file - the file to write to
      Since:
      3.1

    • exportIni

      default void exportIni​(File file, Charset charset)
      Exports this configuration as a INI file.
      Parameters:
      file - the file to write to
      charset - the charset used to export the configuration
      Since:
      3.1

    • exportIni

      default void exportIni​(URL url)
      Exports this configuration as a INI file.
      Parameters:
      url - the URL to write to
      Since:
      3.1

    • exportIni

      default void exportIni​(URL url, Charset charset)
      Exports this configuration as a INI file.
      Parameters:
      url - the URL to write to
      charset - the charset used to export the configuration
      Since:
      3.1

    • createEmbeddedStorageFoundation

      default EmbeddedStorageFoundation<?> createEmbeddedStorageFoundation()
      Creates an EmbeddedStorageFoundation based on the settings of this Configuration.
      Returns:
      an EmbeddedStorageFoundation
      See Also:
      EmbeddedStorageFoundationCreator

    • setBaseDirectory

      Configuration setBaseDirectory​(String baseDirectory)
      The base directory of the storage in the file system.

    • setBaseDirectoryInUserHome

      default Configuration setBaseDirectoryInUserHome​(String baseDirectoryInUserHome)
      The base directory of the storage in the file system.
      Parameters:
      baseDirectoryInUserHome - relative location in the user home directory

    • getBaseDirectory

      String getBaseDirectory()
      The base directory of the storage in the file system.

    • setDeletionDirectory

      Configuration setDeletionDirectory​(String deletionDirectory)
      The deletion directory.

    • getDeletionDirectory

      String getDeletionDirectory()
      The deletion directory.

    • setTruncationDirectory

      Configuration setTruncationDirectory​(String truncationDirectory)
      The truncation directory.

    • getTruncationDirectory

      String getTruncationDirectory()
      The truncation directory.

    • setBackupDirectory

      Configuration setBackupDirectory​(String backupDirectory)
      The backup directory.

    • setBackupDirectoryInUserHome

      default Configuration setBackupDirectoryInUserHome​(String backupDirectoryInUserHome)
      The backup directory.
      Parameters:
      backupDirectoryInUserHome - relative location in the user home directory

    • getBackupDirectory

      String getBackupDirectory()
      The backup directory.

    • setChannelCount

      Configuration setChannelCount​(int channelCount)
      The number of threads and number of directories used by the storage engine. Every thread has exclusive access to its directory. Default is 1.
      Parameters:
      channelCount - the new channel count, must be a power of 2

    • getChannelCount

      int getChannelCount()
      The number of threads and number of directories used by the storage engine. Every thread has exclusive access to its directory.

    • setChannelDirectoryPrefix

      Configuration setChannelDirectoryPrefix​(String channelDirectoryPrefix)
      Name prefix of the subdirectories used by the channel threads. Default is "channel_".
      Parameters:
      channelDirectoryPrefix - new prefix

    • getChannelDirectoryPrefix

      String getChannelDirectoryPrefix()
      Name prefix of the subdirectories used by the channel threads.

    • setDataFilePrefix

      Configuration setDataFilePrefix​(String dataFilePrefix)
      Name prefix of the storage files. Default is "channel_".
      Parameters:
      dataFilePrefix - new prefix

    • getDataFilePrefix

      String getDataFilePrefix()
      Name prefix of the storage files.

    • setDataFileSuffix

      Configuration setDataFileSuffix​(String dataFileSuffix)
      Name suffix of the storage files. Default is ".dat".
      Parameters:
      dataFileSuffix - new suffix

    • getDataFileSuffix

      String getDataFileSuffix()
      Name suffix of the storage files.

    • setTransactionFilePrefix

      Configuration setTransactionFilePrefix​(String transactionFilePrefix)
      Name prefix of the storage transaction file. Default is "transactions_".
      Parameters:
      transactionFilePrefix - new prefix

    • getTransactionFilePrefix

      String getTransactionFilePrefix()
      Name prefix of the storage transaction file.

    • setTransactionFileSuffix

      Configuration setTransactionFileSuffix​(String transactionFileSuffix)
      Name suffix of the storage transaction file. Default is ".sft".
      Parameters:
      transactionFileSuffix - new suffix

    • getTransactionFileSuffix

      String getTransactionFileSuffix()
      Name suffix of the storage transaction file.

    • setTypeDictionaryFilename

      Configuration setTypeDictionaryFilename​(String typeDictionaryFilename)
      The name of the dictionary file. Default is "PersistenceTypeDictionary.ptd".
      Parameters:
      typeDictionaryFilename - new name

    • getTypeDictionaryFilename

      String getTypeDictionaryFilename()
      The name of the dictionary file.

    • setRescuedFileSuffix

      Configuration setRescuedFileSuffix​(String rescuedFileSuffix)

    • getRescuedFileSuffix

      String getRescuedFileSuffix()

    • setLockFileName

      Configuration setLockFileName​(String lockFileName)

    • getLockFileName

      String getLockFileName()

    • setHouseKeepingInterval

      @Deprecated default Configuration setHouseKeepingInterval​(long houseKeepingInterval)
      Deprecated.
      replaced by setHousekeepingIntervalMs(long), will be removed in a future release

    • setHousekeepingIntervalMs

      Configuration setHousekeepingIntervalMs​(long houseKeepingIntervalMs)
      Interval in milliseconds for the houskeeping. This is work like garbage collection or cache checking. In combination with setHousekeepingTimeBudgetNs(long) the maximum processor time for housekeeping work can be set. Default is 1000 (every second).
      Parameters:
      houseKeepingIntervalMs - the new interval
      See Also:
      setHousekeepingTimeBudgetNs(long)

    • getHouseKeepingInterval

      @Deprecated default long getHouseKeepingInterval()
      Deprecated.
      replaced by getHousekeepingIntervalMs(), will be removed in a future release

    • getHousekeepingIntervalMs

      long getHousekeepingIntervalMs()
      Interval in milliseconds for the houskeeping. This is work like garbage collection or cache checking.
      See Also:
      getHousekeepingTimeBudgetNs()

    • setHouseKeepingNanoTimeBudget

      @Deprecated default Configuration setHouseKeepingNanoTimeBudget​(long houseKeepingNanoTimeBudget)
      Deprecated.
      replaced by setHousekeepingTimeBudgetNs(long), will be removed in a future release

    • setHousekeepingTimeBudgetNs

      Configuration setHousekeepingTimeBudgetNs​(long housekeepingTimeBudgetNs)
      Number of nanoseconds used for each housekeeping cycle. However, no matter how low the number is, one item of work will always be completed. But if there is nothing to clean up, no processor time will be wasted. Default is 10000000 (10 million nanoseconds = 10 milliseconds = 0.01 seconds).
      Parameters:
      housekeepingTimeBudgetNs - the new time budget
      See Also:
      setHousekeepingIntervalMs(long)

    • getHouseKeepingNanoTimeBudget

      @Deprecated default long getHouseKeepingNanoTimeBudget()
      Deprecated.
      replaced by getHousekeepingTimeBudgetNs(), will be removed in a future release

    • getHousekeepingTimeBudgetNs

      long getHousekeepingTimeBudgetNs()
      Number of nanoseconds used for each housekeeping cycle. However, no matter how low the number is, one item of work will always be completed. But if there is nothing to clean up, no processor time will be wasted.
      See Also:
      getHousekeepingIntervalMs()

    • setEntityCacheThreshold

      Configuration setEntityCacheThreshold​(long entityCacheThreshold)
      Abstract threshold value for the lifetime of entities in the cache. See StorageEntityCacheEvaluator. Default is 1000000000.
      Parameters:
      entityCacheThreshold - the new threshold

    • getEntityCacheThreshold

      long getEntityCacheThreshold()
      Abstract threshold value for the lifetime of entities in the cache. See StorageEntityCacheEvaluator.

    • setEntityCacheTimeout

      @Deprecated default Configuration setEntityCacheTimeout​(long entityCacheTimeout)
      Deprecated.
      replaced by setEntityCacheTimeoutMs(long), will be removed in a future release

    • setEntityCacheTimeoutMs

      Configuration setEntityCacheTimeoutMs​(long entityCacheTimeoutMs)
      Timeout in milliseconds for the entity cache evaluator. If an entity wasn't accessed in this timespan it will be removed from the cache. Default is 86400000 (1 day).
      Parameters:
      entityCacheTimeoutMs -
      See Also:
      Duration

    • getEntityCacheTimeout

      @Deprecated default long getEntityCacheTimeout()
      Deprecated.
      replaced by getEntityCacheTimeoutMs(), will be removed in a future release

    • getEntityCacheTimeoutMs

      long getEntityCacheTimeoutMs()
      Timeout in milliseconds for the entity cache evaluator. If an entity wasn't accessed in this timespan it will be removed from the cache.

    • setDataFileMinSize

      @Deprecated default Configuration setDataFileMinSize​(int dataFileMinSize)
      Deprecated.
      replaced by setDataFileMinimumSize(int), will be removed in a future release

    • setDataFileMinimumSize

      Configuration setDataFileMinimumSize​(int dataFileMinimumSize)
      Minimum file size for a data file to avoid cleaning it up. Default is 1024^2 = 1 MiB.
      Parameters:
      dataFileMinimumSize - the new minimum file size
      See Also:
      setDataFileMinimumUseRatio(double)

    • getDataFileMinSize

      @Deprecated default int getDataFileMinSize()
      Deprecated.
      replaced by getDataFileMinimumSize(), will be removed in a future release

    • getDataFileMinimumSize

      int getDataFileMinimumSize()
      Minimum file size for a data file to avoid cleaning it up.
      See Also:
      getDataFileMinimumUseRatio()

    • setDataFileMaxSize

      @Deprecated default Configuration setDataFileMaxSize​(int dataFileMaxSize)
      Deprecated.
      replaced by setDataFileMaximumSize(int), will be removed in a future release

    • setDataFileMaximumSize

      Configuration setDataFileMaximumSize​(int dataFileMaximumSize)
      Maximum file size for a data file to avoid cleaning it up. Default is 1024^2*8 = 8 MiB.
      Parameters:
      dataFileMaximumSize - the new maximum file size
      See Also:
      setDataFileMinimumUseRatio(double)

    • getDataFileMaxSize

      @Deprecated default int getDataFileMaxSize()
      Deprecated.
      replaced by getDataFileMaximumSize(), will be removed in a future release

    • getDataFileMaximumSize

      int getDataFileMaximumSize()
      Maximum file size for a data file to avoid cleaning it up.
      See Also:
      getDataFileMinimumUseRatio()

    • setDataFileDissolveRatio

      @Deprecated default Configuration setDataFileDissolveRatio​(double dataFileDissolveRatio)
      Deprecated.
      replaced by setDataFileMinimumUseRatio(double), will be removed in a future release

    • setDataFileMinimumUseRatio

      Configuration setDataFileMinimumUseRatio​(double dataFileMinimumUseRatio)
      The ratio (value in ]0.0;1.0]) of non-gap data contained in a storage file to prevent the file from being dissolved. "Gap" data is anything that is not the latest version of an entity's data, inluding older versions of an entity and "comment" bytes (a sequence of bytes beginning with its length as a negative value length header).
      The closer this value is to 1.0 (100%), the less disk space is occupied by storage files, but the more file dissolving (data transfers to new files) is required and vice versa.
      Parameters:
      dataFileMinimumUseRatio - the new minimum use ratio

    • getDataFileDissolveRatio

      @Deprecated default double getDataFileDissolveRatio()
      Deprecated.
      replaced by getDataFileMinimumUseRatio(), will be removed in a future release

    • getDataFileMinimumUseRatio

      double getDataFileMinimumUseRatio()
      The ratio (value in ]0.0;1.0]) of non-gap data contained in a storage file to prevent the file from being dissolved. "Gap" data is anything that is not the latest version of an entity's data, inluding older versions of an entity and "comment" bytes (a sequence of bytes beginning with its length as a negative value length header).
      The closer this value is to 1.0 (100%), the less disk space is occupied by storage files, but the more file dissolving (data transfers to new files) is required and vice versa.

    • setDataFileCleanupHeadFile

      Configuration setDataFileCleanupHeadFile​(boolean dataFileCleanupHeadFile)
      A flag defining wether the current head file (the only file actively written to) shall be subjected to file cleanups as well.
      Parameters:
      dataFileCleanupHeadFile -

    • getDataFileCleanupHeadFile

      boolean getDataFileCleanupHeadFile()
      A flag defining wether the current head file (the only file actively written to) shall be subjected to file cleanups as well.

    • Default

      static Configuration Default()
      Creates a new Configuration with the default settings.
      Returns:
      a new Configuration
      See Also:
      StorageFileProvider.Defaults, StorageChannelCountProvider.Defaults, StorageHousekeepingController.Defaults, StorageEntityCacheEvaluator.Defaults, StorageDataFileEvaluator.Defaults