com.sleepycat.je
Class EnvironmentConfig

java.lang.Object
  |
  +--com.sleepycat.je.EnvironmentMutableConfig
        |
        +--com.sleepycat.je.EnvironmentConfig

All Implemented Interfaces:

Cloneable

public class EnvironmentConfig

extends EnvironmentMutableConfig

Specifies the attributes of an environment.

To change the default settings for a database environment, an application creates a configuration object, customizes settings and uses it for environment construction. The set methods of this class validate the configuration values when the method is invoked. An IllegalArgumentException is thrown if the value is not valid for that attribute.

All commonly used environment attributes have convenience setter/getter methods defined in this class. For example, to change the default transaction timeout setting for an environment, the application should do the following:

// customize an environment configuration
EnvironmentConfig envConfig = new EnvironmentConfig();
envConfig.setTxnTimeout(10000);  // will throw if timeout value is invalid
 
// Open the environment.
Environment myEnvironment = new Environment(home, envConfig);

Additional parameters are described in the example.properties file found at the top level of the distribution package. These additional parameters will not be needed by most applications. This category of properties can be specified for the EnvironmentConfig object through a Properties object read by EnvironmentConfig(Properties), or individually through EnvironmentConfig.setConfigParam().

For example, an application can change the default btree node size with:

envConfig.setConfigParam("je.nodeMaxEntries", "256");

Environment configuration follows this order of precedence:

1. Configuration parameters specified in <environment home>/je.properties take first precedence.
2. Configuration parameters set in the EnvironmentConfig object used at Environment construction are next.
3. Any configuration parameters not set by the application are set to system defaults, described in the example.properties file.

An EnvironmentConfig can be used to specify both mutable and immutable environment properties. Immutable properties may be specified when the first Environment handle (instance) is opened for a given physical environment. When more handles are opened for the same environment, the following rules apply:

1. Immutable properties must equal the original values specified when constructing an Environment handle for an already open environment. When a mismatch occurs, an exception is thrown.
2. Mutable properties are ignored when constructing an Environment handle for an already open environment.

After an Environment has been constructed, it's mutable properties may be changed using Environment.setMutableConfig(com.sleepycat.je.EnvironmentMutableConfig). See EnvironmentMutableConfig for a list of mutable properties; all other properties are immutable. Whether a property is mutable or immutable is also listed in the example.properties file found at the top level of the distribution package.

Constructor Summary

EnvironmentConfig()
Create an EnvironmentConfig which isinitialized with the system default settings.

EnvironmentConfig(Properties properties)
Create an EnvironmentConfig which includes the properties specified in the properties parameter.

Method Summary

boolean	getAllowCreate() Return true if we may create this environment.
int	getCachePercent() Return the percentage value used in the JE cache size calculation.
long	getCacheSize() Return the memory available to the database system, in bytes.
String	getConfigParam(String configParamName) Return the value for this configuration parameter.
long	getLockTimeout() Return the lock timeout setting, in microseconds.
boolean	getReadOnly() Return if the database environment is configured to be read only.
boolean	getTransactional() Return if the database environment supports transactions.
long	getTxnTimeout() Return the transaction timeout, in microseconds.
void	setAllowCreate(boolean allowCreate) If true, the database environment is created if it doesn't already exist.
void	setCachePercent(int percent) By default, JE sets its cache size proportionally to the JVM memory.
void	setCacheSize(long cacheSize) Configure the memory available to the database system, in bytes.
void	setConfigParam(String configParamName, String value) Validate the value prescribed for the configuration parameter; if it is valid, the value is set in the configuration.
void	setLockTimeout(long lockTimeout) Configure the lock timeout, in microseconds.
void	setReadOnly(boolean readOnly) Configure the database environment to be read only, and any attempt to modify a database will fail.
void	setTransactional(boolean transactional) Configure the database environment to support transactions.
void	setTxnTimeout(long txnTimeout) Configure the transaction timeout, in microseconds.

Methods inherited from class com.sleepycat.je.EnvironmentMutableConfig

getTxnNoSync, setTxnNoSync

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EnvironmentConfig

public EnvironmentConfig()

Create an EnvironmentConfig which isinitialized with the system default settings.

EnvironmentConfig

public EnvironmentConfig(Properties properties)
                  throws IllegalArgumentException

Create an EnvironmentConfig which includes the properties specified in the properties parameter.

Parameters:

properties - Note that supported properties are described in the sample property file.

Throws:

IllegalArgumenentException - if any properties read from the the properties param are invalid.

IllegalArgumentException

Method Detail

setAllowCreate

public void setAllowCreate(boolean allowCreate)
                    throws IllegalArgumentException

If true, the database environment is created if it doesn't already exist.

Parameters:

allowCreate - If true, the database environment is created if it doesn't already exist.

Throws:

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

getAllowCreate

public boolean getAllowCreate()
                       throws IllegalArgumentException

Return true if we may create this environment.

Returns:

True if we may create this environment.

Throws:

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

setCacheSize

public void setCacheSize(long cacheSize)
                  throws IllegalArgumentException

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

Parameters:

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

Throws:

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

getCacheSize

public long getCacheSize()
                  throws IllegalArgumentException

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

Throws:

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

setCachePercent

public void 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.maxMemory property in the je.properties file.

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

Parameters:

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

Throws:

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

getCachePercent

public int getCachePercent()
                    throws IllegalArgumentException

Return the percentage value used in the JE cache size calculation.

Returns:

the percentage value used in the JE cache size calculation.

Throws:

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

setLockTimeout

public void setLockTimeout(long lockTimeout)
                    throws IllegalArgumentException

Configure the lock timeout, in microseconds.

A value of 0 turns off lock timeouts.

Equivalent to setting the je.lock.timeout parameter in the je.properties file.

Parameters:

lockTimeout - The lock timeout, in microseconds.

Throws:

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

getLockTimeout

public long getLockTimeout()
                    throws IllegalArgumentException

Return the lock timeout setting, in microseconds.

A value of 0 means no timeout is set.

Throws:

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

setReadOnly

public void setReadOnly(boolean readOnly)
                 throws IllegalArgumentException

Configure the database environment to be read only, and any attempt to modify a database will fail.

Parameters:

readOnly - If true, configure the database environment to be read only, and any attempt to modify a database will fail.

Throws:

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

getReadOnly

public boolean getReadOnly()
                    throws IllegalArgumentException

Return if the database environment is configured to be read only.

Returns:

If the database environment is configured to be read only.

Throws:

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

setTransactional

public void setTransactional(boolean transactional)
                      throws IllegalArgumentException

Configure the database environment to support transactions.

This configuration option should be used when transactional guarantees such as atomicity of multiple operations and durability are important.

Parameters:

transactional - If true, configure the database environment to support transactions.

Throws:

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

getTransactional

public boolean getTransactional()
                         throws IllegalArgumentException

Return if the database environment supports transactions.

Returns:

If the database environment supports transactions.

Throws:

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

setTxnTimeout

public void setTxnTimeout(long txnTimeout)
                   throws IllegalArgumentException

Configure the transaction timeout, in microseconds.

A value of 0 turns off transaction timeouts.

Equivalent to setting the je.lock.timeout parameter in the je.properties file.

Parameters:

txnTimeout - The transaction timeout, in microseconds.

Throws:

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

getTxnTimeout

public long getTxnTimeout()
                   throws IllegalArgumentException

Return the transaction timeout, in microseconds.

A value of 0 means transaction timeouts are not configured.

Returns:

The transaction timeout, in microseconds.

Throws:

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

setConfigParam

public void setConfigParam(String configParamName,
                           String value)
                    throws IllegalArgumentException

Description copied from class: EnvironmentMutableConfig

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

Overrides:

setConfigParam in class EnvironmentMutableConfig

Parameters:

configParamName - 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:

IllegalArgumentException - if an invalid parameter was specified.

getConfigParam

public String getConfigParam(String configParamName)
                      throws IllegalArgumentException

Description copied from class: EnvironmentMutableConfig

Return the value for this configuration parameter.

Overrides:

getConfigParam in class EnvironmentMutableConfig

Parameters:

configParamName - Name of the requested parameter.

Throws:

IllegalArgumentException - if the configParamName is invalid.