com.sleepycat.je

Class EnvironmentConfig

java.lang.Object

com.sleepycat.je.EnvironmentMutableConfig

com.sleepycat.je.EnvironmentConfig

All Implemented Interfaces:

Serializable, 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();
     // will throw if timeout value is invalid
     envConfig.setLockTimeout(250, TimeUnit.MILLISECONDS);
     // Open the environment using this configuration.
     Environment myEnvironment = new Environment(home, envConfig);
 

Additional parameters are described by the parameter name String constants in this class. 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(EnvironmentConfig.NODE_MAX_ENTRIES, "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 along with the parameter name String constants in this class.

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, its 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 described along with the parameter name String constants in this class.

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.

Time Duration Properties

Several environment and transaction configuration properties are time durations. For these properties, a time unit is specified along with an integer duration value.

When specific setter and getter methods exist for a time duration property, these methods have a TimeUnit argument. Examples are setLockTimeout(long,TimeUnit) and getLockTimeout(TimeUnit). Note that the TimeUnit argument may be null only when the duration value is zero; there is no default unit that is used when null is specified.

When a time duration is specified as a string value, the following format is used.

   <value> [ <whitespace> <unit> ]

The <value> is an integer. The <unit> name, if present, must be preceded by one or more spaces or tabs.

The following <unit> names are allowed. Both TimeUnit names and IEEE standard abbreviations are allowed. Unit names are case insensitive.

IEEE abbreviation	TimeUnit name	Definition
ns	NANOSECONDS	one billionth (10-9) of a second
us	MICROSECONDS	one millionth (10-6) of a second
ms	MILLISECONDS	one thousandth (10-3) of a second
s	SECONDS	1 second
min		60 seconds
h		3600 seconds

Examples are:

 3 seconds
 3 s
 500 ms
 1000000 (microseconds is implied)
 

Note that when the <unit> is omitted, microseconds is implied. This default is supported for compatibility with JE 3.3 and earlier. In JE 3.3 and earlier, explicit time units were not used and durations were always implicitly specified in microseconds. The older methods that do not have a TimeUnit argument, such as setLockTimeout(long) and getLockTimeout(), use microsecond durations and have been deprecated.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static String	ADLER32_CHUNK_SIZE By default, JE passes an entire log record to the Adler32 class for checksumming.
static String	CHECKPOINTER_BYTES_INTERVAL Ask the checkpointer to run every time we write this many bytes to the log.
static String	CHECKPOINTER_DEADLOCK_RETRY The number of times to retry a checkpoint if it runs into a deadlock.
static String	CHECKPOINTER_HIGH_PRIORITY If true, the checkpointer uses more resources in order to complete the checkpoint in a shorter time interval.
static String	CHECKPOINTER_WAKEUP_INTERVAL The checkpointer wakeup interval in microseconds.
static String	CLEANER_ADJUST_UTILIZATION If true, the cleaner will attempt to adjust utilization to account for unknown record sizes.
static String	CLEANER_BACKGROUND_PROACTIVE_MIGRATION If true, the cleaner will fetch log entries (incurring the cost of random I/O) during checkpoints and other JE background thread activities, in order to migrate log entries and reduce the cleaner backlog.
static String	CLEANER_BYTES_INTERVAL The cleaner checks disk utilization every time we write this many bytes to the log.
static String	CLEANER_DEADLOCK_RETRY The number of times to retry cleaning if a deadlock occurs.
static String	CLEANER_DETAIL_MAX_MEMORY_PERCENTAGE Tracking of detailed cleaning information will use no more than this percentage of the cache.
static String	CLEANER_EXPUNGE If true, the cleaner deletes log files after successful cleaning.
static String	CLEANER_FETCH_OBSOLETE_SIZE If true, the cleaner will fetch records to determine their size and more accurately calculate log utilization.
static String	CLEANER_FORCE_CLEAN_FILES Specifies a list of files or file ranges to be cleaned at a time when no other log cleaning is necessary.
static String	CLEANER_FOREGROUND_PROACTIVE_MIGRATION If true, the cleaner will fetch log entries (incurring the cost of random I/O) during eviction, Btree splits, and other application foreground thread activities, in order to migrate log entries and reduce the cleaner backlog.
static String	CLEANER_LAZY_MIGRATION Controls whether log cleaner threads perform LN (leaf node or record) migration immediately when processing a log file, or lazily during eviction and checkpointing.
static String	CLEANER_LOCK_TIMEOUT The lock timeout for cleaner transactions in microseconds.
static String	CLEANER_LOOK_AHEAD_CACHE_SIZE The look ahead cache size for cleaning in bytes.
static String	CLEANER_MAX_BATCH_FILES The maximum number of log files in the cleaner's backlog, or zero if there is no limit.
static String	CLEANER_MIN_AGE The minimum age of a file (number of files between it and the active file) to qualify it for cleaning under any conditions.
static String	CLEANER_MIN_FILE_UTILIZATION A log file will be cleaned if its utilization percentage is below this value, irrespective of total utilization.
static String	CLEANER_MIN_UTILIZATION The cleaner will keep the total disk space utilization percentage above this value.
static String	CLEANER_READ_SIZE The read buffer size for cleaning.
static String	CLEANER_THREADS The number of threads allocated by the cleaner for log file processing.
static String	CLEANER_UPGRADE_TO_LOG_VERSION All log files having a log version prior to the specified version will be cleaned at a time when no other log cleaning is necessary.
static String	COMPRESSOR_DEADLOCK_RETRY The number of times to retry a compression run if a deadlock occurs.
static String	COMPRESSOR_LOCK_TIMEOUT The lock timeout for compressor transactions in microseconds.
static String	COMPRESSOR_PURGE_ROOT Deprecated. as of 3.3.87. Compression of the root node no longer has any benefit and this feature has been removed. This parameter has no effect.
static String	COMPRESSOR_WAKEUP_INTERVAL The compressor thread wakeup interval in microseconds.
static String	CONSOLE_LOGGING_LEVEL Trace messages equal and above this level will be logged to the console.
static String	DOS_PRODUCER_QUEUE_TIMEOUT The timeout for Disk Ordered Scan producer thread queue offers in milliseconds.
static String	ENV_BACKGROUND_READ_LIMIT The maximum number of read operations performed by JE background activities (e.g., cleaning) before sleeping to ensure that application threads can perform I/O.
static String	ENV_BACKGROUND_SLEEP_INTERVAL The duration that JE background activities will sleep when the ENV_BACKGROUND_WRITE_LIMIT or ENV_BACKGROUND_WRITE_LIMIT is reached.
static String	ENV_BACKGROUND_WRITE_LIMIT The maximum number of write operations performed by JE background activities (e.g., checkpointing and eviction) before sleeping to ensure that application threads can perform I/O.
static String	ENV_CHECK_LEAKS Debugging support: check leaked locks and txns at env close.
static String	ENV_DB_EVICTION If true, enable eviction of metadata for closed databases.
static String	ENV_DUP_CONVERT_PRELOAD_ALL If true (the default) preload all duplicates databases at once when upgrading from JE 4.1 and earlier.
static String	ENV_FAIR_LATCHES If true, use latches instead of synchronized blocks to implement the lock table and log write mutexes.
static String	ENV_FORCED_YIELD Debugging support: call Thread.yield() at strategic points.
static String	ENV_IS_LOCKING If true, create the environment with record locking.
static String	ENV_IS_TRANSACTIONAL If true, create an environment that is capable of performing transactions.
static String	ENV_READ_ONLY If true, open the environment read-only.
static String	ENV_RECOVERY_FORCE_CHECKPOINT If true, a checkpoint is forced following recovery, even if the log ends with a checkpoint.
static String	ENV_RECOVERY_FORCE_NEW_FILE Used after performing a restore from backup to force creation of a new log file prior to recovery.
static String	ENV_RUN_CHECKPOINTER If true, starts up the checkpointer thread.
static String	ENV_RUN_CLEANER If true, starts up the cleaner thread.
static String	ENV_RUN_EVICTOR If true, eviction is also done by a pool of evictor threads, as well as being done inline by application threads.
static String	ENV_RUN_IN_COMPRESSOR If true, starts up the INCompressor thread.
static String	EVICTOR_ALLOW_BIN_DELTAS Allow Bottom Internal Nodes (BINs) to be written in a delta format during eviction.
static String	EVICTOR_CORE_THREADS The minimum number of threads in the eviction thread pool.
static String	EVICTOR_CRITICAL_PERCENTAGE At this percentage over the allotted cache, critical eviction will start.
static String	EVICTOR_DEADLOCK_RETRY Deprecated. as of JE 4.1, since the single evictor thread has been replaced be a more robust thread pool. The number of times to retry the evictor if it runs into a deadlock. When using the shared cache feature, the value of this property is applied the first time the cache is set up. New environments that join the cache do not alter the cache setting. Name Type Mutable Default Minimum Maximum "je.evictor.deadlockRetry" Integer No 3 0 -none-
static String	EVICTOR_EVICT_BYTES When eviction occurs, the evictor will push memory usage to this number of bytes below MAX_MEMORY.
static String	EVICTOR_FORCED_YIELD Call Thread.yield() at each check for cache overflow.
static String	EVICTOR_KEEP_ALIVE The duration that excess threads in the eviction thread pool will stay idle.
static String	EVICTOR_LRU_ONLY If true (the default), use an LRU-only policy to select nodes for eviction.
static String	EVICTOR_MAX_THREADS The maximum number of threads in the eviction thread pool.
static String	EVICTOR_NODES_PER_SCAN The number of nodes in one evictor scan.
static String	FILE_LOGGING_LEVEL Trace messages equal and above this level will be logged to the je.info file, which is in the Environment home directory.
static String	HALT_ON_COMMIT_AFTER_CHECKSUMEXCEPTION By default, if a checksum exception is found at the end of the log during Environment startup, JE will assume the checksum is due to previously interrupted I/O and will quietly truncate the log and restart.
static String	LOCK_N_LOCK_TABLES Number of Lock Tables.
static String	LOCK_OLD_LOCK_EXCEPTIONS Whether to throw old-style lock exceptions for compatibility with older JE releases.
static String	LOCK_TIMEOUT The LockTimeout property.
static String	LOG_BUFFER_SIZE The maximum starting size of a JE log buffer.
static String	LOG_CHECKSUM_READ If true, perform a checksum check when reading entries from log.
static String	LOG_CHUNKED_NIO Deprecated. NIO is no longer used by JE and this parameter has no effect.
static String	LOG_DIRECT_NIO Deprecated. NIO is no longer used by JE and this parameter has no effect.
static String	LOG_FAULT_READ_SIZE The buffer size for faulting in objects from disk, in bytes.
static String	LOG_FILE_CACHE_SIZE The size of the file handle cache.
static String	LOG_FILE_MAX The maximum size of each individual JE log file, in bytes.
static String	LOG_FSYNC_TIMEOUT The timeout limit for group file sync, in microseconds.
static String	LOG_GROUP_COMMIT_INTERVAL The time interval in nanoseconds during which transactions may be grouped to amortize the cost of write and/or fsync when a transaction commits with SyncPolicy#SYNC or SyncPolicy#WRITE_NO_SYNC on the local machine.
static String	LOG_GROUP_COMMIT_THRESHOLD The threshold value impacts the number of transactions that may be grouped to amortize the cost of write and/or fsync when a transaction commits with SyncPolicy#SYNC or SyncPolicy#WRITE_NO_SYNC on the local machine.
static String	LOG_ITERATOR_MAX_SIZE The maximum read buffer size for log iterators, which are used when scanning the log during activities like log cleaning and environment open, in bytes.
static String	LOG_ITERATOR_READ_SIZE The read buffer size for log iterators, which are used when scanning the log during activities like log cleaning and environment open, in bytes.
static String	LOG_MEM_ONLY If true, operates in an in-memory test mode without flushing the log to disk.
static String	LOG_N_DATA_DIRECTORIES The JE environment can be spread across multiple subdirectories.
static String	LOG_NUM_BUFFERS The number of JE log buffers.
static String	LOG_TOTAL_BUFFER_BYTES The total memory taken by log buffers, in bytes.
static String	LOG_USE_NIO Deprecated. NIO is no longer used by JE and this parameter has no effect.
static String	LOG_USE_ODSYNC If true (default is false) O_DSYNC is used to open JE log files.
static String	LOG_USE_WRITE_QUEUE If true (default is true) the Write Queue is used for file I/O operations which are blocked by concurrent I/O operations.
static String	LOG_VERIFY_CHECKSUMS If true, perform a checksum verification just before and after writing to the log.
static String	LOG_WRITE_QUEUE_SIZE The size of the Write Queue.
static String	MAX_MEMORY The CacheSize property.
static String	MAX_MEMORY_PERCENT The CachePercent property.
static String	NODE_DUP_TREE_MAX_ENTRIES Deprecated. this property no longer has any effect; DatabaseConfig.setNodeMaxEntries(int) should be used instead.
static String	NODE_MAX_ENTRIES The maximum number of entries in an internal btree node.
static String	SHARED_CACHE The SharedCache property.
static String	STARTUP_DUMP_THRESHOLD If environment startup exceeds this duration, startup statistics are logged and can be found in the je.info file.
static String	STATS_COLLECT If true collect and log statistics.
static String	STATS_COLLECT_INTERVAL The duration of the statistics capture interval.
static String	STATS_FILE_DIRECTORY The directory to save the statistics log file.
static String	STATS_FILE_ROW_COUNT Log file maximum row count for Stat collection.
static String	STATS_MAX_FILES Maximum number of statistics log files to retain.
static String	TRACE_CONSOLE Deprecated. in favor of CONSOLE_LOGGING_LEVEL As of JE 4.0, use the standard java.util.logging configuration methodologies. To enable console output, set com.sleepycat.je.util.ConsoleHandler.level = <LEVEL> through the java.util.logging configuration file, or through the java.util.logging.LogManager. To set the handler level programmatically, set "com.sleepycat.je.util.ConsoleHandler.level" in the EnvironmentConfig object.
static String	TRACE_DB Deprecated. As of JE 4.0, event tracing to the .jdb files has been separated from the java.util.logging mechanism. This parameter has no effect.
static String	TRACE_FILE Deprecated. in favor of FILE_LOGGING_LEVEL As of JE 4.0, use the standard java.util.logging configuration methodologies. To enable logging output to the je.info files, set com.sleepycat.je.util.FileHandler.level = <LEVEL> through the java.util.logging configuration file, or through the java.util.logging.LogManager. To set the handler level programmatically, set "com.sleepycat.je.util.FileHandler.level" in the EnvironmentConfig object.
static String	TRACE_FILE_COUNT Deprecated. As of JE 4.0, use the standard java.util.logging configuration methodologies. To set the FileHandler output file count, set com.sleepycat.je.util.FileHandler.count = <NUMBER> through the java.util.logging configuration file, or through the java.util.logging.LogManager.
static String	TRACE_FILE_LIMIT Deprecated. As of JE 4.0, use the standard java.util.logging configuration methodologies. To set the FileHandler output file size, set com.sleepycat.je.util.FileHandler.limit = <NUMBER> through the java.util.logging configuration file, or through the java.util.logging.LogManager.
static String	TRACE_LEVEL Deprecated. As of JE 4.0, use the standard java.util.logging configuration methodologies. Set logging levels using class names through the java.util.logging configuration file, or through the java.util.logging.LogManager.
static String	TRACE_LEVEL_CLEANER Deprecated. As of JE 4.0, use the standard java.util.logging configuration methodologies. To see cleaner logging, set com.sleepycat.je.cleaner.level = <LEVEL> through the java.util.logging configuration file, or through the java.util.logging.LogManager.
static String	TRACE_LEVEL_EVICTOR Deprecated. As of JE 4.0, use the standard java.util.logging configuration methodologies. To see evictor logging, set com.sleepycat.je.evictor.level = <LEVEL> through the java.util.logging configuration file, or through the java.util.logging.LogManager.
static String	TRACE_LEVEL_LOCK_MANAGER Deprecated. As of JE 4.0, use the standard java.util.logging configuration methodologies. To see locking logging, set com.sleepycat.je.txn.level = <LEVEL> through the java.util.logging configuration file, or through the java.util.logging.LogManager.
static String	TRACE_LEVEL_RECOVERY Deprecated. As of JE 4.0, use the standard java.util.logging configuration methodologies. To see recovery logging, set com.sleepycat.je.recovery.level = <LEVEL> through the java.util.logging configuration file, or through the java.util.logging.LogManager.
static String	TREE_BIN_DELTA If more than this percentage of entries are changed on a BIN, log a a full version instead of a delta.
static String	TREE_COMPACT_MAX_KEY_LENGTH Specifies the maximum unprefixed key length for use in the compact in-memory key representation.
static String	TREE_MAX_DELTA After this many deltas, log a full version.
static String	TREE_MIN_MEMORY The minimum bytes allocated out of the memory cache to hold Btree data including internal nodes and record keys and data.
static String	TXN_DEADLOCK_STACK_TRACE Set this parameter to true to add stacktrace information to deadlock (lock timeout) exception messages.
static String	TXN_DUMP_LOCKS Dump the lock table when a lock timeout is encountered, for debugging assistance.
static String	TXN_SERIALIZABLE_ISOLATION The TxnSerializableIsolation property.
static String	TXN_TIMEOUT The TxnTimeout property.

Constructor Summary

Constructors

Constructor and Description
EnvironmentConfig() Creates an EnvironmentConfig initialized with the system default settings.
EnvironmentConfig(Properties properties) Creates an EnvironmentConfig which includes the properties specified in the properties parameter.

Method Summary

Methods

Modifier and Type	Method and Description
EnvironmentConfig	clone() Returns a copy of this configuration object.
boolean	getAllowCreate() Returns a flag that specifies if we may create this environment.
ClassLoader	getClassLoader() Returns the ClassLoader for loading user-supplied classes by name, or null if no specified ClassLoader is configured.
CustomStats	getCustomStats() Gets the custom statstics object.
boolean	getLocking() Returns true if the database environment is configured for locking.
long	getLockTimeout() Deprecated. as of 4.0, replaced by getLockTimeout(TimeUnit).
long	getLockTimeout(TimeUnit unit) Returns the lock timeout setting.
Handler	getLoggingHandler() Returns the custom java.util.logging.Handler specified by the application.
String	getNodeName() Returns the user defined nodeName for the Environment.
boolean	getReadOnly() Returns true if the database environment is configured to be read only.
ProgressListener<RecoveryProgress>	getRecoveryProgressListener() Return the ProgressListener to be used at this environment startup.
boolean	getSharedCache() Returns true if the shared cache is used by this environment.
boolean	getTransactional() Returns true if the database environment is configured for transactions.
boolean	getTxnSerializableIsolation() Returns true if all transactions for this environment has been configured to have Serializable (Degree 3) isolation.
long	getTxnTimeout() Deprecated. as of 4.0, replaced by getTxnTimeout(TimeUnit).
long	getTxnTimeout(TimeUnit unit) Returns the transaction timeout.
EnvironmentConfig	setAllowCreate(boolean allowCreate) If true, creates the database environment if it doesn't already exist.
EnvironmentConfig	setClassLoader(ClassLoader classLoader) Configure the environment to use a specified ClassLoader for loading user-supplied classes by name.
EnvironmentConfig	setConfigParam(String paramName, String value) Set this configuration parameter.
EnvironmentConfig	setCustomStats(CustomStats customStats) Sets the custom statistics object.
EnvironmentConfig	setLocking(boolean locking) Configures the database environment for no locking.
EnvironmentConfig	setLockTimeout(long timeout) Deprecated. as of 4.0, replaced by setLockTimeout(long, TimeUnit).
EnvironmentConfig	setLockTimeout(long timeout, TimeUnit unit) Configures the lock timeout.
EnvironmentConfig	setLoggingHandler(Handler handler) Set a java.util.logging.Handler which will be used by all java.util.logging.Loggers instantiated by this Environment.
EnvironmentConfig	setNodeName(String nodeName) Sets the user defined nodeName for the Environment.
EnvironmentConfig	setReadOnly(boolean readOnly) Configures the database environment to be read-only, and any attempt to modify a database will fail.
EnvironmentConfig	setRecoveryProgressListener(ProgressListener<RecoveryProgress> progressListener) Configure the environment to make periodic calls to a ProgressListener to provide feedback on environment startup (recovery).
EnvironmentConfig	setSharedCache(boolean sharedCache) If true, the shared cache is used by this environment.
EnvironmentConfig	setTransactional(boolean transactional) Configures the database environment for transactions.
EnvironmentConfig	setTxnSerializableIsolation(boolean txnSerializableIsolation) Configures all transactions for this environment to have Serializable (Degree 3) isolation.
EnvironmentConfig	setTxnTimeout(long timeout) Deprecated. as of 4.0, replaced by setTxnTimeout(long, TimeUnit).
EnvironmentConfig	setTxnTimeout(long timeout, TimeUnit unit) Configures the transaction timeout.
String	toString() Display configuration values.

Methods inherited from class com.sleepycat.je.EnvironmentMutableConfig

getCacheMode, getCachePercent, getCacheSize, getConfigParam, getDurability, getExceptionListener, getTxnNoSync, getTxnWriteNoSync, setCacheMode, setCachePercent, setCacheSize, setDurability, setExceptionListener, setTxnNoSync, setTxnWriteNoSync

Methods inherited from class java.lang.Object

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

Field Detail

MAX_MEMORY

public static final String MAX_MEMORY

The CacheSize property.

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.

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

Name	Type	Mutable	Default	Minimum	Maximum
"je.maxMemory"	Long	Yes	0	-none-	-none-

See Also:

EnvironmentMutableConfig.setCacheSize(long), Constant Field Values

MAX_MEMORY_PERCENT

public static final String MAX_MEMORY_PERCENT

The CachePercent property.

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.

Name	Type	Mutable	Default	Minimum	Maximum
"je.maxMemoryPercent"	Integer	Yes	60	1	90

See Also:

EnvironmentMutableConfig.setCachePercent(int), Constant Field Values

SHARED_CACHE

public static final String SHARED_CACHE

The SharedCache property.

Name	Type	Mutable	Default
"je.sharedCache"	Boolean	No	false

See Also:

Constant Field Values

ENV_RECOVERY_FORCE_CHECKPOINT

public static final String ENV_RECOVERY_FORCE_CHECKPOINT

If true, a checkpoint is forced following recovery, even if the log ends with a checkpoint.

Name	Type	Mutable	Default
"je.env.recoveryForceCheckpoint"	Boolean	No	false

See Also:

Constant Field Values

ENV_RECOVERY_FORCE_NEW_FILE

public static final String ENV_RECOVERY_FORCE_NEW_FILE

Used after performing a restore from backup to force creation of a new log file prior to recovery.

When this parameter is set to true, the last .jdb file restored will not be modified when opening the Environment, and the next .jdb file will be created and will become the end-of-log file. The intention is to make the last file restored immutable, so that the backup set remains valid and can be used as a basis for future incremental backups.

WARNING: If this property is not set to true when opening the environment for the first time after a restore, then the backup set that was restored may not be used as the basis for future incremental backups. If a future incremental backup were performed based on this backup set, it would be incomplete and data would be lost if that incremental backup were restored.

Name	Type	Mutable	Default
"je.env.recoveryForceNewFile"	Boolean	No	false

See Also:

Restoring from a backup, Constant Field Values

HALT_ON_COMMIT_AFTER_CHECKSUMEXCEPTION

public static final String HALT_ON_COMMIT_AFTER_CHECKSUMEXCEPTION

By default, if a checksum exception is found at the end of the log during Environment startup, JE will assume the checksum is due to previously interrupted I/O and will quietly truncate the log and restart. If this property is set to true, when a ChecksumException occurs in the last log file during recovery, instead of truncating the log file, and automatically restarting, attempt to continue reading past the corrupted record with the checksum error to see if there are commit records following the corruption. If there are, throw an EnvironmentFailureException to indicate the presence of committed transactions. The user may then need to run DbTruncateLog to truncate the log for further recovery after doing manual analysis of the log. Setting this property is suitable when the application wants to guard against unusual cases.

Name	Type	Mutable	Default
"je.haltOnCommitAfterChecksumException"	Boolean	No	false

See Also:

Constant Field Values

ENV_RUN_IN_COMPRESSOR

public static final String ENV_RUN_IN_COMPRESSOR

If true, starts up the INCompressor thread.

Name	Type	Mutable	Default
"je.env.runINCompressor"	Boolean	Yes	true

See Also:

Constant Field Values

ENV_RUN_CHECKPOINTER

public static final String ENV_RUN_CHECKPOINTER

If true, starts up the checkpointer thread.

Name	Type	Mutable	Default
"je.env.runCheckpointer"	Boolean	Yes	true

See Also:

Constant Field Values

ENV_RUN_CLEANER

public static final String ENV_RUN_CLEANER

If true, starts up the cleaner thread.

Name	Type	Mutable	Default
"je.env.runCleaner"	Boolean	Yes	true

See Also:

Constant Field Values

ENV_RUN_EVICTOR

public static final String ENV_RUN_EVICTOR

If true, eviction is also done by a pool of evictor threads, as well as being done inline by application threads. If false, the evictor pool is not used, regardless of the values of je.evictor.coreThreads and je.evictor.maxThreads.

Name	Type	Mutable	Default
"je.env.runEvictor"	Boolean	Yes	true

See Also:

Constant Field Values

ENV_BACKGROUND_READ_LIMIT

public static final String ENV_BACKGROUND_READ_LIMIT

The maximum number of read operations performed by JE background activities (e.g., cleaning) before sleeping to ensure that application threads can perform I/O. If zero (the default) then no limitation on I/O is enforced.

Name	Type	Mutable	Default	Minimum	Maximum
"je.env.backgroundReadLimit"	Integer	Yes	0	0	-none-

See Also:

ENV_BACKGROUND_SLEEP_INTERVAL, Constant Field Values

ENV_BACKGROUND_WRITE_LIMIT

public static final String ENV_BACKGROUND_WRITE_LIMIT

The maximum number of write operations performed by JE background activities (e.g., checkpointing and eviction) before sleeping to ensure that application threads can perform I/O. If zero (the default) then no limitation on I/O is enforced.

Name	Type	Mutable	Default	Minimum	Maximum
"je.env.backgroundWriteLimit"	Integer	Yes	0	0	-none-

See Also:

ENV_BACKGROUND_SLEEP_INTERVAL, Constant Field Values

ENV_BACKGROUND_SLEEP_INTERVAL

public static final String ENV_BACKGROUND_SLEEP_INTERVAL

The duration that JE background activities will sleep when the ENV_BACKGROUND_WRITE_LIMIT or ENV_BACKGROUND_WRITE_LIMIT is reached. If ENV_BACKGROUND_WRITE_LIMIT and ENV_BACKGROUND_WRITE_LIMIT are zero, this setting is not used.

Name	Type	Mutable	Default	Minimum	Maximum
"je.env.backgroundSleepInterval"	Duration	Yes	1 ms	1 ms	24 d

See Also:

Time Duration Properties, Constant Field Values

ENV_CHECK_LEAKS

public static final String ENV_CHECK_LEAKS

Debugging support: check leaked locks and txns at env close.

Name	Type	Mutable	Default
"je.env.checkLeaks"	Boolean	No	true

See Also:

Constant Field Values

ENV_FORCED_YIELD

public static final String ENV_FORCED_YIELD

Debugging support: call Thread.yield() at strategic points.

Name	Type	Mutable	Default
"je.env.forcedYield"	Boolean	No	false

See Also:

Constant Field Values

ENV_IS_TRANSACTIONAL

public static final String ENV_IS_TRANSACTIONAL

If true, create an environment that is capable of performing transactions. If true is not passed, transactions may not be used. For licensing purposes, the use of this method distinguishes the use of the Transactional product. Note that if transactions are not used, specifying true does not create additional overhead in the environment.

Name	Type	Mutable	Default
"je.env.isTransactional"	Boolean	No	false

See Also:

Constant Field Values

ENV_IS_LOCKING

public static final String ENV_IS_LOCKING

If true, create the environment with record locking. This property should be set to false only in special circumstances when it is safe to run without record locking.

Name	Type	Mutable	Default
"je.env.isLocking"	Boolean	No	true

See Also:

Constant Field Values

ENV_READ_ONLY

public static final String ENV_READ_ONLY

If true, open the environment read-only.

Name	Type	Mutable	Default
"je.env.isReadOnly"	Boolean	No	false

See Also:

Constant Field Values

ENV_FAIR_LATCHES

public static final String ENV_FAIR_LATCHES

If true, use latches instead of synchronized blocks to implement the lock table and log write mutexes. Latches require that threads queue to obtain the mutex in question and therefore guarantee that there will be no mutex starvation, but do incur a performance penalty. Latches should not be necessary in most cases, so synchronized blocks are the default. An application that puts heavy load on JE with threads with different thread priorities might find it useful to use latches. In a Java 5 JVM, where java.util.concurrent.locks.ReentrantLock is used for the latch implementation, this parameter will determine whether they are 'fair' or not. This parameter is 'static' across all environments.

Name	Type	Mutable	Default
"je.env.fairLatches"	Boolean	No	false

See Also:

Constant Field Values

ENV_DB_EVICTION

public static final String ENV_DB_EVICTION

If true, enable eviction of metadata for closed databases.

Name	Type	Mutable	Default
"je.env.dbEviction"	Boolean	No	true

See Also:

Constant Field Values

ENV_DUP_CONVERT_PRELOAD_ALL

public static final String ENV_DUP_CONVERT_PRELOAD_ALL

If true (the default) preload all duplicates databases at once when upgrading from JE 4.1 and earlier. If false, preload each duplicates database individually instead. Preloading all databases at once gives a performance advantage if the JE cache is roughly large enough to contain the internal nodes for all duplicates databases. Preloading each database individually gives a performance advantage if the JE cache is roughly large enough to contain the internal nodes for a single duplicates database.

Name	Type	Mutable	Default
"je.env.dupConvertPreloadAll"	Boolean	No	true

See Also:

Constant Field Values

ADLER32_CHUNK_SIZE

public static final String ADLER32_CHUNK_SIZE

By default, JE passes an entire log record to the Adler32 class for checksumming. This can cause problems with the GC in some cases if the records are large and there is concurrency. Setting this parameter will cause JE to pass chunks of the log record to the checksumming class so that the GC does not block. 0 means do not chunk.

Name	Type	Mutable	Default	Minimum	Maximum
"je.adler32.chunkSize"	Integer	Yes	0	0	1048576 (1M)

See Also:

Constant Field Values

LOG_TOTAL_BUFFER_BYTES

public static final String LOG_TOTAL_BUFFER_BYTES

The total memory taken by log buffers, in bytes. If 0, use 7% of je.maxMemory. If 0 and je.sharedCache=true, use 7% divided by N where N is the number of environments sharing the global cache.

Name	Type	Mutable	Default	Minimum	Maximum
"je.log.totalBufferBytes"	Long	No	0	6144L	-none-

See Also:

Constant Field Values

LOG_NUM_BUFFERS

public static final String LOG_NUM_BUFFERS

The number of JE log buffers.

Name	Type	Mutable	Default	Minimum	Maximum
"je.log.numBuffers"	Integer	No	3	2	-none-

See Also:

Constant Field Values

LOG_BUFFER_SIZE

public static final String LOG_BUFFER_SIZE

The maximum starting size of a JE log buffer. JE silently restricts this value to be no more than the configured maximum log file size (je.log.fileMax).

Name	Type	Mutable	Default	Minimum	Maximum
"je.log.bufferSize"	Integer	No	1048576 (1M)	1024 (1K)	-none-

See Also:

Constant Field Values

LOG_FAULT_READ_SIZE

public static final String LOG_FAULT_READ_SIZE

The buffer size for faulting in objects from disk, in bytes.

Name	Type	Mutable	Default	Minimum	Maximum
"je.log.faultReadSize"	Integer	No	2048 (2K)	32	-none-

See Also:

Constant Field Values

LOG_ITERATOR_READ_SIZE

public static final String LOG_ITERATOR_READ_SIZE

The read buffer size for log iterators, which are used when scanning the log during activities like log cleaning and environment open, in bytes. This may grow as the system encounters larger log entries.

Name	Type	Mutable	Default	Minimum	Maximum
"je.log.iteratorReadSize"	Integer	No	8192 (8K)	128	-none-

See Also:

Constant Field Values

LOG_ITERATOR_MAX_SIZE

public static final String LOG_ITERATOR_MAX_SIZE

The maximum read buffer size for log iterators, which are used when scanning the log during activities like log cleaning and environment open, in bytes.

Name	Type	Mutable	Default	Minimum	Maximum
"je.log.iteratorMaxSize"	Integer	No	16777216 (16M)	128	-none-

See Also:

Constant Field Values

LOG_FILE_MAX

public static final String LOG_FILE_MAX

The maximum size of each individual JE log file, in bytes.

Name	Type	Mutable	Default	Minimum	Maximum	JVM
"je.log.fileMax"	Long	No	10000000 (10M)	1000000 (1M)	1073741824 (1G)	Conventional JVM
"je.log.fileMax"	Long	No	100000 (100K)	10000 (10K)	1048576 (1M)	Dalvik JVM

See Also:

Constant Field Values

LOG_N_DATA_DIRECTORIES

public static final String LOG_N_DATA_DIRECTORIES

The JE environment can be spread across multiple subdirectories. Environment subdirectories may be used to spread an environment's .jdb files over multiple directories, and therefore over multiple disks or file systems. Environment subdirectories reside in the environment home directory and are named data001/ through dataNNN/, consecutively, where NNN is the value of je.log.nDataDirectories. A typical configuration would be to have each of the dataNNN/ names be symbolic links to actual directories which each reside on separate file systems or disks.

If 0, all log files (*.jdb) will reside in the environment home directory passed to the Environment constructor. A non-zero value indicates the number of environment subdirectories to use for holding the environment log files.

If data subdirectories are used (i.e. je.log.nDataDirectories > 0), this parameter must be set when the environment is initially created. Like the environment home directory, each and every one of the dataNNN/ subdirectories must also be present and writable. This parameter must be set to the same value for all subsequent openings of the environment or an exception will be thrown.

If the set of existing dataNNN/ subdirectories is not equivalent to the set { 1 ... je.log.nDataDirectories } when the environment is opened, an EnvironmentFailureException will be thrown, and the Environment will fail to be opened.

This parameter should be set using the je.properties file rather than the EnvironmentConfig. If not, JE command line utilities that open the Environment will throw an exception because they will not know of the non-zero value of this parameter.

Name	Type	Mutable	Default	Minimum	Maximum	JVM
"je.log.nDataDirectories"	Integer	No	0	0	256

See Also:

Constant Field Values

LOG_CHECKSUM_READ

public static final String LOG_CHECKSUM_READ

If true, perform a checksum check when reading entries from log.

Name	Type	Mutable	Default
"je.log.checksumRead"	Boolean	No	true

See Also:

Constant Field Values

LOG_VERIFY_CHECKSUMS

public static final String LOG_VERIFY_CHECKSUMS

If true, perform a checksum verification just before and after writing to the log. This is primarily used for debugging.

Name	Type	Mutable	Default
"je.log.verifyChecksums"	Boolean	No	false

See Also:

Constant Field Values

LOG_MEM_ONLY

public static final String LOG_MEM_ONLY

If true, operates in an in-memory test mode without flushing the log to disk. An environment directory must be specified, but it need not exist and no files are written. The system operates until it runs out of memory, at which time an OutOfMemoryError is thrown. Because the entire log is kept in memory, this mode is normally useful only for testing.

Name	Type	Mutable	Default
"je.log.memOnly"	Boolean	No	false

See Also:

Constant Field Values

LOG_FILE_CACHE_SIZE

public static final String LOG_FILE_CACHE_SIZE

The size of the file handle cache.

Name	Type	Mutable	Default	Minimum	Maximum
"je.log.fileCacheSize"	Integer	No	100	3	-none-

See Also:

Constant Field Values

LOG_FSYNC_TIMEOUT

public static final String LOG_FSYNC_TIMEOUT

The timeout limit for group file sync, in microseconds.

Name	Type	Mutable	Default	Minimum	Maximum
"je.log.fsyncTimeout"	Duration	No	500 ms	10 ms	24 d

See Also:

Time Duration Properties, Constant Field Values

LOG_GROUP_COMMIT_INTERVAL

public static final String LOG_GROUP_COMMIT_INTERVAL

The time interval in nanoseconds during which transactions may be grouped to amortize the cost of write and/or fsync when a transaction commits with SyncPolicy#SYNC or SyncPolicy#WRITE_NO_SYNC on the local machine.

Name	Type	Mutable	Default	Minimum	Maximum
"je.log.groupCommitInterval"	Duration	No	0	0	none

Since:

5.0.76

See Also:

Time Duration Properties, LOG_GROUP_COMMIT_THRESHOLD, Constant Field Values

LOG_GROUP_COMMIT_THRESHOLD

public static final String LOG_GROUP_COMMIT_THRESHOLD

The threshold value impacts the number of transactions that may be grouped to amortize the cost of write and/or fsync when a transaction commits with SyncPolicy#SYNC or SyncPolicy#WRITE_NO_SYNC on the local machine.

Specifying larger values can result in more transactions being grouped together decreasing average commit times.

Name	Type	Mutable	Default	Minimum	Maximum
"je.log.groupCommitThreshold"	Integer	No	0	0	-none-

Since:

5.0.76

See Also:

LOG_GROUP_COMMIT_INTERVAL, Constant Field Values

LOG_USE_ODSYNC

public static final String LOG_USE_ODSYNC

If true (default is false) O_DSYNC is used to open JE log files.

Name	Type	Mutable	Default
"je.log.useODSYNC"	Boolean	No	false

See Also:

Constant Field Values

LOG_USE_NIO

public static final String LOG_USE_NIO

Deprecated. NIO is no longer used by JE and this parameter has no effect.

If true (default is false) NIO is used for all file I/O.

Name	Type	Mutable	Default
"je.log.useNIO"	Boolean	No	false

See Also:

Constant Field Values

LOG_USE_WRITE_QUEUE

public static final String LOG_USE_WRITE_QUEUE

If true (default is true) the Write Queue is used for file I/O operations which are blocked by concurrent I/O operations.

Name	Type	Mutable	Default
"je.log.useWriteQueue"	Boolean	No	true

See Also:

Constant Field Values

LOG_WRITE_QUEUE_SIZE

public static final String LOG_WRITE_QUEUE_SIZE

The size of the Write Queue.

Name	Type	Mutable	Default	Minimum	Maximum
"je.log.writeQueueSize"	Integer	No	1MB	4KB	32MB-

See Also:

Constant Field Values

LOG_DIRECT_NIO

public static final String LOG_DIRECT_NIO

Deprecated. NIO is no longer used by JE and this parameter has no effect.

If true (default is false) direct NIO buffers are used. This setting is only used if LOG_USE_NIO is true.

Name	Type	Mutable	Default
"je.log.directNIO"	Boolean	No	false

See Also:

Constant Field Values

LOG_CHUNKED_NIO

public static final String LOG_CHUNKED_NIO

Deprecated. NIO is no longer used by JE and this parameter has no effect.

If non-0 (default is 0) break all IO into chunks of this size. This setting is only used if LOG_USE_NIO is true.

Name	Type	Mutable	Default	Minimum	Maximum
"je.log.chunkedNIO"	Long	No	0	0	67108864 (64M)

See Also:

Constant Field Values

NODE_MAX_ENTRIES

public static final String NODE_MAX_ENTRIES

The maximum number of entries in an internal btree node. This can be set per-database using the DatabaseConfig object.

Name	Type	Mutable	Default	Minimum	Maximum
"je.nodeMaxEntries"	Integer	No	128	4	32767 (32K)

See Also:

Constant Field Values

NODE_DUP_TREE_MAX_ENTRIES

public static final String NODE_DUP_TREE_MAX_ENTRIES

Deprecated. this property no longer has any effect; DatabaseConfig.setNodeMaxEntries(int) should be used instead.

See Also:

Constant Field Values

TREE_MAX_DELTA

public static final String TREE_MAX_DELTA

After this many deltas, log a full version.

Both the TREE_MAX_DELTA and TREE_BIN_DELTA conditions for logging a delta must be met; otherwise a full version will be logged. For example, using the default parameter settings, a delta will be logged only if less than 10 deltas have previously been logged (since the last full version) and no more than 25% of the BIN entries have changed.

Name	Type	Mutable	Default	Minimum	Maximum
"je.tree.maxDelta"	Integer	No	10	0	100

See Also:

Constant Field Values

TREE_BIN_DELTA

public static final String TREE_BIN_DELTA

If more than this percentage of entries are changed on a BIN, log a a full version instead of a delta.

Both the TREE_MAX_DELTA and TREE_BIN_DELTA conditions for logging a delta must be met; otherwise a full version will be logged. For example, using the default parameter settings, a delta will be logged only if less than 10 deltas have previously been logged (since the last full version) and no more than 25% of the BIN entries have changed.

Name	Type	Mutable	Default	Minimum	Maximum
"je.tree.binDelta"	Integer	No	25	0	75

See Also:

Constant Field Values

TREE_MIN_MEMORY

public static final String TREE_MIN_MEMORY

The minimum bytes allocated out of the memory cache to hold Btree data including internal nodes and record keys and data. If the specified value is larger than the size initially available in the cache, it will be truncated to the amount available.

TREE_MIN_MEMORY is the minimum for a single environment. By default, 500 KB or the size initially available in the cache is used, whichever is smaller.

Name	Type	Mutable	Default	Minimum	Maximum
"je.tree.minMemory"	Long	Yes	512000 (500K)	51200 (50K)	-none-

See Also:

Constant Field Values

TREE_COMPACT_MAX_KEY_LENGTH

public static final String TREE_COMPACT_MAX_KEY_LENGTH

Specifies the maximum unprefixed key length for use in the compact in-memory key representation.

In the Btree, the JE in-memory cache, the default representation for keys uses a byte array object per key. The per-key object overhead of this approach ranges from 20 to 32 bytes, depending on the JVM platform.

To reduce memory overhead, a compact representation can instead be used where keys will be represented inside a single byte array instead of having one byte array per key. Within the single array, all keys are assigned a storage size equal to that taken up by the largest key, plus one byte to hold the actual key length. The use of the fixed size array reduces Java GC activity as well as memory overhead.

In order for the compact representation to reduce memory usage, all keys in a database, or in a Btree internal node, must be roughly the same size. The more fully populated the internal node, the more the savings with this representation since the single byte array is sized to hold the maximum number of keys in the internal node, regardless of the actual number of keys that are present.

It's worth noting that the storage savings of the compact representation are realized in addition to the storage benefits of key prefixing (if it is configured), since the keys stored in the key array are the smaller key values after the prefix has been stripped, reducing the length of the key and making it more likely that it's small enough for this specialized representation. This configuration parameter (TREE_COMPACT_MAX_KEY_LENGTH) is the maximum key length, not including the common prefix, for the keys in a Btree internal node stored using the compact representation. See DatabaseConfig.setKeyPrefixing(boolean).

The compact representation is used automatically when both of the following conditions hold.

• All keys in a Btree internal node must have an unprefixed length that is less than or equal to the length specified by this parameter (TREE_COMPACT_MAX_KEY_LENGTH).
• If key lengths vary by large amounts within an internal node, the wasted space of the fixed length storage may negate the benefits of the compact representation and cause more memory to be used than with the default representation. In that case, the default representation will be used.

If this configuration parameter is set to zero, the compact representation will not be used.

The default value of this configuration parameter is 16 bytes. The potential drawbacks of specifying a larger length are:

• Insertion and deletion for larger keys move bytes proportional to the storage length of the keys.
• With the compact representation, all operations create temporary byte arrays for each key involved in the operation. Larger byte arrays mean more work for the Java GC, even though these objects are short lived.

Mutation of the key representation between the default and compact approaches is automatic on a per-Btree internal node basis. For example, if a key that exceeds the configured length is added to a node that uses the compact representation, the node is automatically mutated to the default representation. A best effort is made to prevent frequent mutations that could increase Java GC activity.

To determine how often the compact representation is used in a running application, see EnvironmentStats.getNINCompactKeyIN().

Name	Type	Mutable	Default	Minimum	Maximum
"je.tree.compactMaxKeyLength"	Integer	No	16	0	256

Since:

5.0

See Also:

DatabaseConfig.setKeyPrefixing(boolean), EnvironmentStats.getNINCompactKeyIN(), Constant Field Values

COMPRESSOR_WAKEUP_INTERVAL

public static final String COMPRESSOR_WAKEUP_INTERVAL

The compressor thread wakeup interval in microseconds.

Name	Type	Mutable	Default	Minimum	Maximum
"je.compressor.wakeupInterval"	Duration	No	5 s	1 s	75 min

See Also:

Time Duration Properties, Constant Field Values

COMPRESSOR_DEADLOCK_RETRY

public static final String COMPRESSOR_DEADLOCK_RETRY

The number of times to retry a compression run if a deadlock occurs.

Name	Type	Mutable	Default	Minimum	Maximum
"je.compressor.deadlockRetry"	Integer	No	3	0	-none-

See Also:

Constant Field Values

COMPRESSOR_LOCK_TIMEOUT

public static final String COMPRESSOR_LOCK_TIMEOUT

The lock timeout for compressor transactions in microseconds.

Name	Type	Mutable	Default	Minimum	Maximum
"je.compressor.lockTimeout"	Duration	No	500 ms	0	75 min

See Also:

Time Duration Properties, Constant Field Values

COMPRESSOR_PURGE_ROOT

public static final String COMPRESSOR_PURGE_ROOT

Deprecated. as of 3.3.87. Compression of the root node no longer has any benefit and this feature has been removed. This parameter has no effect.

If true, when the compressor encounters an empty database, the root node of the Btree is deleted.

Name	Type	Mutable	Default
"je.compressor.purgeRoot"	Boolean	No	false

See Also:

Constant Field Values

EVICTOR_EVICT_BYTES

public static final String EVICTOR_EVICT_BYTES

When eviction occurs, the evictor will push memory usage to this number of bytes below MAX_MEMORY. No more than 50% of je.maxMemory will be evicted per eviction cycle, regardless of this setting.

When using the shared cache feature, the value of this property is applied the first time the cache is set up. New environments that join the cache do not alter the cache setting.

Name	Type	Mutable	Default	Minimum	Maximum
"je.evictor.evictBytes"	Long	No	524288 (512K)	1024 (1K)	-none-

See Also:

Constant Field Values

EVICTOR_NODES_PER_SCAN

public static final String EVICTOR_NODES_PER_SCAN

The number of nodes in one evictor scan.

When using the shared cache feature, the value of this property is applied the first time the cache is set up. New environments that join the cache do not alter the cache setting.

Name	Type	Mutable	Default	Minimum	Maximum
"je.evictor.nodesPerScan"	Integer	No	10	1	1000

See Also:

Constant Field Values

EVICTOR_CRITICAL_PERCENTAGE

public static final String EVICTOR_CRITICAL_PERCENTAGE

At this percentage over the allotted cache, critical eviction will start. For example, if this parameter is 5, then when the cache size is 5% over its maximum or 105% full, critical eviction will start.

Critical eviction is eviction performed in application threads as part of normal database access operations. Background eviction, on the other hand, is performed in JE evictor threads as well as during log cleaning and checkpointing. Background eviction is unconditionally started when the cache size exceeds its maximum. When critical eviction is also performed (concurrently with background eviction), it helps to ensure that the cache size does not continue to grow, but can have a negative impact on operation latency.

By default this parameter is zero, which means that critical eviction will start as soon as the cache size exceeds its maximum. Some applications may wish to set this parameter to a non-zero value to improve operation latency, when eviction is a significant performance factor and latency requirements are not being satisfied.

When setting this parameter to a non-zero value, for example 5, be sure to reserve enough heap memory for the cache size to be over its configured maximum, for example 105% full.

Name	Type	Mutable	Default	Minimum	Maximum
"je.evictor.criticalPercentage"	Integer	No	0	0	1000

See Also:

Constant Field Values

EVICTOR_DEADLOCK_RETRY

public static final String EVICTOR_DEADLOCK_RETRY

Deprecated. as of JE 4.1, since the single evictor thread has been replaced be a more robust thread pool. The number of times to retry the evictor if it runs into a deadlock.

When using the shared cache feature, the value of this property is applied the first time the cache is set up. New environments that join the cache do not alter the cache setting.

Name	Type	Mutable	Default	Minimum	Maximum
"je.evictor.deadlockRetry"	Integer	No	3	0	-none-

See Also:

Constant Field Values

EVICTOR_LRU_ONLY

public static final String EVICTOR_LRU_ONLY

If true (the default), use an LRU-only policy to select nodes for eviction. If false, select by Btree level first, and then by LRU.

When using the shared cache feature, the value of this property is applied the first time the cache is set up. New environments that join the cache do not alter the cache setting.

Name	Type	Mutable	Default
"je.evictor.lruOnly"	Boolean	No	true

See Also:

Constant Field Values

EVICTOR_FORCED_YIELD

public static final String EVICTOR_FORCED_YIELD

Call Thread.yield() at each check for cache overflow. This improves GC performance on some systems.

When using the shared cache feature, the value of this property is applied the first time the cache is set up. New environments that join the cache do not alter the cache setting.

Name	Type	Mutable	Default
"je.evictor.forcedYield"	Boolean	No	false

See Also:

Constant Field Values

EVICTOR_CORE_THREADS

public static final String EVICTOR_CORE_THREADS

The minimum number of threads in the eviction thread pool. These threads help keep memory usage within cache bounds, offloading work from application threads. je.evictor.coreThreads, je.evictor.maxThreads and je.evictor.keepAlive are used to configure the core, max and keepalive attributes for the ThreadPoolExecutor which implements the eviction thread pool.

Name	Type	Mutable	Default	Minimum	Maximum
"je.evictor.coreThreads"	Integer	yes	1	0	Integer.MAX_VALUE

See Also:

Constant Field Values

EVICTOR_MAX_THREADS

public static final String EVICTOR_MAX_THREADS

The maximum number of threads in the eviction thread pool. These threads help keep memory usage within cache bound, offloading work from application threads. If the eviction thread pool receives more work, it will allocate up to this number of threads. These threads will terminate if they are idle for more than the time indicated by je.evictor.keepAlive je.evictor.coreThreads, je.evictor.maxThreads and je.evictor.keepAlive are used to configure the core, max and keepalive attributes for the ThreadPoolExecutor which implements the eviction thread pool.

Name	Type	Mutable	Default	Minimum	Maximum
"je.evictor.maxThreads"	Integer	yes	10	1	Integer.MAX_VALUE

See Also:

Constant Field Values

EVICTOR_KEEP_ALIVE

public static final String EVICTOR_KEEP_ALIVE

The duration that excess threads in the eviction thread pool will stay idle. After this period, idle threads will terminate. je.evictor.coreThreads, je.evictor.maxThreads and je.evictor.keepAlive are used to configure the core, max and keepalive attributes for the ThreadPoolExecutor which implements the eviction thread pool.

Name	Type	Mutable	Default	Minimum	Maximum
"je.evictor.keepAlive"	Duration	Yes	10 min	1 s	1 d

See Also:

Time Duration Properties, Constant Field Values

EVICTOR_ALLOW_BIN_DELTAS

public static final String EVICTOR_ALLOW_BIN_DELTAS

Allow Bottom Internal Nodes (BINs) to be written in a delta format during eviction. Using a delta format will improve write and log cleaning performance, but may reduce read performance if BINs are not maintained in cache memory.

Name	Type	Mutable	Default
"je.evictor.allowBinDeltas"	Boolean	No	true

See Also:

Constant Field Values

CHECKPOINTER_BYTES_INTERVAL

public static final String CHECKPOINTER_BYTES_INTERVAL

Ask the checkpointer to run every time we write this many bytes to the log. If set, supercedes CHECKPOINTER_WAKEUP_INTERVAL. To use time based checkpointing, set this to 0.

Name	Type	Mutable	Default	Minimum	Maximum	JVM
"je.checkpointer.bytesInterval"	Long	No	20000000 (20M)	0	-none-	Conventional JVM
"je.checkpointer.bytesInterval"	Long	No	200000 (200K)	0	-none-	Dalvik JVM

See Also:

Constant Field Values

CHECKPOINTER_WAKEUP_INTERVAL

public static final String CHECKPOINTER_WAKEUP_INTERVAL

The checkpointer wakeup interval in microseconds. By default, this is inactive and we wakeup the checkpointer as a function of the number of bytes written to the log (CHECKPOINTER_BYTES_INTERVAL).

Name	Type	Mutable	Default	Minimum	Maximum
"je.checkpointer.wakeupInterval"	Duration	No	0	1 s	75 min

See Also:

Time Duration Properties, Constant Field Values

CHECKPOINTER_DEADLOCK_RETRY

public static final String CHECKPOINTER_DEADLOCK_RETRY

The number of times to retry a checkpoint if it runs into a deadlock.

Name	Type	Mutable	Default	Minimum	Maximum
"je.checkpointer.deadlockRetry"	Integer	No	3	0	-none-

See Also:

Constant Field Values

CHECKPOINTER_HIGH_PRIORITY

public static final String CHECKPOINTER_HIGH_PRIORITY

If true, the checkpointer uses more resources in order to complete the checkpoint in a shorter time interval. Btree latches are held and other threads are blocked for a longer period. Log cleaner record migration is performed by cleaner threads instead of lazily during eviction and checkpoints (see CLEANER_LAZY_MIGRATION). When set to true, application response time may be longer during a checkpoint, and more cleaner threads may be required to maintain the configured log utilization.

Note that lazy migration is disabled when the CHECKPOINTER_HIGH_PRIORITY parameter is set to true, regardless of the CLEANER_LAZY_MIGRATION setting.

Name	Type	Mutable	Default
"je.checkpointer.highPriority"	Boolean	Yes	false

See Also:

Constant Field Values

CLEANER_MIN_UTILIZATION

public static final String CLEANER_MIN_UTILIZATION

The cleaner will keep the total disk space utilization percentage above this value.

Name	Type	Mutable	Default	Minimum	Maximum
"je.cleaner.minUtilization"	Integer	Yes	50	0	90

See Also:

Constant Field Values

CLEANER_MIN_FILE_UTILIZATION

public static final String CLEANER_MIN_FILE_UTILIZATION

A log file will be cleaned if its utilization percentage is below this value, irrespective of total utilization.

Name	Type	Mutable	Default	Minimum	Maximum
"je.cleaner.minFileUtilization"	Integer	Yes	5	0	50

See Also:

Constant Field Values

CLEANER_BYTES_INTERVAL

public static final String CLEANER_BYTES_INTERVAL

The cleaner checks disk utilization every time we write this many bytes to the log. If zero (and by default) it is set to the LOG_FILE_MAX value divided by four.

Name	Type	Mutable	Default	Minimum	Maximum
"je.cleaner.bytesInterval"	Long	Yes	0	0	-none-

See Also:

Constant Field Values

CLEANER_FETCH_OBSOLETE_SIZE

public static final String CLEANER_FETCH_OBSOLETE_SIZE

If true, the cleaner will fetch records to determine their size and more accurately calculate log utilization. Normally when a record is updated or deleted without first being read (sometimes called a blind delete/update), the size of the previous version of the record is unknown and therefore the cleaner's utilization calculations may be incorrect. Setting this parameter to true will cause a record to be read during a blind delete/update, in order to determine its size. This will ensure that the cleaner's utilization calculations are correct, but will cause more (potentially random) IO.

To guarantee that utilization will be calculated accurately for all workloads and that automatic adjustments will not interfere, CLEANER_FETCH_OBSOLETE_SIZE should be set to true and CLEANER_ADJUST_UTILIZATION should be set to false.

Name	Type	Mutable	Default
"je.cleaner.fetchObsoleteSize"	Boolean	Yes	false

See Also:

CLEANER_ADJUST_UTILIZATION, Constant Field Values

CLEANER_ADJUST_UTILIZATION

public static final String CLEANER_ADJUST_UTILIZATION

If true, the cleaner will attempt to adjust utilization to account for unknown record sizes. When a record is updated or deleted without first being read (sometimes called a blind delete/update), the size of the previous version of the record is unknown and therefore the cleaner's utilization calculations may be incorrect. To compensate for such inaccuracies, JE uses the following approach.

• When a data file contains obsolete records and the record sizes are unknown, the average record size in a log file is used to estimate the utilization of that file. However, the average size may not reflect the true size of the obsolete records, if an application creates records of varying sizes and then deletes or updates records of non-average sizes.
• When a data file is cleaned, statistics are collected about the actual utilization versus the estimated utilization. Using this information from the 10 most recently cleaned files, the EnvironmentStats.getLNSizeCorrectionFactor() statistic is maintained. This factor can be multiplied by the average record size to obtain the actual obsolete size.
• When no log cleaning is occurring because the estimated utilization is above the configured threshold (see CLEANER_MIN_UTILIZATION), the LNSizeCorrectionFactor cannot be determined. In this situation, JE will perform trial cleaner runs called probes. A probe is similar to cleaning a log file in that it collects information about actual utilization, but the file is not actually cleaned -- no records are copied and the file is not deleted. Probes are performed only when necessary to collect utilization statistics.
• Once the LNSizeCorrectionFactor is known, it is applied to calculate the total utilization of the log and determine whether cleaning is necessary (see CLEANER_MIN_UTILIZATION), and to determine which log files have the lowest utilization and should be selected for cleaning. The LNSizeCorrectionFactor is also used in the DbSpace calculations and is printed at the bottom of the report.

By default this parameter is true and the approach described above is used. This parameter may be set to false to prevent undesired automatic adjustments. Because the adjustments are based on sampled information and application workloads may change over time, the adjustments are not always beneficial. Utilization may be adjusted incorrectly, causing undesired over-cleaning or under-cleaning.

When this parameter is set to false, the last two steps above are not applied. The LNSizeCorrectionFactor will still be calculated when log files are cleaned and will be available via the EnvironmentStats.getLNSizeCorrectionFactor() method. However, the LNSizeCorrectionFactor will not be used to adjust the estimated utilization, and cleaner probes will not be performed. Log files will be cleaned based on the estimated utilization alone.

To guarantee that utilization will be calculated accurately for all workloads and that automatic adjustments will not interfere, CLEANER_FETCH_OBSOLETE_SIZE should be set to true and CLEANER_ADJUST_UTILIZATION should be set to false.

Name	Type	Mutable	Default
"je.cleaner.adjustUtilization"	Boolean	Yes	true

See Also:

CLEANER_FETCH_OBSOLETE_SIZE, Constant Field Values

CLEANER_DEADLOCK_RETRY

public static final String CLEANER_DEADLOCK_RETRY

The number of times to retry cleaning if a deadlock occurs.

Name	Type	Mutable	Default	Minimum	Maximum
"je.cleaner.deadlockRetry"	Integer	Yes	3	0	-none-

See Also:

Constant Field Values

CLEANER_LOCK_TIMEOUT

public static final String CLEANER_LOCK_TIMEOUT

The lock timeout for cleaner transactions in microseconds.

Name	Type	Mutable	Default	Minimum	Maximum
"je.cleaner.lockTimeout"	Duration	Yes	500 ms	0	75 min

See Also:

Time Duration Properties, Constant Field Values

CLEANER_EXPUNGE

public static final String CLEANER_EXPUNGE

If true, the cleaner deletes log files after successful cleaning. If false, the cleaner changes log file extensions to .DEL instead of deleting them. The latter is useful for diagnosing log cleaning problems.

Name	Type	Mutable	Default
"je.cleaner.expunge"	Boolean	Yes	true

See Also:

Constant Field Values

CLEANER_MIN_AGE

public static final String CLEANER_MIN_AGE

The minimum age of a file (number of files between it and the active file) to qualify it for cleaning under any conditions.

Name	Type	Mutable	Default	Minimum	Maximum
"je.cleaner.minAge"	Integer	Yes	2	1	1000

See Also:

Constant Field Values

CLEANER_MAX_BATCH_FILES

public static final String CLEANER_MAX_BATCH_FILES

The maximum number of log files in the cleaner's backlog, or zero if there is no limit. Changing this property can impact the performance of some out-of-memory applications.

Name	Type	Mutable	Default	Minimum	Maximum
"je.cleaner.maxBatchFiles"	Integer	Yes	0	0	100000

See Also:

Constant Field Values

CLEANER_READ_SIZE

public static final String CLEANER_READ_SIZE

The read buffer size for cleaning. If zero (the default), then LOG_ITERATOR_READ_SIZE value is used.

Name	Type	Mutable	Default	Minimum	Maximum
"je.cleaner.readSize"	Integer	Yes	0	128	-none-

See Also:

Constant Field Values

CLEANER_DETAIL_MAX_MEMORY_PERCENTAGE

public static final String CLEANER_DETAIL_MAX_MEMORY_PERCENTAGE

Tracking of detailed cleaning information will use no more than this percentage of the cache. The default value is 2% of MAX_MEMORY. If 0 and SHARED_CACHE is true, use 2% divided by N where N is the number of environments sharing the global cache.

Name	Type	Mutable	Default	Minimum	Maximum
"je.cleaner.detailMaxMemoryPercentage"	Integer	Yes	2	1	90

See Also:

Constant Field Values

CLEANER_FORCE_CLEAN_FILES

public static final String CLEANER_FORCE_CLEAN_FILES

Specifies a list of files or file ranges to be cleaned at a time when no other log cleaning is necessary. This parameter is intended for use in forcing the cleaning of a large number of log files. File numbers are in hex and are comma separated or hyphen separated to specify ranges, e.g.: '9,a,b-d' will clean 5 files.

Name	Type	Mutable	Default
"je.cleaner.forceCleanFiles"	String	No	""

See Also:

Constant Field Values

CLEANER_UPGRADE_TO_LOG_VERSION

public static final String CLEANER_UPGRADE_TO_LOG_VERSION

All log files having a log version prior to the specified version will be cleaned at a time when no other log cleaning is necessary. Intended for use in upgrading old format log files forward to the current log format version, e.g., to take advantage of format improvements; note that log upgrading is optional. The default value zero (0) specifies that no upgrading will occur. The value negative one (-1) specifies upgrading to the current log version.

Name	Type	Mutable	Default	Minimum	Maximum
"je.cleaner.upgradeToLogVersion"	Integer	No	0	-1	-none-

See Also:

Constant Field Values

CLEANER_THREADS

public static final String CLEANER_THREADS

The number of threads allocated by the cleaner for log file processing. If the cleaner backlog becomes large, try increasing this value.

Name	Type	Mutable	Default	Minimum	Maximum
"je.cleaner.threads"	Integer	Yes	1	1	-none-

See Also:

Constant Field Values

CLEANER_LOOK_AHEAD_CACHE_SIZE

public static final String CLEANER_LOOK_AHEAD_CACHE_SIZE

The look ahead cache size for cleaning in bytes. Increasing this value can reduce the number of Btree lookups.

Name	Type	Mutable	Default	Minimum	Maximum
"je.cleaner.lookAheadCacheSize"	Integer	Yes	8192 (8K)	0	-none-

See Also:

Constant Field Values

CLEANER_FOREGROUND_PROACTIVE_MIGRATION

public static final String CLEANER_FOREGROUND_PROACTIVE_MIGRATION

If true, the cleaner will fetch log entries (incurring the cost of random I/O) during eviction, Btree splits, and other application foreground thread activities, in order to migrate log entries and reduce the cleaner backlog.

This parameter is false by default in order to avoid database operation delays caused by random I/O during eviction and Btree splits. This parameter may be set to true to keep the cleaner backlog from growing when the number of cleaner threads is not sufficient to prevent a backlog. This should be done only when database operation delays are acceptable. By database operations we mean ordinary record reads and writes (get() and put() method calls).

Name	Type	Mutable	Default
"je.cleaner.foregroundProactiveMigration"	Boolean	Yes	false

Since:

4.0

See Also:

Constant Field Values

CLEANER_BACKGROUND_PROACTIVE_MIGRATION

public static final String CLEANER_BACKGROUND_PROACTIVE_MIGRATION

If true, the cleaner will fetch log entries (incurring the cost of random I/O) during checkpoints and other JE background thread activities, in order to migrate log entries and reduce the cleaner backlog.

This parameter is false by default in order to avoid long checkpoint durations caused by random I/O during the checkpoint. This parameter may be set to true to keep the cleaner backlog from growing when the number of cleaner threads is not sufficient to prevent a backlog. This should be done only when the resulting duration of the checkpoint is acceptable.

Name	Type	Mutable	Default
"je.cleaner.backgroundProactiveMigration"	Boolean	Yes	false

Since:

4.0

See Also:

Constant Field Values

CLEANER_LAZY_MIGRATION

public static final String CLEANER_LAZY_MIGRATION

Controls whether log cleaner threads perform LN (leaf node or record) migration immediately when processing a log file, or lazily during eviction and checkpointing. LN migration is the copying of active records from the log file being cleaned to the end of the log, prior to deletion of the log file.

By default this parameter is false. When set to true, LN migration is performed lazily during eviction (when the cache fills) and checkpointing. LNs are placed into the JE cache by the log cleaner threads as the LNs are read sequentially from the log file, but the LNs are not logged until their parent BIN (Bottom Internal Node) is evicted or checkpointed. Lazy migration has two potential advantages:

• Because records are logged when their parent BIN in the Btree is logged, records are clustered together by key as they are migrated, even when those records were not originally written in key order. This has a performance benefit if records with adjacent keys are frequently accessed together, i.e., locality of reference. However, it may be undesirable if records are frequently accessed in the order they were originally written, rather than in key order.
• Lazy migration off-loads work from the log cleaner threads to the application threads (which perform eviction) and the checkpointer thread, making it easier for the log cleaner to "keep up" with heavy write activity and maintain the configured log utilization.

If this parameter is set to false (or left false by default), LN migration will be performed immediately by the log cleaner threads, or by an application thread calling Environment.cleanLog(). Immediate migration has three potential advantages:

• Eviction and checkpointing will do less work, because they will not perform LN migration. This may result in shorter response times for application operations, and will definitely result in faster checkpoints (see CHECKPOINTER_HIGH_PRIORITY). However, more cleaner threads may be required to maintain the configured log utilization.
• When records are frequently accessed in the order they are written rather than in key order, immediate migration will preserve their order in the log.
• Migrated LNs will not occupy space in the cache, avoiding possible interference with an application caching policy.

Note that lazy migration is disabled when the CHECKPOINTER_HIGH_PRIORITY parameter is set to true, regardless of the CLEANER_LAZY_MIGRATION setting.

Name	Type	Mutable	Default
"je.cleaner.lazyMigration"	Boolean	Yes	false

See Also:

Constant Field Values

DOS_PRODUCER_QUEUE_TIMEOUT

public static final String DOS_PRODUCER_QUEUE_TIMEOUT

The timeout for Disk Ordered Scan producer thread queue offers in milliseconds.

Name	Type	Mutable	Default	Minimum	Maximum
"je.env.diskOrderedScanLockTimeout"	Duration	Yes	10 secs	0	75 min

See Also:

Time Duration Properties, Constant Field Values

LOCK_N_LOCK_TABLES

public static final String LOCK_N_LOCK_TABLES

Number of Lock Tables. Set this to a value other than 1 when an application has multiple threads performing concurrent JE operations. It should be set to a prime number, and in general not higher than the number of application threads performing JE operations.

Name	Type	Mutable	Default	Minimum	Maximum
"je.lock.nLockTables"	Integer	No	1	1	32767 (32K)

See Also:

Constant Field Values

LOCK_TIMEOUT

public static final String LOCK_TIMEOUT

The LockTimeout property.

Name	Type	Mutable	Default	Minimum	Maximum
"je.lock.timeout"	Duration	No	500 ms	0	75 min

See Also:

setLockTimeout(long,TimeUnit), Time Duration Properties, Constant Field Values

LOCK_OLD_LOCK_EXCEPTIONS

public static final String LOCK_OLD_LOCK_EXCEPTIONS

Whether to throw old-style lock exceptions for compatibility with older JE releases.

In JE 3.3 and earlier, DeadlockException or a subclass of it was always thrown when a lock conflict occurred. Applications typically caught DeadlockException in order to detect lock conflicts and determine whether to retry a transaction. DeadlockException itself was thrown when a lock or transaction timeout occurred and LockNotGrantedException (a subclass of DeadlockException) was thrown when a lock conflict occurred for a no-wait transaction (see TransactionConfig.setNoWait(boolean)).

In all releases after JE 3.3, new exceptions and the new base class LockConflictException are available. Now, LockConflictException should be caught to handle lock conflicts in a general manner, instead of catching DeadlockException. New exceptions are now thrown as follows:

• LockTimeoutException is now thrown when a lock timeout occurs, rather than DeadlockException.
• TransactionTimeoutException is now thrown when a transaction timeout occurs, rather than DeadlockException.
• LockNotAvailableException is now thrown when a lock conflict occurs for a no-wait transaction, rather than LockNotGrantedException.

These three new exceptions are subclasses of LockConflictException. DeadlockException is also now a subclass of LockConflictException, but is not currently thrown by JE because true deadlock detection is not used in JE. Currently, lock timeouts are used instead. When true deadlock detection is added to JE in the future, DeadlockException will be thrown. LockNotGrantedException has been deprecated and replaced by LockNotAvailableException.

The LOCK_OLD_LOCK_EXCEPTIONS configuraton parameter may be explicitly set to true to enable the old exception behavior. By default, this parameter is false.

Unless LOCK_OLD_LOCK_EXCEPTIONS is set to true, the following changes must be made to JE applications that upgrade from JE 3.3 or earlier.

1. All occurrences of DeadlockException must be replaced with LockConflictException or one of its non-deprecated subclasses (LockTimeoutException, TransactionTimeoutException, or LockNotAvailableException). It is strongly recommended to replace it with LockConflictException, since catching this exception will catch true deadlocks in the future and other types of lock conflicts. All lock conflicts all typically handled in the same way, which is normally to abort and retry the transaction.
2. All occurances of LockNotGrantedException must be replaced with LockNotAvailableException. LockNotGrantedException has been deprecated because it misleadingly extends DeadlockException.

Name	Type	Mutable	Default
"je.lock.oldLockExceptions"	Boolean	No	false

See Also:

Constant Field Values

TXN_TIMEOUT

public static final String TXN_TIMEOUT

The TxnTimeout property.

Name	Type	Mutable	Default	Minimum	Maximum
"je.txn.timeout"	Duration	No	0	0	75 min

See Also:

setTxnTimeout(long, java.util.concurrent.TimeUnit), Time Duration Properties, Constant Field Values

TXN_SERIALIZABLE_ISOLATION

public static final String TXN_SERIALIZABLE_ISOLATION

The TxnSerializableIsolation property.

Name	Type	Mutable	Default
"je.txn.serializableIsolation"	Boolean	No	false

See Also:

setTxnSerializableIsolation(boolean), Constant Field Values

TXN_DEADLOCK_STACK_TRACE

public static final String TXN_DEADLOCK_STACK_TRACE

Set this parameter to true to add stacktrace information to deadlock (lock timeout) exception messages. The stack trace will show where each lock was taken. The default is false, and true should only be used during debugging because of the added memory/processing cost. This parameter is 'static' across all environments.

Name	Type	Mutable	Default
"je.txn.deadlockStackTrace"	Boolean	Yes	false

See Also:

Constant Field Values

TXN_DUMP_LOCKS

public static final String TXN_DUMP_LOCKS

Dump the lock table when a lock timeout is encountered, for debugging assistance.

Name	Type	Mutable	Default
"je.txn.dumpLocks"	Boolean	Yes	false

See Also:

Constant Field Values

TRACE_FILE

public static final String TRACE_FILE

Deprecated. in favor of FILE_LOGGING_LEVEL As of JE 4.0, use the standard java.util.logging configuration methodologies. To enable logging output to the je.info files, set com.sleepycat.je.util.FileHandler.level = <LEVEL> through the java.util.logging configuration file, or through the java.util.logging.LogManager. To set the handler level programmatically, set "com.sleepycat.je.util.FileHandler.level" in the EnvironmentConfig object.

Use FileHandler in logging system.

Name	Type	Mutable	Default
"java.util.logging.FileHandler.on"	Boolean	No	false

See Also:

Constant Field Values

TRACE_CONSOLE

public static final String TRACE_CONSOLE

Deprecated. in favor of CONSOLE_LOGGING_LEVEL As of JE 4.0, use the standard java.util.logging configuration methodologies. To enable console output, set com.sleepycat.je.util.ConsoleHandler.level = <LEVEL> through the java.util.logging configuration file, or through the java.util.logging.LogManager. To set the handler level programmatically, set "com.sleepycat.je.util.ConsoleHandler.level" in the EnvironmentConfig object.

Enable ConsoleHandler in logging system.

Name	Type	Mutable	Default
"java.util.logging.ConsoleHandler.on"	Boolean	No	false

See Also:

Constant Field Values

TRACE_DB

public static final String TRACE_DB

Deprecated. As of JE 4.0, event tracing to the .jdb files has been separated from the java.util.logging mechanism. This parameter has no effect.

Use DbLogHandler in logging system.

Name	Type	Mutable	Default
"java.util.logging.DbLogHandler.on"	Boolean	No	true

See Also:

Constant Field Values

TRACE_FILE_LIMIT

public static final String TRACE_FILE_LIMIT

Deprecated. As of JE 4.0, use the standard java.util.logging configuration methodologies. To set the FileHandler output file size, set com.sleepycat.je.util.FileHandler.limit = <NUMBER> through the java.util.logging configuration file, or through the java.util.logging.LogManager.

Log file limit for FileHandler.

Name	Type	Mutable	Default	Minimum	Maximum
"java.util.logging.FileHandler.limit"	Integer	No	10000000 (10M)	1000	1000000000 (1G)

See Also:

Constant Field Values

TRACE_FILE_COUNT

public static final String TRACE_FILE_COUNT

Deprecated. As of JE 4.0, use the standard java.util.logging configuration methodologies. To set the FileHandler output file count, set com.sleepycat.je.util.FileHandler.count = <NUMBER> through the java.util.logging configuration file, or through the java.util.logging.LogManager.

Log file count for FileHandler.

Name	Type	Mutable	Default	Minimum	Maximum
"java.util.logging.FileHandler.count"	Integer	No	10	1	-none-

See Also:

Constant Field Values

TRACE_LEVEL

public static final String TRACE_LEVEL

Deprecated. As of JE 4.0, use the standard java.util.logging configuration methodologies. Set logging levels using class names through the java.util.logging configuration file, or through the java.util.logging.LogManager.

Trace messages equal and above this level will be logged. Value should be one of the predefined java.util.logging.Level values.

Name	Type	Mutable	Default
"java.util.logging.level"	String	No	"INFO"

See Also:

Constant Field Values

CONSOLE_LOGGING_LEVEL

public static final String CONSOLE_LOGGING_LEVEL

Trace messages equal and above this level will be logged to the console. Value should be one of the predefined java.util.logging.Level values.

Setting this parameter in the je.properties file or through setConfigParam(java.lang.String, java.lang.String) is analogous to setting the property in the java.util.logging properties file or MBean. It is preferred to use the standard java.util.logging mechanisms for configuring java.util.logging.Handler, but this JE parameter is provided because the java.util.logging API doesn't provide a method to set handler levels programmatically.

Name	Type	Mutable	Default
"com.sleepycat.je.util.ConsoleHandler.level"	String	No	"OFF"

See Also:

Chapter 12. Logging, Constant Field Values

FILE_LOGGING_LEVEL

public static final String FILE_LOGGING_LEVEL

Trace messages equal and above this level will be logged to the je.info file, which is in the Environment home directory. Value should be one of the predefined java.util.logging.Level values.

Setting this parameter in the je.properties file or through setConfigParam(java.lang.String, java.lang.String) is analogous to setting the property in the java.util.logging properties file or MBean. It is preferred to use the standard java.util.logging mechanisms for configuring java.util.logging.Handler, but this JE parameter is provided because the java.util.logging APIs doesn't provide a method to set handler levels programmatically.

Name	Type	Mutable	Default
"com.sleepycat.je.util.FileHandler.level"	String	No	"INFO"

See Also:

Chapter 12. Logging, Constant Field Values

TRACE_LEVEL_LOCK_MANAGER

public static final String TRACE_LEVEL_LOCK_MANAGER

Deprecated. As of JE 4.0, use the standard java.util.logging configuration methodologies. To see locking logging, set com.sleepycat.je.txn.level = <LEVEL> through the java.util.logging configuration file, or through the java.util.logging.LogManager.

Lock manager specific trace messages will be issued at this level. Value should be one of the predefined java.util.logging.Level values.

Name	Type	Mutable	Default
"java.util.logging.level.lockMgr"	String	No	"FINE"

See Also:

Constant Field Values

TRACE_LEVEL_RECOVERY

public static final String TRACE_LEVEL_RECOVERY

Deprecated. As of JE 4.0, use the standard java.util.logging configuration methodologies. To see recovery logging, set com.sleepycat.je.recovery.level = <LEVEL> through the java.util.logging configuration file, or through the java.util.logging.LogManager.

Recovery specific trace messages will be issued at this level. Value should be one of the predefined java.util.logging.Level values.

Name	Type	Mutable	Default
"java.util.logging.level.recovery"	String	No	"FINE"

See Also:

Constant Field Values

TRACE_LEVEL_EVICTOR

public static final String TRACE_LEVEL_EVICTOR

Deprecated. As of JE 4.0, use the standard java.util.logging configuration methodologies. To see evictor logging, set com.sleepycat.je.evictor.level = <LEVEL> through the java.util.logging configuration file, or through the java.util.logging.LogManager.

Evictor specific trace messages will be issued at this level. Value should be one of the predefined java.util.logging.Level values.

Name	Type	Mutable	Default
"java.util.logging.level.evictor"	String	No	"FINE"

See Also:

Constant Field Values

TRACE_LEVEL_CLEANER

public static final String TRACE_LEVEL_CLEANER

Deprecated. As of JE 4.0, use the standard java.util.logging configuration methodologies. To see cleaner logging, set com.sleepycat.je.cleaner.level = <LEVEL> through the java.util.logging configuration file, or through the java.util.logging.LogManager.

Cleaner specific detailed trace messages will be issued at this level. Value should be one of the predefined java.util.logging.Level values.

Name	Type	Mutable	Default
"java.util.logging.level.cleaner"	String	Yes	"FINE"

See Also:

Constant Field Values

STARTUP_DUMP_THRESHOLD

public static final String STARTUP_DUMP_THRESHOLD

If environment startup exceeds this duration, startup statistics are logged and can be found in the je.info file.

Name	Type	Mutable	Default	Minimum	Maximum
"je.env.startupThreshold"	Duration	No	5 min	0	none

See Also:

Time Duration Properties, Constant Field Values

STATS_COLLECT

public static final String STATS_COLLECT

If true collect and log statistics. The statistics are logged in CSV format and written to the log file at a user specified interval. The logging occurs per-Environment when the Environment is opened in read/write mode. Statistics are written to a filed named je.stat.csv. Successively older files are named by adding "0", "1", "2", etc into the file name. The file name format is je.stat.[version number].csv.

Name	Type	Mutable	Default	Minimum	Maximum
"je.stats.collect"	Boolean	Yes	True	0	none

See Also:

Constant Field Values

STATS_MAX_FILES

public static final String STATS_MAX_FILES

Maximum number of statistics log files to retain. The rotating set of files, as each file reaches a given size limit, is closed, rotated out, and a new file opened. The name of the log file is je.stat.csv. Successively older files are named by adding "0", "1", "2", etc into the file name. The file name format is je.stat.[version number].csv.

Name	Type	Mutable	Default	Minimum	Maximum
"je.stats.max.files"	Integer	Yes	10	1	-none-

See Also:

Constant Field Values

STATS_FILE_ROW_COUNT

public static final String STATS_FILE_ROW_COUNT

Log file maximum row count for Stat collection. When the number of rows in the statistics file reaches the maximum row count, the file is closed, rotated out, and a new file opened. The name of the log file is je.stat.csv. Successively older files are named by adding "0", "1", "2", etc into the file name. The file name format is je.stat.[version number].csv.

Name	Type	Mutable	Default	Minimum	Maximum
"je.stats.file.row.count"	Integer	Yes	1440	1	-none-

See Also:

Constant Field Values

STATS_COLLECT_INTERVAL

public static final String STATS_COLLECT_INTERVAL

The duration of the statistics capture interval. Statistics are captured and written to the log file at this interval.

Name	Type	Mutable	Default	Minimum	Maximum
"je.stats.collect.interval"	Duration	Yes	1 min	1 s	24 d

See Also:

Time Duration Properties, Constant Field Values

STATS_FILE_DIRECTORY

public static final String STATS_FILE_DIRECTORY

The directory to save the statistics log file.

Name	Type	Mutable	Default
"je.stats.file.directory"	String	No	"NULL-> Environment home directory"

See Also:

Constant Field Values

Constructor Detail

EnvironmentConfig

public EnvironmentConfig()

Creates an EnvironmentConfig initialized with the system default settings.

EnvironmentConfig

public EnvironmentConfig(Properties properties)
                  throws IllegalArgumentException

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

Parameters:

properties - Supported properties are described in this class

Throws:

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

Method Detail

setAllowCreate

public EnvironmentConfig setAllowCreate(boolean allowCreate)

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

Parameters:

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

Returns:

this

getAllowCreate

public boolean getAllowCreate()

Returns a flag that specifies if we may create this environment.

Returns:

true if we may create this environment.

setLockTimeout

public EnvironmentConfig setLockTimeout(long timeout,
                               TimeUnit unit)
                                 throws IllegalArgumentException

Configures the lock timeout.

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

Parameters:

timeout - The lock timeout for all transactional and non-transactional operations. A value of zero disables lock timeouts, meaning that no lock wait time limit is enforced and a deadlocked operation will block indefinitely. We strongly recommend that a large timeout value, rather than zero, is used when deadlocks are not expected. That way, a timeout exception will be thrown when an unexpected deadlock occurs.

unit - the TimeUnit of the timeout value. May be null only if timeout is zero.

Returns:

this

Throws:

IllegalArgumentException - if the value of timeout is invalid

See Also:

Transaction.setLockTimeout(long,TimeUnit)

setLockTimeout

public EnvironmentConfig setLockTimeout(long timeout)
                                 throws IllegalArgumentException

Deprecated. as of 4.0, replaced by setLockTimeout(long, TimeUnit).

Configures the lock timeout, in microseconds. This method is equivalent to:

setLockTimeout(long, TimeUnit.MICROSECONDS);

Throws:

IllegalArgumentException

getLockTimeout

public long getLockTimeout(TimeUnit unit)

Returns the lock timeout setting.

Parameters:

unit - the TimeUnit of the returned value. May not be null. A value of 0 means no timeout is set.

getLockTimeout

public long getLockTimeout()

Deprecated. as of 4.0, replaced by getLockTimeout(TimeUnit).

Returns the lock timeout setting, in microseconds. This method is equivalent to:

getLockTimeout(TimeUnit.MICROSECONDS);

setReadOnly

public EnvironmentConfig setReadOnly(boolean readOnly)

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

A read-only environment has several limitations and is recommended only in special circumstances. Note that there is no performance advantage to opening an environment read-only.

The primary reason for opening an environment read-only is to open a single environment in multiple JVM processes. Only one JVM process at a time may open the environment read-write. See EnvironmentLockedException.

When the environment is open read-only, the following limitations apply.

• In the read-only environment no writes may be performed, as expected, and databases must be opened read-only using DatabaseConfig.setReadOnly(boolean).
• The read-only environment receives a snapshot of the data that is effectively frozen at the time the environment is opened. If the application has the environment open read-write in another JVM process and modifies the environment's databases in any way, the read-only version of the data will not be updated until the read-only JVM process closes and reopens the environment (and by extension all databases in that environment).
• If the read-only environment is opened while the environment is in use by another JVM process in read-write mode, opening the environment read-only (recovery) is likely to take longer than it does after a clean shutdown. This is due to the fact that the read-write JVM process is writing and checkpoints are occurring that are not coordinated with the read-only JVM process. The effect is similar to opening an environment after a crash.
• In a read-only environment, the JE cache will contain information that cannot be evicted because it was reconstructed by recovery and cannot be flushed to disk. This means that the read-only environment may not be suitable for operations that use large amounts of memory, and poor performance may result if this is attempted.
• In a read-write environment, the log cleaner will be prohibited from deleting log files for as long as the environment is open read-only in another JVM process. This may cause disk usage to rise, and for this reason it is not recommended that an environment is kept open read-only in this manner for long periods.

For these reasons, it is recommended that a read-only environment be used only for short periods and for operations that are not performance critical or memory intensive. With few exceptions, all application functions that require access to a JE environment should be built into a single application so that they can be performed in the JVM process where the environment is open read-write.

In most applications, opening an environment read-only can and should be avoided.

Parameters:

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

Returns:

this

getReadOnly

public boolean getReadOnly()

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

setTransactional

public EnvironmentConfig setTransactional(boolean transactional)

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

Returns:

this

getTransactional

public boolean getTransactional()

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

setLocking

public EnvironmentConfig setLocking(boolean locking)

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

Returns:

this

getLocking

public boolean getLocking()

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

setTxnTimeout

public EnvironmentConfig setTxnTimeout(long timeout,
                              TimeUnit unit)
                                throws IllegalArgumentException

Configures the transaction timeout.

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

Parameters:

timeout - The transaction timeout. A value of 0 turns off transaction timeouts.

unit - the TimeUnit of the timeout value. May be null only if timeout is zero.

Returns:

this

Throws:

IllegalArgumentException - If the value of timeout is negative

See Also:

Transaction.setTxnTimeout(long, java.util.concurrent.TimeUnit)

setTxnTimeout

public EnvironmentConfig setTxnTimeout(long timeout)
                                throws IllegalArgumentException

Deprecated. as of 4.0, replaced by setTxnTimeout(long, TimeUnit).

Configures the transaction timeout, in microseconds. This method is equivalent to:

setTxnTimeout(long, TimeUnit.MICROSECONDS);

Throws:

IllegalArgumentException

getTxnTimeout

public long getTxnTimeout(TimeUnit unit)

Returns the transaction timeout.

A value of 0 means transaction timeouts are not configured.

Parameters:

unit - the TimeUnit of the returned value. May not be null.

Returns:

The transaction timeout.

getTxnTimeout

public long getTxnTimeout()

Deprecated. as of 4.0, replaced by getTxnTimeout(TimeUnit).

Returns the transaction timeout, in microseconds. This method is equivalent to:

getTxnTimeout(TimeUnit.MICROSECONDS);

setTxnSerializableIsolation

public EnvironmentConfig setTxnSerializableIsolation(boolean txnSerializableIsolation)

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

Returns:

this

See Also:

LockMode

getTxnSerializableIsolation

public boolean getTxnSerializableIsolation()

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

Returns:

true if the environment has been configured to have repeatable read isolation.

See Also:

LockMode

setSharedCache

public EnvironmentConfig setSharedCache(boolean sharedCache)

If true, the shared cache is used by this environment.

By default this parameter is false and this environment uses a private cache. If this parameter is set to true, this environment will use a cache that is shared with all other open environments in this process that also set this parameter to true. There is a single shared cache per process.

By using the shared cache, multiple open environments will make better use of memory because the cache LRU algorithm is applied across all information in all environments sharing the cache. For example, if one environment is open but not recently used, then it will only use a small portion of the cache, leaving the rest of the cache for environments that have been recently used.

Parameters:

sharedCache - If true, the shared cache is used by this environment.

Returns:

this

getSharedCache

public boolean getSharedCache()

Returns true if the shared cache is used by this environment.

Returns:

true if the shared cache is used by this environment. @see #setSharedCache

setNodeName

public EnvironmentConfig setNodeName(String nodeName)

Sets the user defined nodeName for the Environment. If set, exception messages, logging messages, and thread names will have this nodeName included in them. If a user has multiple Environments in a single JVM, setting this to a string unique to each Environment may make it easier to diagnose certain exception conditions as well as thread dumps.

Returns:

this

getNodeName

public String getNodeName()

Returns the user defined nodeName for the Environment.

setCustomStats

public EnvironmentConfig setCustomStats(CustomStats customStats)

Sets the custom statistics object.

Returns:

this

getCustomStats

public CustomStats getCustomStats()

Gets the custom statstics object.

Returns:

customStats

setLoggingHandler

public EnvironmentConfig setLoggingHandler(Handler handler)

Set a java.util.logging.Handler which will be used by all java.util.logging.Loggers instantiated by this Environment. This lets the application specify a handler which

• requires a constructor with arguments
• is specific to this environment, which is important if the application is using multiple environments within the same process.

Note that Handler is not serializable, and the logging handler should be set within the same process.

getLoggingHandler

public Handler getLoggingHandler()

Returns the custom java.util.logging.Handler specified by the application.

setConfigParam

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

Description copied from class: EnvironmentMutableConfig

Set this configuration parameter. First validate the value specified for the configuration parameter; if it is valid, the value is set in the configuration.

Overrides:

setConfigParam in class EnvironmentMutableConfig

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.

setRecoveryProgressListener

public EnvironmentConfig setRecoveryProgressListener(ProgressListener<RecoveryProgress> progressListener)

Configure the environment to make periodic calls to a ProgressListener to provide feedback on environment startup (recovery). The ProgressListener.progress() method is called at different stages of the recovery process. See RecoveryProgress for information about those stages.

When using progress listeners, review the information at ProgressListener.progress(T, long, long) to avoid any unintended disruption to environment startup.

Parameters:

progressListener - The ProgressListener to callback during environment startup (recovery).

getRecoveryProgressListener

public ProgressListener<RecoveryProgress> getRecoveryProgressListener()

Return the ProgressListener to be used at this environment startup.

setClassLoader

public EnvironmentConfig setClassLoader(ClassLoader classLoader)

Configure the environment to use a specified ClassLoader for loading user-supplied classes by name.

getClassLoader

public ClassLoader getClassLoader()

Returns the ClassLoader for loading user-supplied classes by name, or null if no specified ClassLoader is configured.

clone

public EnvironmentConfig clone()

Returns a copy of this configuration object.

toString

public String toString()

Display configuration values.

Overrides:

toString in class EnvironmentMutableConfig