com.sleepycat.je

Class EnvironmentMutableConfig

java.lang.Object

com.sleepycat.je.EnvironmentMutableConfig

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

EnvironmentConfig

public class EnvironmentMutableConfig
extends java.lang.Object
implements java.lang.Cloneable

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.

• setTxnNoSync(boolean), getTxnNoSync()
• setTxnWriteNoSync(boolean), getTxnWriteNoSync()

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

Field Summary

Fields

Modifier and Type	Field and Description
protected long	cacheSize
protected java.util.Properties	props
(package private) boolean	validateParams Internal boolean that says whether or not to validate params.

Constructor Summary

Constructors

Constructor and Description
EnvironmentMutableConfig() An instance created using the default constructor is initialized with the system's default settings.
EnvironmentMutableConfig(java.util.Properties properties) Used by EnvironmentConfig to construct from properties.

Method Summary

Methods

Modifier and Type	Method and Description
(package private) void	checkImmutablePropsForEquality(EnvironmentMutableConfig passedConfig) Checks that the immutable values in the environment config used to open an environment match those in the config object saved by the underlying shared EnvironmentImpl.
protected java.lang.Object	clone()
(package private) EnvironmentMutableConfig	cloneMutableConfig() Used by Environment to create a copy of the application supplied configuration.
(package private) void	copyHandlePropsTo(EnvironmentMutableConfig other) Copies the per-handle properties of this object to the given config object.
(package private) void	copyMutablePropsTo(EnvironmentMutableConfig toConfig) Copies all mutable props to the given config object.
(package private) void	fillInEnvironmentGeneratedProps(EnvironmentImpl envImpl) Fills in the properties calculated by the environment to the given config object.
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.
java.lang.String	getConfigParam(java.lang.String paramName) Returns the value for this configuration parameter.
ReplicaConsistencyPolicy	getConsistencyPolicy()
Durability	getDurability()
ExceptionListener	getExceptionListener() Returns the exception listener, if set.
(package private) boolean	getLoadPropertyFile() For unit testing, to prevent loading of je.properties.
int	getNumExplicitlySetParams() Testing support
(package private) java.util.Properties	getProps()
boolean	getTxnNoSync() Returns true if the database environment is configured for asynchronous transactions.
boolean	getTxnWriteNoSync() Returns true if the database environment is configured for transactions which write but do not flush the log.
void	setCachePercent(int percent) By default, JE sets its cache size proportionally to the JVM memory.
void	setCacheSize(long totalBytes) Configures the memory available to the database system, in bytes.
void	setConfigParam(java.lang.String paramName, java.lang.String value) Validates the value prescribed for the configuration parameter; if it is valid, the value is set in the configuration.
void	setConsistencyPolicy(ReplicaConsistencyPolicy consistencyPolicy)
void	setDurability(Durability durability)
void	setExceptionListener(ExceptionListener exceptionListener) Sets the exception listener for an Environment.
(package private) void	setLoadPropertyFile(boolean loadPropertyFile) For unit testing, to prevent loading of je.properties.
void	setTxnNoSync(boolean noSync) Configures the database environment for asynchronous transactions.
void	setTxnWriteNoSync(boolean writeNoSync) Configures the database environment for transactions which write but do not flush the log.
(package private) void	setValidateParams(boolean validateParams)
java.lang.String	toString() Display configuration values.

Methods inherited from class java.lang.Object

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

Field Detail

cacheSize

protected long cacheSize

props

protected java.util.Properties props

validateParams

boolean validateParams

Internal boolean that says whether or not to validate params. Setting it to false means that parameter value validatation won't be performed during setVal() calls. Only should be set to false by unit tests using DbInternal.

Constructor Detail

EnvironmentMutableConfig

public EnvironmentMutableConfig()

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

EnvironmentMutableConfig

EnvironmentMutableConfig(java.util.Properties properties)
                   throws java.lang.IllegalArgumentException

Used by EnvironmentConfig to construct from properties.

Throws:

java.lang.IllegalArgumentException

Method Detail

setTxnNoSync

public void setTxnNoSync(boolean noSync)

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.

Throws:

DatabaseException - if a failure occurs.

getTxnNoSync

public boolean getTxnNoSync()

Returns true if the database environment is configured for asynchronous transactions.

Returns:

true if the database environment is configured for asynchronous transactions.

setTxnWriteNoSync

public void setTxnWriteNoSync(boolean writeNoSync)

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.

Throws:

DatabaseException - if a failure occurs.

getTxnWriteNoSync

public boolean getTxnWriteNoSync()

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 void setDurability(Durability durability)

Parameters:

durability - the durability definition

getDurability

public Durability getDurability()

Returns:

the durability setting currently associated with this config.

setConsistencyPolicy

public void setConsistencyPolicy(ReplicaConsistencyPolicy consistencyPolicy)

Parameters:

consistencyPolicy - the consistency definition

getConsistencyPolicy

public ReplicaConsistencyPolicy getConsistencyPolicy()

Returns:

the consistency policy currently associated with this config.

setCacheSize

public void setCacheSize(long totalBytes)
                  throws java.lang.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
 

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.

Parameters:

totalBytes - The memory available to the database system, in bytes.

Throws:

java.lang.IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

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 void setCachePercent(int percent)
                     throws java.lang.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.

Parameters:

percent - The percent of JVM memory to allocate to the JE cache.

Throws:

java.lang.IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

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

getExceptionListener

public ExceptionListener getExceptionListener()

Returns the exception listener, if set.

setConfigParam

public void setConfigParam(java.lang.String paramName,
                  java.lang.String value)
                    throws java.lang.IllegalArgumentException

Validates the value prescribed for the configuration parameter; if it is valid, the value is set in the configuration.

Parameters:

paramName - The name of the configuration parameter. See the sample je.properties file for descriptions of all parameters.

value - The value for this configuration parameter.

Throws:

java.lang.IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

getConfigParam

public java.lang.String getConfigParam(java.lang.String paramName)
                                throws java.lang.IllegalArgumentException

Returns the value for this configuration parameter.

Parameters:

paramName - Name of the requested parameter.

Throws:

java.lang.IllegalArgumentException - if the configParamName is invalid.

setValidateParams

void setValidateParams(boolean validateParams)

checkImmutablePropsForEquality

void checkImmutablePropsForEquality(EnvironmentMutableConfig passedConfig)
                              throws java.lang.IllegalArgumentException

Checks that the immutable values in the environment config used to open an environment match those in the config object saved by the underlying shared EnvironmentImpl.

Throws:

java.lang.IllegalArgumentException

clone

protected java.lang.Object clone()
                          throws java.lang.CloneNotSupportedException

Overrides:

clone in class java.lang.Object

Throws:

java.lang.CloneNotSupportedException

cloneMutableConfig

EnvironmentMutableConfig cloneMutableConfig()

Used by Environment to create a copy of the application supplied configuration. Done this way to provide non-public cloning.

copyHandlePropsTo

void copyHandlePropsTo(EnvironmentMutableConfig other)

Copies the per-handle properties of this object to the given config object.

copyMutablePropsTo

void copyMutablePropsTo(EnvironmentMutableConfig toConfig)

Copies all mutable props to the given config object. Unchecked suppress here because Properties don't play well with generics in Java 1.5

fillInEnvironmentGeneratedProps

void fillInEnvironmentGeneratedProps(EnvironmentImpl envImpl)

Fills in the properties calculated by the environment to the given config object.

getProps

java.util.Properties getProps()

setLoadPropertyFile

void setLoadPropertyFile(boolean loadPropertyFile)

For unit testing, to prevent loading of je.properties.

getLoadPropertyFile

boolean getLoadPropertyFile()

For unit testing, to prevent loading of je.properties.

getNumExplicitlySetParams

public int getNumExplicitlySetParams()

Testing support

toString

public java.lang.String toString()

Display configuration values.

Overrides:

toString in class java.lang.Object