Berkeley DB Java Edition version 3.2.76

## 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 initialized 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 if we may create this environment.
`String` `getConfigParam(String configParamName)` Return the value for this configuration parameter.
`ExceptionListener` `getExceptionListener()` Returns the exception listener, if set.
`boolean` `getLocking()` Return true if the database environment is configured for locking.
`long` `getLockTimeout()` Return the lock timeout setting, in microseconds.
`boolean` `getReadOnly()` Return true if the database environment is configured to be read only.
`boolean` `getTransactional()` Return true if the database environment is configured for transactions.
`boolean` `getTxnSerializableIsolation()` Return if all transactions for this environment has been configured to have Serializable (Degree 3) isolation.
`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` `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` `setExceptionListener(ExceptionListener exceptionListener)` Sets the exception listener for an Environment.
`void` `setLocking(boolean locking)` Configure the database environment for no locking.
`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 for transactions.
`void` `setTxnSerializableIsolation(boolean serializableIsolation)` Configure all transactions for this environment to have Serializable (Degree 3) isolation.
`void` `setTxnTimeout(long txnTimeout)` Configure the transaction timeout, in microseconds.

Methods inherited from class com.sleepycat.je.EnvironmentMutableConfig
`getCachePercent, getCacheSize, getTxnNoSync, getTxnWriteNoSync, setCachePercent, setCacheSize, setTxnNoSync, setTxnWriteNoSync`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### EnvironmentConfig

    public EnvironmentConfig()

  Create an EnvironmentConfig initialized 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` - Supported properties are described in the sample property file.

  Throws:
    `IllegalArgumentException` - If any properties read from the properties param are invalid.

Method Detail

### setAllowCreate

    public void setAllowCreate(boolean allowCreate)

  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.

### getAllowCreate

    public boolean getAllowCreate()

  Return if we may create this environment.

  Returns:
    If true, we may create this environment.

### setLockTimeout

    public void setLockTimeout(long lockTimeout)
                        throws IllegalArgumentException

  Configure the lock timeout, in microseconds.

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

  Parameters:
    `lockTimeout` - The lock timeout, in microseconds. A value of 0 turns off lock timeouts.
  Throws:
    `IllegalArgumentException` - If the value of timeout is negative.
  See Also:
    `Transaction.setLockTimeout(long)`

### getLockTimeout

    public long getLockTimeout()

  Return the lock timeout setting, in microseconds.

  A value of 0 means no timeout is set.

### setReadOnly

    public void setReadOnly(boolean readOnly)

  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.

### getReadOnly

    public boolean getReadOnly()

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

  This method may be called at any time during the life of the application.

  Returns:
    True if the database environment is configured to be read only.

### setTxnTimeout

    public void setTxnTimeout(long txnTimeout)
                       throws IllegalArgumentException

  Configure the transaction timeout, in microseconds.

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

  Parameters:
    `txnTimeout` - The transaction timeout, in microseconds. A value of 0 turns off transaction timeouts.
  Throws:
    `IllegalArgumentException` - If the value of timeout is negative.
  See Also:
    `Transaction.setTxnTimeout(long)`

### getTxnTimeout

    public long getTxnTimeout()

  Return the transaction timeout, in microseconds.

  A value of 0 means transaction timeouts are not configured.

  Returns:
    The transaction timeout, in microseconds.

### setTxnSerializableIsolation

    public void setTxnSerializableIsolation(boolean serializableIsolation)

  Configure all transactions for this environment to have Serializable (Degree 3) isolation. By setting Serializable isolation, phantoms will be prevented. By default transactions provide Repeatable Read isolation.

  The default is false for the database environment.

### getTxnSerializableIsolation

    public boolean getTxnSerializableIsolation()

  Return if all transactions for this environment has been configured to have Serializable (Degree 3) isolation.

  Returns:
    If the environment has been configured to have repeatable read isolation.

### 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(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)

  Description copied from class: `EnvironmentMutableConfig`
  Return the value for this configuration parameter.

  Overrides:
    `getConfigParam` in class `EnvironmentMutableConfig`
  Parameters:
    `configParamName` - Name of the requested parameter.

### setLocking

    public void setLocking(boolean locking)

  Configure the database environment for no locking.

  This configuration option should be used when locking guarantees such as consistency and isolation are not important. If locking mode is disabled (it is enabled by default), the cleaner is automatically disabled. The user is responsible for invoking the cleaner and ensuring that there are no concurrent operations while the cleaner is running.

  Parameters:
    `locking` - If false, configure the database environment for no locking. The default is true.

### getLocking

    public boolean getLocking()

  Return true if the database environment is configured for locking.

  This method may be called at any time during the life of the application.

  Returns:
    True if the database environment is configured for locking.

### setTransactional

    public void setTransactional(boolean transactional)

  Configure the database environment for 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 for transactions.

### getTransactional

    public boolean getTransactional()

  Return true if the database environment is configured for transactions.

  This method may be called at any time during the life of the application.

  Returns:
    True if the database environment is configured for transactions.

Berkeley DB Java Edition version 3.2.76

Copyright 1996,2008 Oracle. All rights reserved.