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 = env.getMutableConfig();
     mutableConfig.setTxnNoSync(true);
     env.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 threads for the environment.
     EnvironmentMutableConfig mutableConfig = env.getMutableConfig();
     mutableConfig.setConfigParam(EnvironmentConfig.ENV_RUN_CLEANER, "false");
     env.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

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.
long	getOffHeapCacheSize() Returns the number of bytes to be used as a secondary, off-heap cache.
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) Configures the memory available to the database system, as a percentage of the JVM maximum 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	setOffHeapCacheSize(long totalBytes) Configures the number of bytes to be used as a secondary, off-heap cache.
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. Calling setCacheSize() is equivalent to setting EnvironmentConfig.MAX_MEMORY.

The following details apply to setting the cache size to a byte size (this method) as well as to a percentage of the JVM heap size (see setCachePercent(int)

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.

When using the shared cache feature, new environments that join the cache may alter the cache percent setting if their configuration is set to a different value.

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

Configures the memory available to the database system, as a percentage of the JVM maximum memory.

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 EnvironmentConfig.MAX_MEMORY_PERCENT.

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

See setCacheSize(long) for additional details.

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.

setOffHeapCacheSize

public EnvironmentMutableConfig setOffHeapCacheSize(long totalBytes)
                                             throws IllegalArgumentException

Configures the number of bytes to be used as a secondary, off-heap cache. The off-heap cache is used to hold record data and Btree nodes when these are evicted from the "main cache" because it overflows. Eviction occurs according to an LRU algorithm and takes into account the user- specified CacheMode. When the off-heap cache overflows, eviction occurs there also according to the same algorithm.

The main cache is in the Java heap and consists primarily of the Java objects making up the in-memory Btree data structure. Btree objects are not serialized the main cache, so no object materialization is needed to access the Btree there. Access to records in the main cache is therefore very fast, but the main cache has drawbacks as well: 1) The larger the main cache, the more likely it is to have Java GC performance problems. 2) When the Java heap exceeds 32GB, the "compressed OOPs" setting no longer applies and less data will fit in the same amount of memory. For these reasons, JE applications often configure a heap of 32GB or less, and a main cache that is significantly less than 32GB, leaving any additional machine memory for use by the file system cache.

The use of the file system cache has performance benefits, but also has its own drawbacks: 1) There is a significant redundancy between the main cache and the file system cache because all data and Btree information that is logged (written) by JE appears in the file system and may also appear in the main cache. 2) It is not possible for dirty Btree information to be placed in the file system cache without logging it, this logging may be otherwise unnecessary, and the logging creates additional work for the JE cleaner; in other words, the size of the main cache alone determines the maximum size of the in-memory "dirty set".

The off-heap cache is stored outside the Java heap using a native platform memory allocator. The current implementation relies on internals that are specific to the Oracle and IBM JDKs; however, a memory allocator interface that can be implemented for other situations is being considered for a future release. Records and Btree objects are serialized when they are placed in the off-heap cache, and they must be materialized when they are moved back to the main cache in order to access them. This serialization and materialization adds some CPU overhead and thread contention, as compared to accessing data directly in the main cache. The off-heap cache can contain dirty Btree information, so it can be used to increase the maximum size of the in-memory "dirty set".

NOTE: If an off-heap cache is configured but cannot be used because that native allocator is not available in the JDK that is used, an IllegalStateException will be thrown by the Environment or ReplicatedEnvironment constructor. In the current release, this means that the sun.misc.Unsafe class must contain the allocateMemory method and related methods, as defined in the Oracle JDK.

When configuring an off-heap cache you can think of the performance trade-offs in two ways. First, if the off-heap cache is considered to be a replacement for the file system cache, the serialization and materialization overhead is not increased. In this case, the use of the off-heap cache is clearly beneficial, and using the off-heap cache "instead of" the file system cache is normally recommended. Second, the off-heap cache can be used along with a main cache that is reduced in size in order to compensate for Java GC problems. In this case, the trade-off is between the additional serialization, materialization and contention overheads of the off-heap cache, as compared to the Java GC overhead.

When dividing up available memory for the JVM heap, the off-heap cache, and for other uses, please be aware that the file system cache and the off-heap cache are different in one important respect. The file system cache automatically shrinks when memory is needed by the OS or other processes, while the off-heap cache does not. Therefore, it is best to be conservative about leaving memory free for other uses, and it is not a good idea to size the off-heap cache such that all machine memory will be allocated. If off-heap allocations or other allocations fail because there is no available memory, the process is likely to die without any exception being thrown. In one test on Linux, for example, the process was killed abruptly by the OS and the only indication of the problem was the following shown by dmesg.

 Out of memory: Kill process 28768 (java) score 974 or sacrifice child
 Killed process 28768 (java)
    total-vm:278255336kB, anon-rss:257274420kB, file-rss:0kB
 

WARNING: Although this configuration property is mutable, it cannot be changed from zero to non-zero, or non-zero to zero. In other words, the size of the off-heap cache can be changed after initially configuring a non-zero size, but the off-heap cache cannot be turned on and off dynamically. An attempt to do so will cause an IllegalArgumentException to be thrown by the Environment or ReplicatedEnvironment constructor.

Throws:

IllegalArgumentException

getOffHeapCacheSize

public long getOffHeapCacheSize()

Returns the number of bytes to be used as a secondary, off-heap cache.

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), ReadOptions.setCacheMode(CacheMode) or WriteOptions.setCacheMode(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