EnvironmentMutableConfig (Oracle - Berkeley DB Java Edition API)
Date: 2014-12-16

com.sleepycat.je

## Class EnvironmentMutableConfig

- java.lang.Object
- - com.sleepycat.je.EnvironmentMutableConfig

- All Implemented Interfaces:
    Serializable, Cloneable
  Direct Known Subclasses:
    EnvironmentConfig

      public class EnvironmentMutableConfig
      extends Object
      implements Cloneable, Serializable

  Specifies the environment attributes that may be changed after the environment has been opened. EnvironmentMutableConfig is a parameter to `Environment.setMutableConfig(com.sleepycat.je.EnvironmentMutableConfig)` and is returned by `Environment.getMutableConfig()`.

  There are two types of mutable environment properties: per-environment handle properties, and environment wide properties.

  #### Per-Environment Handle Properties

  Per-environment handle properties apply only to a single Environment instance. For example, to change the default transaction commit behavior for a single environment handle, do this:

  >          // Specify no-sync behavior for a given handle.
  >          EnvironmentMutableConfig mutableConfig = myEnvHandle.getMutableConfig();
  >          mutableConfig.setTxnNoSync(true);
  >          myEnvHandle.setMutableConfig(mutableConfig);

  The per-environment handle properties are listed below. These properties are accessed using the setter and getter methods listed, as shown in the example above.

  - `setDurability(com.sleepycat.je.Durability)`, `getDurability()`
  - `setTxnNoSync(boolean)`, `getTxnNoSync()` deprecated
  - `setTxnWriteNoSync(boolean)`, `getTxnWriteNoSync()` deprecated

  #### Environment-Wide Mutable Properties

  Environment-wide mutable properties are those that can be changed for an environment as a whole, irrespective of which environment instance (for the same physical environment) is used. For example, to stop the cleaner daemon thread, do this:

  >          // Stop the cleaner daemon thread for the environment.
  >          EnvironmentMutableConfig mutableConfig = myEnvHandle.getMutableConfig();
  >          mutableConfig.setConfigParam("je.env.runCleaner", "false");
  >          myEnvHandle.setMutableConfig(mutableConfig);

  The environment-wide mutable properties are listed below. These properties are accessed using the `setConfigParam(java.lang.String, java.lang.String)` and `getConfigParam(java.lang.String)` methods, as shown in the example above, using the property names listed below. In some cases setter and getter methods are also available.

  - je.maxMemory (`setCacheSize(long)`, `getCacheSize()`)
  - je.maxMemoryPercent (`setCachePercent(int)`, `getCachePercent()`)
  - je.env.runINCompressor
  - je.env.runEvictor
  - je.env.runCheckpointer
  - je.env.runCleaner

  #### Getting the Current Environment Properties

  To get the current "live" properties of an environment after constructing it or changing its properties, you must call `Environment.getConfig()` or `Environment.getMutableConfig()`. The original EnvironmentConfig or EnvironmentMutableConfig object used to set the properties is not kept up to date as properties are changed, and does not reflect property validation or properties that are computed. @see EnvironmentConfig
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `EnvironmentMutableConfig()` An instance created using the default constructor is initialized with the system's default settings.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `CacheMode` | `getCacheMode()` Returns the default `CacheMode` used for operations performed in this environment, or null if `CacheMode.DEFAULT` is used.
    `int` | `getCachePercent()` Returns the percentage value used in the JE cache size calculation.
    `long` | `getCacheSize()` Returns the memory available to the database system, in bytes.
    `String` | `getConfigParam(String paramName)` Returns the value for this configuration parameter.
    `Durability` | `getDurability()` Returns the durability associated with the configuration.
    `ExceptionListener` | `getExceptionListener()` Returns the exception listener, if set.
    `boolean` | `getTxnNoSync()` Deprecated. replaced by `getDurability()`
    `boolean` | `getTxnWriteNoSync()` Deprecated. replaced by `getDurability()`
    `EnvironmentMutableConfig` | `setCacheMode(CacheMode cacheMode)` Sets the default `CacheMode` used for operations performed in this environment.
    `EnvironmentMutableConfig` | `setCachePercent(int percent)` By default, JE sets its cache size proportionally to the JVM memory.
    `EnvironmentMutableConfig` | `setCacheSize(long totalBytes)` Configures the memory available to the database system, in bytes.
    `EnvironmentMutableConfig` | `setConfigParam(String paramName, String value)` Set this configuration parameter.
    `EnvironmentMutableConfig` | `setDurability(Durability durability)` Configures the durability associated with transactions.
    `EnvironmentMutableConfig` | `setExceptionListener(ExceptionListener exceptionListener)` Sets the exception listener for an Environment.
    `EnvironmentMutableConfig` | `setTxnNoSync(boolean noSync)` Deprecated. replaced by `setDurability(com.sleepycat.je.Durability)`
    `EnvironmentMutableConfig` | `setTxnWriteNoSync(boolean writeNoSync)` Deprecated. replaced by `setDurability(com.sleepycat.je.Durability)`
    `String` | `toString()` Display configuration values.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### EnvironmentMutableConfig

          public EnvironmentMutableConfig()

      An instance created using the default constructor is initialized with the system's default settings.

  - ### Method Detail

    - #### setTxnNoSync

          public EnvironmentMutableConfig setTxnNoSync(boolean noSync)

      Deprecated. replaced by `setDurability(com.sleepycat.je.Durability)`
      Configures the database environment for asynchronous transactions.
      Parameters:
        `noSync` - If true, do not write or synchronously flush the log on transaction commit. This means that transactions exhibit the ACI (Atomicity, Consistency, and Isolation) properties, but not D (Durability); that is, database integrity is maintained, but if the JVM or operating system fails, it is possible some number of the most recently committed transactions may be undone during recovery. The number of transactions at risk is governed by how many updates fit into a log buffer, how often the operating system flushes dirty buffers to disk, and how often the database environment is checkpointed.

        This attribute is false by default for this class and for the database environment.

    - #### getTxnNoSync

          public boolean getTxnNoSync()

      Deprecated. replaced by `getDurability()`
      Returns true if the database environment is configured for asynchronous transactions.
      Returns:
        true if the database environment is configured for asynchronous transactions.

    - #### setTxnWriteNoSync

          public EnvironmentMutableConfig setTxnWriteNoSync(boolean writeNoSync)

      Deprecated. replaced by `setDurability(com.sleepycat.je.Durability)`
      Configures the database environment for transactions which write but do not flush the log.
      Parameters:
        `writeNoSync` - If true, write but do not synchronously flush the log on transaction commit. This means that transactions exhibit the ACI (Atomicity, Consistency, and Isolation) properties, but not D (Durability); that is, database integrity is maintained, but if the operating system fails, it is possible some number of the most recently committed transactions may be undone during recovery. The number of transactions at risk is governed by how often the operating system flushes dirty buffers to disk, and how often the database environment is checkpointed.

        The motivation for this attribute is to provide a transaction that has more durability than asynchronous (nosync) transactions, but has higher performance than synchronous transactions.

        This attribute is false by default for this class and for the database environment.

    - #### getTxnWriteNoSync

          public boolean getTxnWriteNoSync()

      Deprecated. replaced by `getDurability()`
      Returns true if the database environment is configured for transactions which write but do not flush the log.
      Returns:
        true if the database environment is configured for transactions which write but do not flush the log.

    - #### setDurability

          public EnvironmentMutableConfig setDurability(Durability durability)

      Configures the durability associated with transactions.

      Equivalent to setting the je.txn.durability property in the je.properties file.

      Parameters:
        `durability` - the new durability definition
      Returns:
        this
      See Also:
        `Durability`

    - #### getDurability

          public Durability getDurability()

      Returns the durability associated with the configuration.
      Returns:
        the durability setting currently associated with this config.

    - #### setCacheSize

          public EnvironmentMutableConfig setCacheSize(long totalBytes)
                                                throws IllegalArgumentException

      Configures the memory available to the database system, in bytes.

      Equivalent to setting the je.maxMemory property in the je.properties file. The system will evict database objects when it comes within a prescribed margin of the limit.

      By default, JE sets the cache size to:

                   (je.maxMemoryPercent *  JVM maximum memory) / 100

      where JVM maximum memory is specified by the JVM -Xmx flag. However, calling setCacheSize() with a non-zero value overrides the percentage based calculation and sets the cache size explicitly.

      Note that the log buffer cache may be cleared if the cache size is changed after the environment has been opened.

      If setSharedCache(true) is called, setCacheSize and setCachePercent specify the total size of the shared cache, and changing these parameters will change the size of the shared cache.

      To take full advantage of JE cache memory, it is strongly recommended that compressed oops (`-XX:+UseCompressedOops`) is specified when a 64-bit JVM is used and the maximum heap size is less than 32 GB. As described in the referenced documentation, compressed oops is sometimes the default JVM mode even when it is not explicitly specified in the Java command. However, if compressed oops is desired then it must be explicitly specified in the Java command when running DbCacheSize or a JE application. If it is not explicitly specified then JE will not aware of it, even if it is the JVM default setting, and will not take it into account when calculating cache memory sizes.

      Parameters:
        `totalBytes` - The memory available to the database system, in bytes.
      Returns:
        this
      Throws:
        `IllegalArgumentException` - if an invalid parameter is specified.

    - #### getCacheSize

          public long getCacheSize()

      Returns the memory available to the database system, in bytes. A valid value is only available if this EnvironmentConfig object has been returned from Environment.getConfig();
      Returns:
        The memory available to the database system, in bytes.

    - #### setCachePercent

          public EnvironmentMutableConfig setCachePercent(int percent)
                                                   throws IllegalArgumentException

      By default, JE sets its cache size proportionally to the JVM memory. This formula is used:

      >              je.maxMemoryPercent *  JVM maximum memory

      where JVM maximum memory is specified by the JVM -Xmx flag. setCachePercent() specifies the percentage used and is equivalent to setting the je.maxMemoryPercent property in the je.properties file.

      Calling setCacheSize() with a non-zero value overrides the percentage based calculation and sets the cache size explicitly.

      Note that the log buffer cache may be cleared if the cache size is changed after the environment has been opened.

      If setSharedCache(true) is called, setCacheSize and setCachePercent specify the total size of the shared cache, and changing these parameters will change the size of the shared cache.

      To take full advantage of JE cache memory, it is strongly recommended that compressed oops (`-XX:+UseCompressedOops`) is specified when a 64-bit JVM is used and the maximum heap size is less than 32 GB. As described in the referenced documentation, compressed oops is sometimes the default JVM mode even when it is not explicitly specified in the Java command. However, if compressed oops is desired then it must be explicitly specified in the Java command when running DbCacheSize or a JE application. If it is not explicitly specified then JE will not aware of it, even if it is the JVM default setting, and will not take it into account when calculating cache memory sizes.

      Parameters:
        `percent` - The percent of JVM memory to allocate to the JE cache.
      Returns:
        this
      Throws:
        `IllegalArgumentException` - if an invalid parameter is specified.

    - #### getCachePercent

          public int getCachePercent()

      Returns the percentage value used in the JE cache size calculation.
      Returns:
        the percentage value used in the JE cache size calculation.

    - #### setExceptionListener

          public EnvironmentMutableConfig setExceptionListener(ExceptionListener exceptionListener)

      Sets the exception listener for an Environment. The listener is called when a daemon thread throws an exception, in order to provide a notification mechanism for these otherwise asynchronous exceptions. Daemon thread exceptions are also printed through stderr.

      Not all daemon exceptions are fatal, and the application bears responsibility for choosing how to respond to the notification. Since exceptions may repeat, the application should also choose how to handle a spate of exceptions. For example, the application may choose to act upon each notification, or it may choose to batch up its responses by implementing the listener so it stores exceptions, and only acts when a certain number have been received.

      Parameters:
        `exceptionListener` - the callback to be executed when an exception occurs.
      Returns:
        this

    - #### getExceptionListener

          public ExceptionListener getExceptionListener()

      Returns the exception listener, if set.

    - #### setCacheMode

          public EnvironmentMutableConfig setCacheMode(CacheMode cacheMode)

      Sets the default `CacheMode` used for operations performed in this environment. The default cache mode may be overridden on a per-database basis using `DatabaseConfig.setCacheMode(com.sleepycat.je.CacheMode)`, and on a per-record or per-operation basis using `Cursor.setCacheMode(com.sleepycat.je.CacheMode)`.
      Parameters:
        `cacheMode` - is the default `CacheMode` used for operations performed in this environment. If `null` is specified, `CacheMode.DEFAULT` will be used.
      Since:
        4.0.97
      See Also:
        `for further details.`

    - #### getCacheMode

          public CacheMode getCacheMode()

      Returns the default `CacheMode` used for operations performed in this environment, or null if `CacheMode.DEFAULT` is used.
      Returns:
        the default `CacheMode` used for operations performed on this database, or null if `CacheMode.DEFAULT` is used.
      Since:
        4.0.97
      See Also:
        `setCacheMode(com.sleepycat.je.CacheMode)`

    - #### setConfigParam

          public EnvironmentMutableConfig setConfigParam(String paramName,
                                                String value)
                                                  throws IllegalArgumentException

      Set this configuration parameter. First validate the value specified for the configuration parameter; if it is valid, the value is set in the configuration.
      Parameters:
        `paramName` - the configuration parameter name, one of the String constants in this class
        `value` - The configuration value
      Returns:
        this
      Throws:
        `IllegalArgumentException` - if the paramName or value is invalid.

    - #### getConfigParam

          public String getConfigParam(String paramName)
                                throws IllegalArgumentException

      Returns the value for this configuration parameter.
      Parameters:
        `paramName` - a valid configuration parameter, one of the String constants in this class.
      Returns:
        the configuration value.
      Throws:
        `IllegalArgumentException` - if the paramName is invalid.

    - #### toString

          public String toString()

      Display configuration values.
      Overrides:
        `toString` in class `Object`

Copyright (c) 2004, 2014 Oracle and/or its affiliates. All rights reserved.