public class EnvironmentConfig extends EnvironmentMutableConfig
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.
Most parameters are described by the parameter name String constants in
this class. These parameters can be specified or individually by calling
setConfigParam(java.lang.String, java.lang.String)
, through a Properties object passed to EnvironmentConfig(Properties)
, or via properties in the je.properties
files located in the environment home directory.
For example, an application can change the default btree node size with:
envConfig.setConfigParam(EnvironmentConfig.LOCK_TIMEOUT, "250 ms");
Some commonly used environment attributes have convenience setter/getter methods defined in this class. For example, to change the default lock timeout setting for an environment, the application can instead 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);
Parameter values are applied using this order of precedence:
However, a small number of parameters do not have string constants in
this class, and cannot be set using setConfigParam(java.lang.String, java.lang.String)
, a Properties
object, or the je.properties file. These parameters can only be changed
via the following setter methods:
setAllowCreate(boolean)
EnvironmentMutableConfig.setCacheMode(com.sleepycat.je.CacheMode)
setClassLoader(java.lang.ClassLoader)
setCustomStats(com.sleepycat.je.CustomStats)
EnvironmentMutableConfig.setExceptionListener(com.sleepycat.je.ExceptionListener)
setLoggingHandler(java.util.logging.Handler)
setNodeName(java.lang.String)
setRecoveryProgressListener(com.sleepycat.je.ProgressListener<com.sleepycat.je.RecoveryProgress>)
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:
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.
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.
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)
The maximum duration value is currently Integer.MAX_VALUE milliseconds. This translates to almost 25 days (2147483647999999 ns, 2147483647999 us, 2147483647 ms, 2147483 s, 35791 min, 596 h).
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.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
ADLER32_CHUNK_SIZE
By default, JE passes an entire log record to the Adler32 class for
checksumming.
|
static java.lang.String |
CHECKPOINTER_BYTES_INTERVAL
Ask the checkpointer to run every time we write this many bytes to the
log.
|
static java.lang.String |
CHECKPOINTER_DEADLOCK_RETRY
The number of times to retry a checkpoint if it runs into a deadlock.
|
static java.lang.String |
CHECKPOINTER_HIGH_PRIORITY
If true, the checkpointer uses more resources in order to complete the
checkpoint in a shorter time interval.
|
static java.lang.String |
CHECKPOINTER_WAKEUP_INTERVAL
The checkpointer wakeup interval in microseconds.
|
static java.lang.String |
CLEANER_ADJUST_UTILIZATION
Deprecated.
in JE 6.3. Adjustments are no longer needed because LN log
sizes have been stored in the Btree since JE 6.0.
|
static java.lang.String |
CLEANER_BACKGROUND_PROACTIVE_MIGRATION
Deprecated.
This parameter is ignored and proactive migration is no
longer supported due to its negative impact on eviction and
checkpointing. To reduce a cleaner backlog, configure more cleaner
threads.
|
static java.lang.String |
CLEANER_BYTES_INTERVAL
The cleaner checks disk utilization every time we write this many bytes
to the log.
|
static java.lang.String |
CLEANER_DEADLOCK_RETRY
The number of times to retry cleaning if a deadlock occurs.
|
static java.lang.String |
CLEANER_DETAIL_MAX_MEMORY_PERCENTAGE
Tracking of detailed cleaning information will use no more than this
percentage of the cache.
|
static java.lang.String |
CLEANER_EXPUNGE
If true (the default setting), the cleaner deletes log files after
successful cleaning.
|
static java.lang.String |
CLEANER_FETCH_OBSOLETE_SIZE
If true, the cleaner will fetch records to determine their size and more
accurately calculate log utilization.
|
static java.lang.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 java.lang.String |
CLEANER_FOREGROUND_PROACTIVE_MIGRATION
Deprecated.
This parameter is ignored and proactive migration is no
longer supported due to its negative impact on eviction and Btree
splits. To reduce a cleaner backlog, configure more cleaner threads.
|
static java.lang.String |
CLEANER_LAZY_MIGRATION
Deprecated.
This parameter is ignored and lazy migration is no longer
supported due to its negative impact on eviction and checkpointing.
To reduce a cleaner backlog, configure more cleaner threads.
|
static java.lang.String |
CLEANER_LOCK_TIMEOUT
The lock timeout for cleaner transactions in microseconds.
|
static java.lang.String |
CLEANER_LOOK_AHEAD_CACHE_SIZE
The look ahead cache size for cleaning in bytes.
|
static java.lang.String |
CLEANER_MAX_BATCH_FILES
Deprecated.
in 7.0. No longer used because the cleaner no longer has a
backlog.
|
static java.lang.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 java.lang.String |
CLEANER_MIN_FILE_UTILIZATION
A log file will be cleaned if its utilization percentage is below this
value, irrespective of total utilization.
|
static java.lang.String |
CLEANER_MIN_UTILIZATION
The cleaner will keep the total disk space utilization percentage above
this value.
|
static java.lang.String |
CLEANER_READ_SIZE
The read buffer size for cleaning.
|
static java.lang.String |
CLEANER_THREADS
The number of threads allocated by the cleaner for log file processing.
|
static java.lang.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 java.lang.String |
CLEANER_USE_DELETED_DIR
When
CLEANER_EXPUNGE is false, the CLEANER_USE_DELETED_DIR parameter determines whether successfully
cleaned files are moved to the "deleted" sub-directory. |
static java.lang.String |
CLEANER_WAKEUP_INTERVAL
The cleaner checks whether cleaning is needed if this interval elapses
without any writing, to handle the case where cleaning or checkpointing
is necessary to reclaim disk space, but writing has stopped.
|
static java.lang.String |
COMPRESSOR_DEADLOCK_RETRY
The number of times to retry a compression run if a deadlock occurs.
|
static java.lang.String |
COMPRESSOR_LOCK_TIMEOUT
The lock timeout for compressor transactions in microseconds.
|
static java.lang.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 java.lang.String |
COMPRESSOR_WAKEUP_INTERVAL
The compressor thread wakeup interval in microseconds.
|
static java.lang.String |
CONSOLE_LOGGING_LEVEL
Trace messages equal and above this level will be logged to the
console.
|
static java.lang.String |
DOS_PRODUCER_QUEUE_TIMEOUT
The timeout for Disk Ordered Scan producer thread queue offers in
milliseconds.
|
static java.lang.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 java.lang.String |
ENV_BACKGROUND_SLEEP_INTERVAL
The duration that JE background activities will sleep when the
ENV_BACKGROUND_WRITE_LIMIT or ENV_BACKGROUND_READ_LIMIT is
reached. |
static java.lang.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 java.lang.String |
ENV_CHECK_LEAKS
Debugging support: check leaked locks and txns at env close.
|
static java.lang.String |
ENV_DB_EVICTION
If true, enable eviction of metadata for closed databases.
|
static java.lang.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 java.lang.String |
ENV_EXPIRATION_ENABLED
If true (the default), expired data is filtered from queries and purged
by the cleaner.
|
static java.lang.String |
ENV_FAIR_LATCHES
If true, use latches instead of synchronized blocks to implement the
lock table and log write mutexes.
|
static java.lang.String |
ENV_FORCED_YIELD
Debugging support: call Thread.yield() at strategic points.
|
static java.lang.String |
ENV_IS_LOCKING
Configures the database environment for no locking.
|
static java.lang.String |
ENV_IS_TRANSACTIONAL
Configures the use of transactions.
|
static java.lang.String |
ENV_LATCH_TIMEOUT
The timeout for detecting internal latch timeouts, so that deadlocks can
be detected.
|
static java.lang.String |
ENV_READ_ONLY
Configures the database environment to be read-only, and any attempt to
modify a database will fail.
|
static java.lang.String |
ENV_RECOVERY_FORCE_CHECKPOINT
If true, a checkpoint is forced following recovery, even if the
log ends with a checkpoint.
|
static java.lang.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 java.lang.String |
ENV_RUN_CHECKPOINTER
If true, starts up the checkpointer thread.
|
static java.lang.String |
ENV_RUN_CLEANER
If true, starts up the cleaner thread.
|
static java.lang.String |
ENV_RUN_EVICTOR
If true, eviction is done by a pool of evictor threads, as well as being
done inline by application threads.
|
static java.lang.String |
ENV_RUN_IN_COMPRESSOR
If true, starts up the INCompressor thread.
|
static java.lang.String |
ENV_RUN_OFFHEAP_EVICTOR
If true, off-heap eviction is done by a pool of evictor threads, as well
as being done inline by application threads.
|
static java.lang.String |
ENV_RUN_VERIFIER
Whether to run the background verifier.
|
static java.lang.String |
ENV_TTL_CLOCK_TOLERANCE
The interval added to the system clock time for determining that a
record may have expired.
|
static java.lang.String |
EVICTOR_ALLOW_BIN_DELTAS
Allow Bottom Internal Nodes (BINs) to be written in a delta format
during eviction.
|
static java.lang.String |
EVICTOR_CORE_THREADS
The minimum number of threads in the eviction thread pool.
|
static java.lang.String |
EVICTOR_CRITICAL_PERCENTAGE
At this percentage over the allotted cache, critical eviction will
start.
|
static java.lang.String |
EVICTOR_DEADLOCK_RETRY
Deprecated.
as of JE 4.1, since the single evictor thread has
been replaced be a more robust thread pool.
|
static java.lang.String |
EVICTOR_EVICT_BYTES
When eviction occurs, the evictor will push memory usage to this number
of bytes below
MAX_MEMORY . |
static java.lang.String |
EVICTOR_FORCED_YIELD
Call Thread.yield() at each check for cache overflow.
|
static java.lang.String |
EVICTOR_KEEP_ALIVE
The duration that excess threads in the eviction thread pool will stay
idle; after this period, idle threads will terminate.
|
static java.lang.String |
EVICTOR_LRU_ONLY
Deprecated.
as of JE 6.0. This parameter is ignored by the new,
more efficient and more accurate evictor.
|
static java.lang.String |
EVICTOR_MAX_THREADS
The maximum number of threads in the eviction thread pool.
|
static java.lang.String |
EVICTOR_N_LRU_LISTS
The number of LRU lists in the main JE cache.
|
static java.lang.String |
EVICTOR_NODES_PER_SCAN
Deprecated.
as of JE 6.0. This parameter is ignored by the new, more
efficient and more accurate evictor.
|
static java.lang.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 java.lang.String |
FREE_DISK
A lower limit on the number of bytes of free space to maintain on a
volume and per JE Environment.
|
static java.lang.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 java.lang.String |
LOCK_DEADLOCK_DETECT
Whether to perform deadlock detection when a lock conflict occurs.
|
static java.lang.String |
LOCK_DEADLOCK_DETECT_DELAY
The delay after a lock conflict, before performing deadlock detection.
|
static java.lang.String |
LOCK_N_LOCK_TABLES
Number of Lock Tables.
|
static java.lang.String |
LOCK_OLD_LOCK_EXCEPTIONS
Deprecated.
since JE 6.5; has no effect, as if it were set to false.
|
static java.lang.String |
LOCK_TIMEOUT
Configures the default lock timeout.
|
static java.lang.String |
LOG_BUFFER_SIZE
The maximum starting size of a JE log buffer.
|
static java.lang.String |
LOG_CHECKSUM_READ
If true, perform a checksum check when reading entries from log.
|
static java.lang.String |
LOG_CHUNKED_NIO
Deprecated.
NIO is no longer used by JE and this parameter has no
effect.
|
static java.lang.String |
LOG_DETECT_FILE_DELETE
If true, periodically detect unexpected file deletions.
|
static java.lang.String |
LOG_DETECT_FILE_DELETE_INTERVAL
The interval used to check for unexpected file deletions.
|
static java.lang.String |
LOG_DIRECT_NIO
Deprecated.
NIO is no longer used by JE and this parameter has no
effect.
|
static java.lang.String |
LOG_FAULT_READ_SIZE
The buffer size for faulting in objects from disk, in bytes.
|
static java.lang.String |
LOG_FILE_CACHE_SIZE
The size of the file handle cache.
|
static java.lang.String |
LOG_FILE_MAX
The maximum size of each individual JE log file, in bytes.
|
static java.lang.String |
LOG_FLUSH_NO_SYNC_INTERVAL
The maximum time interval between committing a transaction with
NO_SYNC durability, and
making the transaction durable with respect to the file system. |
static java.lang.String |
LOG_FLUSH_SYNC_INTERVAL
The maximum time interval between committing a transaction with
NO_SYNC or WRITE_NO_SYNC durability,
and making the transaction durable with respect to the storage device. |
static java.lang.String |
LOG_FSYNC_TIME_LIMIT
If the time taken by an fsync exceeds this limit, a WARNING level
message is logged.
|
static java.lang.String |
LOG_FSYNC_TIMEOUT
The timeout limit for group file sync, in microseconds.
|
static java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.String |
LOG_MEM_ONLY
If true, operates in an in-memory test mode without flushing the log to
disk.
|
static java.lang.String |
LOG_N_DATA_DIRECTORIES
Deprecated.
as of 7.3. This feature is not known to provide benefits
beyond that of a simple RAID configuration, and will be removed in the
next release, which is slated for mid-April, 2017.
|
static java.lang.String |
LOG_NUM_BUFFERS
The number of JE log buffers.
|
static java.lang.String |
LOG_TOTAL_BUFFER_BYTES
The total memory taken by log buffers, in bytes.
|
static java.lang.String |
LOG_USE_NIO
Deprecated.
NIO is no longer used by JE and this parameter has no
effect.
|
static java.lang.String |
LOG_USE_ODSYNC
If true (default is false) O_DSYNC is used to open JE log files.
|
static java.lang.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 java.lang.String |
LOG_VERIFY_CHECKSUMS
If true, perform a checksum verification just before and after writing
to the log.
|
static java.lang.String |
LOG_WRITE_QUEUE_SIZE
The size of the Write Queue.
|
static java.lang.String |
MAX_DISK
An upper limit on the number of bytes used for data storage.
|
static java.lang.String |
MAX_MEMORY
Configures the JE main cache size in bytes.
|
static java.lang.String |
MAX_MEMORY_PERCENT
Configures the JE main cache size as a percentage of the JVM maximum
memory.
|
static java.lang.String |
MAX_OFF_HEAP_MEMORY
Configures the number of bytes to be used as a secondary, off-heap cache.
|
static java.lang.String |
NODE_DUP_TREE_MAX_ENTRIES
Deprecated.
this property no longer has any effect;
DatabaseConfig.setNodeMaxEntries(int) should be used instead. |
static java.lang.String |
NODE_MAX_ENTRIES
The maximum number of entries in an internal btree node.
|
static java.lang.String |
OFFHEAP_CHECKSUM
Can be used to add a checksum to each off-heap block when the block is
written, and validate the checksum when the block is read, for debugging
purposes.
|
static java.lang.String |
OFFHEAP_CORE_THREADS
The minimum number of threads in the off-heap eviction thread pool.
|
static java.lang.String |
OFFHEAP_EVICT_BYTES
The off-heap evictor will attempt to keep memory usage this number of
bytes below
MAX_OFF_HEAP_MEMORY . |
static java.lang.String |
OFFHEAP_KEEP_ALIVE
The duration that excess threads in the off-heap eviction thread pool
will stay idle; after this period, idle threads will terminate.
|
static java.lang.String |
OFFHEAP_MAX_THREADS
The maximum number of threads in the off-heap eviction thread pool.
|
static java.lang.String |
OFFHEAP_N_LRU_LISTS
The number of LRU lists in the off-heap JE cache.
|
static java.lang.String |
SHARED_CACHE
If true, the shared cache is used by this environment.
|
static java.lang.String |
STARTUP_DUMP_THRESHOLD
If environment startup exceeds this duration, startup statistics are
logged and can be found in the je.info file.
|
static java.lang.String |
STATS_COLLECT
If true collect and log statistics.
|
static java.lang.String |
STATS_COLLECT_INTERVAL
The duration of the statistics capture interval.
|
static java.lang.String |
STATS_FILE_DIRECTORY
The directory to save the statistics log file.
|
static java.lang.String |
STATS_FILE_ROW_COUNT
Log file maximum row count for Stat collection.
|
static java.lang.String |
STATS_MAX_FILES
Maximum number of statistics log files to retain.
|
static java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.String |
TREE_COMPACT_MAX_KEY_LENGTH
Specifies the maximum unprefixed key length for use in the compact
in-memory key representation.
|
static java.lang.String |
TREE_MAX_DELTA
Deprecated.
as of JE 6.0. The
TREE_BIN_DELTA param alone now
determines whether a delta is logged. |
static java.lang.String |
TREE_MAX_EMBEDDED_LN
The maximum size (in bytes) of a record's data portion that will cause
the record to be embedded in its parent LN.
|
static java.lang.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 java.lang.String |
TXN_DEADLOCK_STACK_TRACE
Set this parameter to true to add stacktrace information to deadlock
(lock timeout) exception messages.
|
static java.lang.String |
TXN_DUMP_LOCKS
Dump the lock table when a lock timeout is encountered, for debugging
assistance.
|
static java.lang.String |
TXN_DURABILITY
Configures the default durability associated with transactions.
|
static java.lang.String |
TXN_SERIALIZABLE_ISOLATION
Configures all transactions for this environment to have Serializable
(Degree 3) isolation.
|
static java.lang.String |
TXN_TIMEOUT
Configures the transaction timeout.
|
static java.lang.String |
VERIFY_BTREE
Whether the background verifier should perform Btree verification,
as if the
DbVerify utility were run. |
static java.lang.String |
VERIFY_BTREE_BATCH_DELAY
The delay between batches during
Btree
verification . |
static java.lang.String |
VERIFY_BTREE_BATCH_SIZE
The number of records verified per batch during
Btree verification . |
static java.lang.String |
VERIFY_DATA_RECORDS
Whether to verify data records (leaf nodes, or LNs) during Btree
verification.
|
static java.lang.String |
VERIFY_LOG
Whether the background verifier should verify checksums in the log,
as if the
DbVerifyLog utility were run. |
static java.lang.String |
VERIFY_LOG_READ_DELAY
The delay between reads during
log verification . |
static java.lang.String |
VERIFY_SCHEDULE
A crontab-format string indicating when to start the background
verifier.
|
static java.lang.String |
VERIFY_SECONDARIES
Whether to verify secondary index references during Btree verification.
|
Constructor and Description |
---|
EnvironmentConfig()
Creates an EnvironmentConfig initialized with the system default
settings.
|
EnvironmentConfig(java.util.Properties properties)
Creates an EnvironmentConfig which includes the properties specified in
the properties parameter.
|
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.
|
java.lang.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(java.util.concurrent.TimeUnit unit)
Returns the lock timeout setting.
|
java.util.logging.Handler |
getLoggingHandler()
Returns the custom java.util.logging.Handler specified by the
application.
|
java.lang.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()
A convenience method for getting the
SHARED_CACHE parameter. |
boolean |
getTransactional()
Returns true if the database environment is configured for transactions.
|
boolean |
getTxnSerializableIsolation()
A convenience method for getting
TXN_SERIALIZABLE_ISOLATION . |
long |
getTxnTimeout()
Deprecated.
as of 4.0, replaced by
getTxnTimeout(TimeUnit) . |
long |
getTxnTimeout(java.util.concurrent.TimeUnit unit)
A convenience method for getting
TXN_TIMEOUT . |
EnvironmentConfig |
setAllowCreate(boolean allowCreate)
If true, creates the database environment if it doesn't already exist.
|
EnvironmentConfig |
setClassLoader(java.lang.ClassLoader classLoader)
Configure the environment to use a specified ClassLoader for loading
user-supplied classes by name.
|
EnvironmentConfig |
setConfigParam(java.lang.String paramName,
java.lang.String value)
Set this configuration parameter.
|
EnvironmentConfig |
setCustomStats(CustomStats customStats)
Sets the custom statistics object.
|
EnvironmentConfig |
setLocking(boolean locking)
Convenience method for setting
ENV_IS_LOCKING . |
EnvironmentConfig |
setLockTimeout(long timeout)
Deprecated.
as of 4.0, replaced by
setLockTimeout(long,
TimeUnit) . |
EnvironmentConfig |
setLockTimeout(long timeout,
java.util.concurrent.TimeUnit unit)
Convenience method for setting
LOCK_TIMEOUT . |
EnvironmentConfig |
setLoggingHandler(java.util.logging.Handler handler)
Set a java.util.logging.Handler which will be used by all
java.util.logging.Loggers instantiated by this Environment.
|
EnvironmentConfig |
setNodeName(java.lang.String nodeName)
Sets the user defined nodeName for the Environment.
|
EnvironmentConfig |
setReadOnly(boolean readOnly)
Convenience method for setting
ENV_READ_ONLY . |
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)
A convenience method for setting the
SHARED_CACHE parameter. |
EnvironmentConfig |
setTransactional(boolean transactional)
Convenience method for setting
ENV_IS_TRANSACTIONAL . |
EnvironmentConfig |
setTxnSerializableIsolation(boolean txnSerializableIsolation)
A convenience method for setting
TXN_SERIALIZABLE_ISOLATION . |
EnvironmentConfig |
setTxnTimeout(long timeout)
Deprecated.
as of 4.0, replaced by
setTxnTimeout(long,
TimeUnit) . |
EnvironmentConfig |
setTxnTimeout(long timeout,
java.util.concurrent.TimeUnit unit)
A convenience method for setting
TXN_TIMEOUT . |
java.lang.String |
toString()
Display configuration values.
|
getCacheMode, getCachePercent, getCacheSize, getConfigParam, getDurability, getExceptionListener, getMaxDisk, getOffHeapCacheSize, getTxnNoSync, getTxnWriteNoSync, setCacheMode, setCachePercent, setCacheSize, setDurability, setExceptionListener, setMaxDisk, setOffHeapCacheSize, setTxnNoSync, setTxnWriteNoSync
public static final java.lang.String MAX_MEMORY
Either MAX_MEMORY or MAX_MEMORY_PERCENT may be used to configure the
cache size. When MAX_MEMORY is zero (its default value),
MAX_MEMORY_PERCENT determines the cache size. See
MAX_MEMORY_PERCENT
for more information.
When using MAX_MEMORY, take care to ensure that the overhead of the JVM does not leave less free space in the heap than intended. Some JVMs have more overhead than others, and some JVMs allocate their overhead within the specified heap size (the -Xmx value). To be sure that enough free space is available, use MAX_MEMORY_PERCENT rather than MAX_MEMORY.
When using the Oracle NoSQL DB product
Name | Type | Mutable | Default | Minimum | Maximum |
"je.maxMemory" | Long | Yes | 0 | -none- | -none- |
public static final java.lang.String MAX_MEMORY_PERCENT
The system will evict database objects when it comes within a prescribed margin of the limit.
By default, JE sets the cache size to:
(MAX_MEMORY_PERCENT * JVM maximum memory) / 100
where JVM maximum memory is specified by the JVM -Xmx flag. Note that
the actual heap size may be somewhat less, depending on JVM overheads.
The value used in the calculation above is the actual heap size as
returned by Runtime.maxMemory()
.
The above calculation applies when MAX_MEMORY
is zero, which
is its default value. Setting MAX_MEMORY to a non-zero value overrides
the percentage based calculation and sets the cache size explicitly.
The following details apply to setting the cache size to a percentage
of the JVM heap size byte size (this parameter) as well as to a byte
size (MAX_MEMORY
If SHARED_CACHE
is set to true, MAX_MEMORY and
MAX_MEMORY_PERCENT specify the total size of the shared cache, and
changing these parameters will change the size of the shared cache. New
environments that join the cache may alter the cache size if their
configuration uses a different cache size parameter.
The size of the cache is often directly proportional to operation
performance. See Cache
Statistics for information on understanding and monitoring the
cache. It is strongly recommended that the cache is large enough to
hold all INs. See DbCacheSize
for information on sizing the
cache.
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.
Note that log write buffers may be flushed to disk if the cache size is changed after the environment has been opened.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.maxMemoryPercent" | Integer | Yes | 60 | 1 | 90 |
public static final java.lang.String MAX_OFF_HEAP_MEMORY
CacheMode
. When the off-heap cache overflows, eviction
occurs there also according to the same algorithm.
The main cache is in the Java heap and consists primarily of the Java objects making up the in-memory Btree data structure. Btree objects are not serialized the main cache, so no object materialization is needed to access the Btree there. Access to records in the main cache is therefore very fast, but the main cache has drawbacks as well: 1) The larger the main cache, the more likely it is to have Java GC performance problems. 2) When the Java heap exceeds 32GB, the "compressed OOPs" setting no longer applies and less data will fit in the same amount of memory. For these reasons, JE applications often configure a heap of 32GB or less, and a main cache that is significantly less than 32GB, leaving any additional machine memory for use by the file system cache.
The use of the file system cache has performance benefits, but also has its own drawbacks: 1) There is a significant redundancy between the main cache and the file system cache because all data and Btree information that is logged (written) by JE appears in the file system and may also appear in the main cache. 2) It is not possible for dirty Btree information to be placed in the file system cache without logging it, this logging may be otherwise unnecessary, and the logging creates additional work for the JE cleaner; in other words, the size of the main cache alone determines the maximum size of the in-memory "dirty set".
The off-heap cache is stored outside the Java heap using a native platform memory allocator. The current implementation relies on internals that are specific to the Oracle and IBM JDKs; however, a memory allocator interface that can be implemented for other situations is being considered for a future release. Records and Btree objects are serialized when they are placed in the off-heap cache, and they must be materialized when they are moved back to the main cache in order to access them. This serialization and materialization adds some CPU overhead and thread contention, as compared to accessing data directly in the main cache. The off-heap cache can contain dirty Btree information, so it can be used to increase the maximum size of the in-memory "dirty set".
NOTE: If an off-heap cache is configured but cannot be used because
that native allocator is not available in the JDK that is used, an
IllegalStateException
will be thrown by the Environment
or ReplicatedEnvironment
constructor. In
the current release, this means that the sun.misc.Unsafe
class
must contain the allocateMemory
method and related methods, as
defined in the Oracle JDK.
When configuring an off-heap cache you can think of the performance trade-offs in two ways. First, if the off-heap cache is considered to be a replacement for the file system cache, the serialization and materialization overhead is not increased. In this case, the use of the off-heap cache is clearly beneficial, and using the off-heap cache "instead of" the file system cache is normally recommended. Second, the off-heap cache can be used along with a main cache that is reduced in size in order to compensate for Java GC problems. In this case, the trade-off is between the additional serialization, materialization and contention overheads of the off-heap cache, as compared to the Java GC overhead.
When dividing up available memory for the JVM heap, the off-heap cache,
and for other uses, please be aware that the file system cache and the
off-heap cache are different in one important respect. The file system
cache automatically shrinks when memory is needed by the OS or other
processes, while the off-heap cache does not. Therefore, it is best to
be conservative about leaving memory free for other uses, and it is not
a good idea to size the off-heap cache such that all machine memory will
be allocated. If off-heap allocations or other allocations fail because
there is no available memory, the process is likely to die without any
exception being thrown. In one test on Linux, for example, the process
was killed abruptly by the OS and the only indication of the problem was
the following shown by dmesg
.
Out of memory: Kill process 28768 (java) score 974 or sacrifice child Killed process 28768 (java) total-vm:278255336kB, anon-rss:257274420kB, file-rss:0kB
WARNING: Although this configuration property is mutable, it cannot be
changed from zero to non-zero, or non-zero to zero. In other words, the
size of the off-heap cache can be changed after initially configuring a
non-zero size, but the off-heap cache cannot be turned on and off
dynamically. An attempt to do so will cause an IllegalArgumentException
to be thrown by the Environment
or
ReplicatedEnvironment
constructor.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.maxOffHeapMemory" | Long | Yes | 0 | 0 | -none- |
public static final java.lang.String SHARED_CACHE
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.
Name | Type | Mutable | Default |
"je.sharedCache" | Boolean | No | false |
public static final java.lang.String MAX_DISK
FREE_DISK
to define the storage limit. If the limit is
exceeded, write operations will be prohibited.
If set to zero (the default), no usage limit is enforced, meaning that
all space on the storage volume, minus FREE_DISK
, may be used.
If MAX_DISK is non-zero, FREE_DISK is subtracted from MAX_DISK to
determine the usage threshold for prohibiting write operations. If
multiple JE environments share the same storage volume, setting MAX_DISK
to a non-zero value is strongly recommended.
Note: An exception to the rule above is
when MAX_DISK is less than or equal to 10GB and FREE_DISK is not
explicitly specified. See FREE_DISK
more information.
DiskLimitException
.
DiskLimitException extends OperationFailureException
and
will invalidate the transaction, but will not invalidate the
environment. Read operations may continue even when write operations
are prohibited.
Environment.checkpoint(com.sleepycat.je.CheckpointConfig)
, Environment.sync()
and
Database.sync()
will throw DiskLimitException.
Environment.close()
may throw DiskLimitException when a final
checkpoint is performed. However, the environment will be properly
closed in other respects.
recommended
.
InsufficientAcksException
or
InsufficientReplicasException
will be
thrown if the ack requirements
are not met.
JE uses a log structured storage system where data files often become
gradually obsolete over time (see CLEANER_MIN_UTILIZATION
). The
JE cleaner is responsible for reclaiming obsolete space by cleaning and
deleting data files. In a standalone (non-HA) environment, data files
are normally deleted quickly after being cleaned, but may be reserved
and protected temporarily by a DbBackup
or
DiskOrderedCursor
. These reserved files will be deleted as soon
as they are no longer protected.
In an HA environment, JE will retain as many reserved files as possible to support replication to nodes that are out of contact. All cleaned files are reserved (not deleted) until approaching a disk limit, at which time they are deleted, as long as they are not protected. Reserved files are protected when they are needed for replication to active nodes or for feeding an active network restore.
For more information on reserved and protected data files, see
EnvironmentStats.getActiveLogSize()
,
EnvironmentStats.getReservedLogSize()
,
EnvironmentStats.getProtectedLogSize()
,
EnvironmentStats.getProtectedLogSizeMap()
,
EnvironmentStats.getAvailableLogSize()
and
EnvironmentStats.getTotalLogSize()
.
When multiple JE environments share the same storage volume, the FREE_DISK amount will be maintained for each environment. The following scenario illustrates use of a single shared volume with capacity 300GB:
Each JE environment will use no more than 95GB each, so at least 10GB will remain free overall. In other words, if both JE environments reach their threshold and write operations are prohibited, each JE environment will have 5GB of free space for recovery (10GB total).
On the other hand, when an external service is also consuming disk space and its usage of disk space is variable over time, the situation is more complex and JE cannot always guarantee that FREE_DISK is honored. The following scenario includes multiple JE environments as well an external service, all sharing a 300GB volume.
Assuming that the external service stays within its 50GB limit then, as the previous example, each JE environment will normally use no more than 95GB each, and at least 10GB will remain free overall. However, if the external service exceeds its threshold, JE will make a best effort to prohibit write operations in order to honor the FREE_DISK limit, but this is not always possible, as illustrated by the following sequence of events:
Name | Type | Mutable | Default | Minimum | Maximum |
"je.maxDisk" | Long | Yes | 0 | 0 | -none- |
FREE_DISK
,
EnvironmentMutableConfig.setMaxDisk(long)
,
EnvironmentMutableConfig.getMaxDisk()
,
Constant Field Valuespublic static final java.lang.String FREE_DISK
MAX_DISK
to define
the storage limit. If the limit is exceeded, write operations will be
prohibited.
The default FREE_DISK value is 5GB. This value is designed to be large enough to allow manual recovery after exceeding a disk threshold.
If FREE_DISK is set to zero, no free space limit is enforced. This is not recommended, since manual recovery may be very difficult or impossible when the volume is completely full.
If non-zero, this parameter is used in two ways.
MAX_DISK
for more information.
Note that this subtraction could make testing inconvenient when a small value is specified for MAX_DISK and FREE_DISK is not also specified. For example, if MAX_DISK is 1GB and FREE_DISK is 5G (its default value), then no writing would be allowed (MAX_DISK minus FREE_DISK is negative 4G). To address this, the subtraction is performed only if one of two conditions is met:
Name | Type | Mutable | Default | Minimum | Maximum |
"je.freeDisk" | Long | Yes | 5,368,709,120 (5GB) | -none- | -none- |
MAX_DISK
,
Constant Field Valuespublic static final java.lang.String ENV_RECOVERY_FORCE_CHECKPOINT
Name | Type | Mutable | Default |
"je.env.recoveryForceCheckpoint" | Boolean | No | false |
public static final java.lang.String ENV_RECOVERY_FORCE_NEW_FILE
As of JE 6.3, the use of this parameter is unnecessary except in special cases. See the "Restoring from a backup" section in the DbBackup javadoc for more information.
Name | Type | Mutable | Default |
"je.env.recoveryForceNewFile" | Boolean | No | false |
public static final java.lang.String HALT_ON_COMMIT_AFTER_CHECKSUMEXCEPTION
Name | Type | Mutable | Default |
"je.haltOnCommitAfterChecksumException" | Boolean | No | false |
public static final java.lang.String ENV_RUN_IN_COMPRESSOR
Name | Type | Mutable | Default |
"je.env.runINCompressor" | Boolean | Yes | true |
public static final java.lang.String ENV_RUN_CHECKPOINTER
Name | Type | Mutable | Default |
"je.env.runCheckpointer" | Boolean | Yes | true |
public static final java.lang.String ENV_RUN_CLEANER
Name | Type | Mutable | Default |
"je.env.runCleaner" | Boolean | Yes | true |
public static final java.lang.String ENV_RUN_EVICTOR
EVICTOR_CORE_THREADS
and
EVICTOR_MAX_THREADS
.
Name | Type | Mutable | Default |
"je.env.runEvictor" | Boolean | Yes | true |
public static final java.lang.String ENV_RUN_OFFHEAP_EVICTOR
OFFHEAP_CORE_THREADS
and OFFHEAP_MAX_THREADS
.
Name | Type | Mutable | Default |
"je.env.runOffHeapEvictor" | Boolean | Yes | true |
public static final java.lang.String ENV_BACKGROUND_READ_LIMIT
Name | Type | Mutable | Default | Minimum | Maximum |
"je.env.backgroundReadLimit" | Integer | Yes | 0 | 0 | -none- |
public static final java.lang.String ENV_BACKGROUND_WRITE_LIMIT
Name | Type | Mutable | Default | Minimum | Maximum |
"je.env.backgroundWriteLimit" | Integer | Yes | 0 | 0 | -none- |
public static final java.lang.String ENV_BACKGROUND_SLEEP_INTERVAL
ENV_BACKGROUND_WRITE_LIMIT
or ENV_BACKGROUND_READ_LIMIT
is
reached. If ENV_BACKGROUND_WRITE_LIMIT
and ENV_BACKGROUND_READ_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 |
public static final java.lang.String ENV_CHECK_LEAKS
Name | Type | Mutable | Default |
"je.env.checkLeaks" | Boolean | No | true |
public static final java.lang.String ENV_FORCED_YIELD
Name | Type | Mutable | Default |
"je.env.forcedYield" | Boolean | No | false |
public static final java.lang.String ENV_IS_TRANSACTIONAL
This should be set to true when transactional guarantees such as atomicity of multiple operations and durability are important.
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 |
setTransactional(boolean)
,
Constant Field Valuespublic static final java.lang.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.
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.
Name | Type | Mutable | Default |
"je.env.isLocking" | Boolean | No | true |
setLocking(boolean)
,
Constant Field Valuespublic static final java.lang.String ENV_READ_ONLY
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.
DatabaseConfig.setReadOnly(boolean)
.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.
Name | Type | Mutable | Default |
"je.env.isReadOnly" | Boolean | No | false |
setReadOnly(boolean)
,
Constant Field Valuespublic static final java.lang.String ENV_FAIR_LATCHES
Name | Type | Mutable | Default |
"je.env.fairLatches" | Boolean | No | false |
public static final java.lang.String ENV_LATCH_TIMEOUT
EnvironmentFailureException
is thrown.Most applications should not change this parameter. The default value, 5 minutes, should be much longer than a latch is ever held.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.env.latchTimeout" | Duration | No | 5 min | 1 ms | -none- |
public static final java.lang.String ENV_TTL_CLOCK_TOLERANCE
For example, say a record expires and then the clock is moved back by one hour to correct a daylight savings time error. Because the LN and BIN slot for an expired record are purged separately (see Time-To_live), in this case the LN was purged but the BIN slot was not purged. When accessing the record's key via the BIN slot, it will appear that it is not expired. But then when accessing the the data, the LN will not be accessible. Normally this would be considered a fatal integrity error, but since the record will expire within the 2 hour limit, it is simply treated as an expired record.
Most applications should not change this parameter. The default value, two hours, is enough to account for minor clock adjustments or accidentally setting the clock one hour off.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.env.ttlClockTolerance" | Duration | No | 2 h | 1 ms | -none- |
public static final java.lang.String ENV_EXPIRATION_ENABLED
WARNING: Disabling expiration is intended for special-purpose access for data recovery only. When this parameter is set to false, records that have expired may or may not have been purged, so they may or may not be accessible. In addition, it is possible for the key and data of a record to expire independently, so the key may be accessible (if the data is not requested by the read operation), while the record will appear to be deleted when the data is requested. The same thing is true of primary and secondary records, which are also purged independently. A record may be accessible by primary key but not secondary key, and vice-versa.
Name | Type | Mutable | Default |
"je.env.expirationEnabled" | Boolean | yes | true |
public static final java.lang.String ENV_DB_EVICTION
This param is unlikely to be needed for tuning, but is sometimes useful for debugging and testing.
Name | Type | Mutable | Default |
"je.env.dbEviction" | Boolean | No | true |
public static final java.lang.String ENV_DUP_CONVERT_PRELOAD_ALL
Name | Type | Mutable | Default |
"je.env.dupConvertPreloadAll" | Boolean | No | true |
public static final java.lang.String ADLER32_CHUNK_SIZE
Name | Type | Mutable | Default | Minimum | Maximum |
"je.adler32.chunkSize" | Integer | Yes | 0 | 0 | 1048576 (1M) |
public static final java.lang.String LOG_TOTAL_BUFFER_BYTES
Name | Type | Mutable | Default | Minimum | Maximum |
"je.log.totalBufferBytes" | Long | No | 0 | 6144L | -none- |
public static final java.lang.String LOG_NUM_BUFFERS
Name | Type | Mutable | Default | Minimum | Maximum |
"je.log.numBuffers" | Integer | No | 3 | 2 | -none- |
public static final java.lang.String LOG_BUFFER_SIZE
Name | Type | Mutable | Default | Minimum | Maximum |
"je.log.bufferSize" | Integer | No | 1048576 (1M) | 1024 (1K) | -none- |
public static final java.lang.String LOG_FAULT_READ_SIZE
Name | Type | Mutable | Default | Minimum | Maximum |
"je.log.faultReadSize" | Integer | No | 2048 (2K) | 32 | -none- |
public static final java.lang.String LOG_ITERATOR_READ_SIZE
Name | Type | Mutable | Default | Minimum | Maximum |
"je.log.iteratorReadSize" | Integer | No | 8192 (8K) | 128 | -none- |
public static final java.lang.String LOG_ITERATOR_MAX_SIZE
Name | Type | Mutable | Default | Minimum | Maximum |
"je.log.iteratorMaxSize" | Integer | No | 16777216 (16M) | 128 | -none- |
public static final java.lang.String LOG_FILE_MAX
Name | Type | Mutable | Default | Minimum | Maximum |
"je.log.fileMax" | Long | No | 10000000 (10M) | 1000000 (1M) | 1073741824 (1G) |
public static final java.lang.String LOG_N_DATA_DIRECTORIES
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 |
public static final java.lang.String LOG_CHECKSUM_READ
Name | Type | Mutable | Default |
"je.log.checksumRead" | Boolean | No | true |
public static final java.lang.String LOG_VERIFY_CHECKSUMS
Name | Type | Mutable | Default |
"je.log.verifyChecksums" | Boolean | No | false |
public static final java.lang.String LOG_MEM_ONLY
Name | Type | Mutable | Default |
"je.log.memOnly" | Boolean | No | false |
public static final java.lang.String LOG_FILE_CACHE_SIZE
Name | Type | Mutable | Default | Minimum | Maximum |
"je.log.fileCacheSize" | Integer | No | 100 | 3 | -none- |
public static final java.lang.String LOG_DETECT_FILE_DELETE
EnvironmentFailureException
.
Name | Type | Mutable | Default |
"je.log.detectFileDelete" | Boolean | No | true |
public static final java.lang.String LOG_DETECT_FILE_DELETE_INTERVAL
Name | Type | Mutable | Default | Minimum | Maximum |
"je.log.detectFileDeleteInterval" | Duration | No | 1000 ms | 1 ms | none |
public static final java.lang.String LOG_FSYNC_TIMEOUT
Name | Type | Mutable | Default | Minimum | Maximum |
"je.log.fsyncTimeout" | Duration | No | 500 ms | 10 ms | 24 d |
public static final java.lang.String LOG_FSYNC_TIME_LIMIT
Name | Type | Mutable | Default | Minimum | Maximum |
"je.log.fsyncTimeLimit" | Duration | No | 5 s | zero | 30 s |
EnvironmentStats.getFSyncMaxTime()
,
Time Duration
Properties,
Constant Field Valuespublic static final java.lang.String LOG_GROUP_COMMIT_INTERVAL
Name | Type | Mutable | Default | Minimum | Maximum |
"je.log.groupCommitInterval" | Duration | No | 0 | 0 | none |
LOG_GROUP_COMMIT_THRESHOLD
,
Constant Field Valuespublic static final java.lang.String LOG_GROUP_COMMIT_THRESHOLD
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- |
LOG_GROUP_COMMIT_INTERVAL
,
Constant Field Valuespublic static final java.lang.String LOG_FLUSH_SYNC_INTERVAL
NO_SYNC
or WRITE_NO_SYNC
durability,
and making the transaction durable with respect to the storage device.
To provide this guarantee, a JE background thread is used to flush any
data buffered by JE to the file system, and also perform an fsync to
force any data buffered by the file system to the storage device. If
this parameter is set to zero, this JE background task is disabled and
no such guarantee is provided.
Separately, the LOG_FLUSH_NO_SYNC_INTERVAL
flushing provides a
guarantee that data is periodically flushed to the file system. To guard
against data loss due to an OS crash (and to improve performance) we
recommend that the file system is configured to periodically flush dirty
pages to the storage device. This parameter, LOG_FLUSH_SYNC_INTERVAL
, provides a fallback for flushing to the
storage device, in case the file system is not adequately configured.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.log.flushSyncInterval" | Duration | Yes | 20 s | 0 | -none- |
public static final java.lang.String LOG_FLUSH_NO_SYNC_INTERVAL
NO_SYNC
durability, and
making the transaction durable with respect to the file system. To
provide this guarantee, a JE background thread is used to flush any data
buffered by JE to the file system. If this parameter is set to zero,
this JE background task is disabled and no such guarantee is provided.
Frequent periodic flushing to the file system provides improved
durability for NO_SYNC transactions. Without this flushing, if
application write operations stop, then some number of NO_SYNC
transactions would be left in JE memory buffers and would be lost in the
event of a crash. For HA applications, this flushing reduces the
possibility of RollbackProhibitedException
.
Note that periodic flushing reduces the time window where a crash can
cause transaction loss and RollbackProhibitedException
, but the
window cannot be closed completely when using NO_SYNC durability.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.log.flushNoSyncInterval" | Duration | Yes | 5 s | 0 | -none- |
public static final java.lang.String LOG_USE_ODSYNC
Name | Type | Mutable | Default |
"je.log.useODSYNC" | Boolean | No | false |
public static final java.lang.String LOG_USE_NIO
public static final java.lang.String LOG_USE_WRITE_QUEUE
Name | Type | Mutable | Default |
"je.log.useWriteQueue" | Boolean | No | true |
public static final java.lang.String LOG_WRITE_QUEUE_SIZE
Name | Type | Mutable | Default | Minimum | Maximum |
"je.log.writeQueueSize" | Integer | No | 1MB | 4KB | 32MB- |
public static final java.lang.String LOG_DIRECT_NIO
public static final java.lang.String LOG_CHUNKED_NIO
public static final java.lang.String ENV_RUN_VERIFIER
If true (the default), the verifier runs according to the schedule
given by VERIFY_SCHEDULE
. Each time the verifier runs, it
performs checksum verification if the VERIFY_LOG
setting is
true and performs Btree verification if the VERIFY_BTREE
setting is true.
When corruption is detected, the Environment will be invalidated and an
EnvironmentFailureException will be thrown. Applications catching this
exception can call the new EnvironmentFailureException.isCorrupted()
method to determine whether
corruption was detected.
If isCorrupted returns true, a full restore (an HA NetworkRestore
or restore from backup)
should be performed to avoid further problems. The advantage of
performing verification frequently is that a problem may be detected
sooner than it would be otherwise. For HA applications, this means that
the network restore can be done while the other nodes in the group are
up, minimizing exposure to additional failures.
When index corruption is detected, the environment is not invalidated.
Instead, the corrupt index (secondary database) is marked as corrupt
in memory and a warning message is logged. All subsequent access to the
index will throw SecondaryIntegrityException
. To correct the
problem, the application may perform a full restore or rebuild the
corrupt index.
Name | Type | Mutable | Default |
"je.env.runVerifier" | Boolean | Yes | true |
public static final java.lang.String VERIFY_SCHEDULE
See https://en.wikipedia.org/wiki/Cron#Configuration_file Note that times and dates are specified in local time, not UTC time.
The data verifier will run at most once per scheduled interval. If the complete verification (log verification followed by Btree verification) takes longer than the scheduled interval, then the next verification will start at the next increment of the interval. For example, if the default schedule is used (one per day at midnight), and verification takes 25 hours, then verification will occur once every two days (48 hours), starting at midnight.
Name | Type | Mutable | Default |
"je.env.verifySchedule" | String | Yes | "0 0 * * * (run once a day at midnight, local time)" |
public static final java.lang.String VERIFY_LOG
DbVerifyLog
utility were run.
If true, the entire log is read sequentially and verified. The size of the read buffer is determined by LOG_ITERATOR_READ_SIZE.
Name | Type | Mutable | Default |
"je.env.verifyLog" | Boolean | Yes | true |
public static final java.lang.String VERIFY_LOG_READ_DELAY
log verification
.
A delay between reads is needed to allow other JE components, such as
HA, to make timely progress.
A 100ms delay, the default value, with the read buffer size 131072, i.e. 128K, for a 1GB file, the total delay time is about 13 minutes.
This parameter applies only to the background
verifier
. It does not apply to use of DbVerifyLog
.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.env.verifyLogReadDelay" | Duration | Yes | 100 ms | 0 ms | 10 s |
public static final java.lang.String VERIFY_BTREE
DbVerify
utility were run.
If true, the Btree of all databases, external and internal, is
verified. The in-memory cache is used for verification and internal
data structures are checked. References to data records (log sequence
numbers, or LSNs) are checked to ensure they do not refer to deleted
files -- this is the most common type of corruption. Additional
checks are performed, depending on the settings for VERIFY_SECONDARIES
and VERIFY_DATA_RECORDS
.
Name | Type | Mutable | Default |
"je.env.verifyBtree" | Boolean | Yes | true |
public static final java.lang.String VERIFY_SECONDARIES
An index record contains a reference to a primary key, and the verification involves checking that a record for the primary key exists.
Note that secondary index references are verified only for each
SecondaryDatabase
(and SecondaryIndex
) that is currently
open. The relationship between a secondary and primary database is not
stored persistently, so JE is not aware of the relationship unless the
secondary database has been opened by the application.
Name | Type | Mutable | Default |
"je.env.verifySecondaries" | Boolean | Yes | true |
public static final java.lang.String VERIFY_DATA_RECORDS
Regardless of this parameter's value, the Btree reference to the data record (the log sequence number, or LSN) is checked to ensure that it doesn't refer to a file that has been deleted by the JE cleaner -- this sort of "dangling reference" is the most common type of corruption. If this parameter value is true, the LN is additionally fetched from disk (if not in cache) to verify that the LSN refers to a valid log entry. Because LNs are often not cached, this can cause expensive random IO, and the default value for this parameter is false for this reason. Some applications may choose to set this parameter to true, for example, when using a storage device with fast random IO (an SSD).
Note that Btree internal nodes (INs) are always fetched from disk during verification, if they are not in cache, and this can result in random IO. Verification was implemented with the assumption that most INs will be in cache.
Name | Type | Mutable | Default |
"je.env.verifyDataRecords" | Boolean | Yes | false |
public static final java.lang.String VERIFY_BTREE_BATCH_SIZE
Btree verification
. In order to give database remove/truncate the
opportunity to execute, records are verified in batches and there is
a delay
between batches.
This parameter applies only to the background
verifier
. It does not apply to use of DbVerify
.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.env.verifyBtreeBatchSize" | Integer | Yes | 1000 | 1 | 10000 |
public static final java.lang.String VERIFY_BTREE_BATCH_DELAY
Btree
verification
. In order to give database remove/truncate the
opportunity to execute, records are verified in batches
and there is a delay between batches.
A 10ms delay, the default value, should be enough to allow other threads to run. A large value, for example 1s, would result in a total delay of 28 hours when verifying 100m records or 100k batches.
This parameter applies only to the background
verifier
. It does not apply to use of DbVerify
.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.env.verifyBtreeBatchDelay" | Duration | Yes | 10 ms | 0 ms | 10 s |
public static final java.lang.String NODE_MAX_ENTRIES
Name | Type | Mutable | Default | Minimum | Maximum |
"je.nodeMaxEntries" | Integer | No | 128 | 4 | 32767 (32K) |
public static final java.lang.String NODE_DUP_TREE_MAX_ENTRIES
DatabaseConfig.setNodeMaxEntries(int)
should be used instead.public static final java.lang.String TREE_MAX_EMBEDDED_LN
Normally, records (key-value pairs) are stored on disk as individual byte sequences called LNs (leaf nodes) and they are accessed via a Btree. The nodes of the Btree are called INs (Internal Nodes) and the INs at the bottom layer of the Btree are called BINs (Bottom Internal Nodes). Conceptually, each BIN contains an array of slots. A slot represents an associated data record. Among other things, it stores the key of the record and the most recent disk address of that record. Records and INs share the disk space (are stored in the same kind of files), but LNs are stored separately from BINs, i.e., there is no clustering or co-location of a BIN and its child LNs.
With embedded LNs, a whole record may be stored inside a BIN (i.e., a BIN slot may contain both the key and the data portion of a record). Specifically, a record will be "embedded" if the size (in bytes) of its data portion is less than or equal to the value of the TREE_MAX_EMBEDDED_LN configuration parameter. The decision to embed a record or not is taken on a record-by-record basis. As a result, a BIN may contain both embedded and non-embedded records. The "embeddedness" of a record is a dynamic property: a size-changing update may turn a non-embedded record to an embedded one or vice-versa.
Notice that even though a record may be embedded, when the record is inserted, updated, or deleted an LN for that record is still generated and written to disk. This is because LNs also act as log records, which are needed during recovery and/or transaction abort to undo/redo operations that are/are-not currently reflected in the BINs. However, during normal processing, these LNs will never be fetched from disk.
Obviously, embedding records has the performance advantage that no extra disk read is needed to fetch the record data (i.e., the LN) during read operations. This is especially true for operations like cursor scans and for random searches within key ranges whose containing BINs can fit in the JE cache (in other words when there is locality of reference). Furthermore, embedded records do not need to be migrated during cleaning; they are considered obsolete by default, because they will never be needed again after their containing log file is deleted. This makes cleaning faster, and more importantly, avoids the dirtying of the parent BINs, which would otherwise cause even more cleaning later.
On the other hand, embedded LNs make the BINs larger, which can lead to more cache eviction of BINs and the associated performance problems. When eviction does occur, performance can deteriorate as the size of the data portion of the records grows. This is especially true for insertion-only workloads. Therefore, increasing the value of TREE_MAX_EMBEDDED_LN beyond the default value of 16 bytes should be done "carefully": by considering the kind of workloads that will be run against BDB-JE and their relative importance and expected response times, and by running performance tests with both embedded and non-embedded LNs.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.tree.maxEmbeddedLN" | Integer | No | 16 | 0 | Integer.MAX_VALUE |
public static final java.lang.String TREE_MAX_DELTA
TREE_BIN_DELTA
param alone now
determines whether a delta is logged.public static final java.lang.String TREE_BIN_DELTA
Name | Type | Mutable | Default | Minimum | Maximum |
"je.tree.binDelta" | Integer | No | 25 | 0 | 75 |
public static final java.lang.String TREE_MIN_MEMORY
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.
This param is only likely to be needed for tuning of Environments with extremely small cache sizes. It is sometimes also useful for debugging and testing.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.tree.minMemory" | Long | Yes | 512000 (500K) | 51200 (50K) | -none- |
public static final java.lang.String TREE_COMPACT_MAX_KEY_LENGTH
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.
TREE_COMPACT_MAX_KEY_LENGTH
).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:
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 |
public static final java.lang.String COMPRESSOR_WAKEUP_INTERVAL
Name | Type | Mutable | Default | Minimum | Maximum |
"je.compressor.wakeupInterval" | Duration | No | 5 s | 1 s | 75 min |
public static final java.lang.String COMPRESSOR_DEADLOCK_RETRY
Name | Type | Mutable | Default | Minimum | Maximum |
"je.compressor.deadlockRetry" | Integer | No | 3 | 0 | -none- |
public static final java.lang.String COMPRESSOR_LOCK_TIMEOUT
Name | Type | Mutable | Default | Minimum | Maximum |
"je.compressor.lockTimeout" | Duration | No | 500 ms | 0 | 75 min |
public static final java.lang.String COMPRESSOR_PURGE_ROOT
public static final java.lang.String EVICTOR_EVICT_BYTES
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.
This parameter impacts how often background evictor threads are awoken as well as the size of latency spikes caused by critical eviction.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.evictor.evictBytes" | Long | No | 524288 (512K) | 1024 (1K) | -none- |
public static final java.lang.String EVICTOR_NODES_PER_SCAN
public static final java.lang.String EVICTOR_CRITICAL_PERCENTAGE
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 |
public static final java.lang.String EVICTOR_DEADLOCK_RETRY
public static final java.lang.String EVICTOR_LRU_ONLY
public static final java.lang.String EVICTOR_N_LRU_LISTS
Ideally, all nodes managed by an LRU eviction policy should appear in a single LRU list, ordered by the "hotness" of each node. However, such a list is accessed very frequently by multiple threads, and can become a synchronization bottleneck. To avoid this problem, the evictor can employ multiple LRU lists. The nLRULists parameter specifies the number of LRU lists to be used. Increasing the number of LRU lists alleviates any potential synchronization bottleneck, but it also decreases the quality of the LRU approximation.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.evictor.nLRULists" | Integer | No | 4 | 1 | 32 |
public static final java.lang.String EVICTOR_FORCED_YIELD
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.
This param is unlikely to be needed for tuning, but is sometimes useful for debugging and testing.
Name | Type | Mutable | Default |
"je.evictor.forcedYield" | Boolean | No | false |
public static final java.lang.String EVICTOR_CORE_THREADS
These threads help keep memory usage within cache bounds, offloading work from application threads.
EVICTOR_CORE_THREADS
, EVICTOR_MAX_THREADS
and EVICTOR_KEEP_ALIVE
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 |
public static final java.lang.String EVICTOR_MAX_THREADS
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 EVICTOR_KEEP_ALIVE
.
EVICTOR_CORE_THREADS
, EVICTOR_MAX_THREADS
and EVICTOR_KEEP_ALIVE
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 |
public static final java.lang.String EVICTOR_KEEP_ALIVE
EVICTOR_CORE_THREADS
, EVICTOR_MAX_THREADS
and EVICTOR_KEEP_ALIVE
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 |
public static final java.lang.String EVICTOR_ALLOW_BIN_DELTAS
This param is unlikely to be needed for tuning, but is sometimes useful for debugging and testing.
Name | Type | Mutable | Default |
"je.evictor.allowBinDeltas" | Boolean | No | true |
public static final java.lang.String OFFHEAP_EVICT_BYTES
MAX_OFF_HEAP_MEMORY
.
If this value is too small, memory usage may exceed the maximum and then "critical eviction" is needed, which will increase operation latency in the application threads.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.offHeap.evictBytes" | Long | No | 52428800 (50MB) | 1024 (1K) | -none- |
public static final java.lang.String OFFHEAP_N_LRU_LISTS
Ideally, all nodes managed by an LRU eviction policy should appear in a single LRU list, ordered by the "hotness" of each node. However, such a list is accessed very frequently by multiple threads, and can become a synchronization bottleneck. To avoid this problem, the evictor can employ multiple LRU lists. The nLRULists parameter specifies the number of LRU lists to be used. Increasing the number of LRU lists alleviates any potential synchronization bottleneck, but it also decreases the quality of the LRU approximation.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.evictor.nLRULists" | Integer | No | 4 | 1 | 32 |
public static final java.lang.String OFFHEAP_CHECKSUM
Name | Type | Mutable | Default |
"je.offHeap.checksum" | Boolean | No | false |
public static final java.lang.String OFFHEAP_CORE_THREADS
These threads help keep memory usage within cache bounds, offloading work from application threads.
OFFHEAP_CORE_THREADS
, OFFHEAP_MAX_THREADS
and OFFHEAP_KEEP_ALIVE
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.offHeap.coreThreads" | Integer | yes | 1 | 0 | Integer.MAX_VALUE |
public static final java.lang.String OFFHEAP_MAX_THREADS
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 OFFHEAP_KEEP_ALIVE
.
If the number of threads is too small, memory usage may exceed the maximum and then "critical eviction" is needed, which will increase operation latency in the application threads.
OFFHEAP_CORE_THREADS
, OFFHEAP_MAX_THREADS
and OFFHEAP_KEEP_ALIVE
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.offHeap.maxThreads" | Integer | yes | 3 | 1 | Integer.MAX_VALUE |
public static final java.lang.String OFFHEAP_KEEP_ALIVE
OFFHEAP_CORE_THREADS
, OFFHEAP_MAX_THREADS
and OFFHEAP_KEEP_ALIVE
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.offHeap.keepAlive" | Duration | Yes | 10 min | 1 s | 1 d |
public static final java.lang.String CHECKPOINTER_BYTES_INTERVAL
CHECKPOINTER_WAKEUP_INTERVAL
. To use
time based checkpointing, set this to 0.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.checkpointer.bytesInterval" | Long | No | 20000000 (20M) | 0 | -none- |
public static final java.lang.String CHECKPOINTER_WAKEUP_INTERVAL
CHECKPOINTER_BYTES_INTERVAL
).
Name | Type | Mutable | Default | Minimum | Maximum |
"je.checkpointer.wakeupInterval" | Duration | No | 0 | 1 s | 75 min |
public static final java.lang.String CHECKPOINTER_DEADLOCK_RETRY
Name | Type | Mutable | Default | Minimum | Maximum |
"je.checkpointer.deadlockRetry" | Integer | No | 3 | 0 | -none- |
public static final java.lang.String CHECKPOINTER_HIGH_PRIORITY
Name | Type | Mutable | Default |
"je.checkpointer.highPriority" | Boolean | Yes | false |
public static final java.lang.String CLEANER_MIN_UTILIZATION
Name | Type | Mutable | Default | Minimum | Maximum |
"je.cleaner.minUtilization" | Integer | Yes | 50 | 0 | 90 |
public static final java.lang.String CLEANER_MIN_FILE_UTILIZATION
Name | Type | Mutable | Default | Minimum | Maximum |
"je.cleaner.minFileUtilization" | Integer | Yes | 5 | 0 | 50 |
public static final java.lang.String CLEANER_BYTES_INTERVAL
LOG_FILE_MAX
value divided by four, or to 100 MB, whichever is
smaller.
When overriding the default value, use caution to ensure that the cleaner is woken frequently enough, so that reserved files are deleted quickly enough to avoid violating a disk limit.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.cleaner.bytesInterval" | Long | Yes | 0 | 0 | -none- |
CLEANER_WAKEUP_INTERVAL
,
Constant Field Valuespublic static final java.lang.String CLEANER_WAKEUP_INTERVAL
CLEANER_BYTES_INTERVAL
may not cause
cleaning, and CHECKPOINTER_BYTES_INTERVAL
may not cause
checkpointing, when enough writing has not occurred to exceed these
intervals.
If this parameter is set to zero, the cleaner wakeup interval is
disabled, and cleaning and checkpointing will occur only via CLEANER_BYTES_INTERVAL
, CHECKPOINTER_BYTES_INTERVAL
, and
CHECKPOINTER_WAKEUP_INTERVAL
.
For example, if a database were removed or truncated, or large records were deleted, the amount written to the log may not exceed CLEANER_BYTES_INTERVAL. If writing were to stop at that point, no cleaning would occur, if it were not for the wakeup interval.
In addition, even when cleaning is performed, a checkpoint is
additionally needed to reclaim disk space. This may not occur if
CHECKPOINTER_BYTES_INTERVAL
or
CHECKPOINTER_WAKEUP_INTERVAL
does not happen to cause a
checkpoint after write operations have stopped. If files have been
cleaned and a checkpoint is needed to reclaim space, and write
operations have stopped, a checkpoint will be scheduled when the
CLEANER_WAKEUP_INTERVAL elapses. The checkpoint will be performed in the
JE checkpointer thread if it is not disabled, or when
Environment.checkpoint(com.sleepycat.je.CheckpointConfig)
is called.
In test environments it is fairly common for application writing to stop, and then to expect cleaning to occur as a result of the last set of operations. This situation may also arise in production environments, for example, during repair of an out-of-disk situation.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.cleaner.wakeupInterval" | Duration | Yes | 10 s | 0 | 10 h |
CLEANER_BYTES_INTERVAL
,
Constant Field Valuespublic static final java.lang.String CLEANER_FETCH_OBSOLETE_SIZE
Name | Type | Mutable | Default |
"je.cleaner.fetchObsoleteSize" | Boolean | Yes | false |
CLEANER_ADJUST_UTILIZATION
,
Constant Field Valuespublic static final java.lang.String CLEANER_ADJUST_UTILIZATION
public static final java.lang.String CLEANER_DEADLOCK_RETRY
Name | Type | Mutable | Default | Minimum | Maximum |
"je.cleaner.deadlockRetry" | Integer | Yes | 3 | 0 | -none- |
public static final java.lang.String CLEANER_LOCK_TIMEOUT
Name | Type | Mutable | Default | Minimum | Maximum |
"je.cleaner.lockTimeout" | Duration | Yes | 500 ms | 0 | 75 min |
public static final java.lang.String CLEANER_EXPUNGE
CLEANER_USE_DELETED_DIR
parameter, the file is either renamed in its current data directory
(the default), or moved into the "deleted" sub-directory.
When this parameter is set to false, disk usage may grow without bounds and the application is responsible for removing the cleaned files. It may be necessary to write a script for deleting the least recently cleaned files when disk usage is low. The .del extension and the last modification time can be leveraged to write such a script. The "deleted" sub-directory can be used to avoid granting write or delete permissions for the main data directory to the script.
Name | Type | Mutable | Default |
"je.cleaner.expunge" | Boolean | Yes | true |
public static final java.lang.String CLEANER_USE_DELETED_DIR
CLEANER_EXPUNGE
is false, the CLEANER_USE_DELETED_DIR
parameter determines whether successfully
cleaned files are moved to the "deleted" sub-directory.
CLEANER_USE_DELETED_DIR
applies only when CLEANER_EXPUNGE
is false. When CLEANER_EXPUNGE
is true,
successfully cleaned files are deleted and the CLEANER_USE_DELETED_DIR
parameter setting is ignored.
When CLEANER_USE_DELETED_DIR
is true (and CLEANER_EXPUNGE
is false), the cleaner will move successfully cleaned
data files (".jdb" files) to the "deleted" sub-directory of the
Environment directory, in addition to changing the file extension to
"*.del". In this case, the "deleted" sub-directory must have been
created by the application before opening the Environment. This allows
the application to control permissions on this sub-directory. When
multiple data directories are used (LOG_N_DATA_DIRECTORIES
), a
"deleted" sub-directory must be created under each data directory. Note
that File.renameTo(File)
is used to move the file, and
this method may or may not support moving the file to a different volume
(when the "deleted" directory is a file system link) on a particular
platform.
When CLEANER_USE_DELETED_DIR
is false (and CLEANER_EXPUNGE
is false), the cleaner will change the file extension
of successfully cleaned data files from ".jdb" to ".del", but will not
move the files to a different directory.
Name | Type | Mutable | Default |
"je.cleaner.useDeletedDir" | Boolean | Yes | false |
public static final java.lang.String CLEANER_MIN_AGE
Name | Type | Mutable | Default | Minimum | Maximum |
"je.cleaner.minAge" | Integer | Yes | 2 | 1 | 1000 |
public static final java.lang.String CLEANER_MAX_BATCH_FILES
public static final java.lang.String CLEANER_READ_SIZE
LOG_ITERATOR_READ_SIZE
value is used.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.cleaner.readSize" | Integer | Yes | 0 | 128 | -none- |
public static final java.lang.String CLEANER_DETAIL_MAX_MEMORY_PERCENTAGE
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 |
public static final java.lang.String CLEANER_FORCE_CLEAN_FILES
Name | Type | Mutable | Default |
"je.cleaner.forceCleanFiles" | String | No | "" |
public static final java.lang.String CLEANER_UPGRADE_TO_LOG_VERSION
Name | Type | Mutable | Default | Minimum | Maximum |
"je.cleaner.upgradeToLogVersion" | Integer | No | 0 | -1 | -none- |
public static final java.lang.String CLEANER_THREADS
Name | Type | Mutable | Default | Minimum | Maximum |
"je.cleaner.threads" | Integer | Yes | 1 | 1 | -none- |
public static final java.lang.String CLEANER_LOOK_AHEAD_CACHE_SIZE
Name | Type | Mutable | Default | Minimum | Maximum |
"je.cleaner.lookAheadCacheSize" | Integer | Yes | 8192 (8K) | 0 | -none- |
public static final java.lang.String CLEANER_FOREGROUND_PROACTIVE_MIGRATION
public static final java.lang.String CLEANER_BACKGROUND_PROACTIVE_MIGRATION
public static final java.lang.String CLEANER_LAZY_MIGRATION
public static final java.lang.String DOS_PRODUCER_QUEUE_TIMEOUT
Name | Type | Mutable | Default | Minimum | Maximum |
"je.env.diskOrderedScanLockTimeout" | Duration | Yes | 10 secs | 0 | 75 min |
public static final java.lang.String LOCK_N_LOCK_TABLES
Name | Type | Mutable | Default | Minimum | Maximum |
"je.lock.nLockTables" | Integer | No | 1 | 1 | 32767 (32K) |
public static final java.lang.String LOCK_TIMEOUT
Transaction.setLockTimeout(long, TimeUnit)
.
A value of zero disables lock timeouts. This is not recommended, even when the application expects that deadlocks will not occur or will be easily resolved. A lock timeout is a fall-back that guards against unexpected "live lock", unresponsive threads, or application failure to close a cursor or to commit or abort a transaction.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.lock.timeout" | Duration | No | 500 ms | 0 | 75 min |
public static final java.lang.String LOCK_DEADLOCK_DETECT
Deadlock detection is performed as follows.
LOCK_DEADLOCK_DETECT_DELAY
interval, if it is non-zero.
This delay is useful for avoiding the overhead of deadlock
detection when normal, short-lived contention (not a deadlock) is
the reason for the conflict. If the lock is acquired during the
delay, the thread wakes up and the operation returns
normally.DeadlockException
is thrown in
one of the threads participating in the deadlock, called the
"victim". The victim is chosen at random to prevent a repeated
pattern of deadlocks, called "live lock". A non-victim thread that
detects a deadlock will notify the victim and perform short
delays, waiting for the deadlock to be broken; if the lock is
acquired, the operation returns normally.DeadlockException
is
thrown for the last deadlock detected, in the thread that detected
the deadlock. In this case, DeadlockException
may be
thrown by more than one thread participating in the deadlock.
DeadlockException
is thrown; otherwise,
LockTimeoutException
or
TransactionTimeoutException
is thrown.
Deadlock detection may be disabled (by setting this parameter to false)
in applications that are known to be free of deadlocks, and this may
provide a slight performance improvement in certain scenarios. However,
this is not recommended because deadlock-free operation is difficult to
guarantee. If deadlock detection is disabled, JE skips steps 2, 3 and 4
above. However, deadlock detection is always performed in the last step,
and DeadlockException
may be thrown.
Name | Type | Mutable | Default |
"je.lock.deadlockDetect" | Boolean | No | true |
public static final java.lang.String LOCK_DEADLOCK_DETECT_DELAY
LOCK_DEADLOCK_DETECT
for more information.
Name | Type | Mutable | Default | Minimum | Maximum |
"je.lock.deadlockDetectDelay" | Duration | No | 0 | 0 | 75 min |
public static final java.lang.String LOCK_OLD_LOCK_EXCEPTIONS
public static final java.lang.String TXN_TIMEOUT
Name | Type | Mutable | Default | Minimum | Maximum |
"je.txn.timeout" | Duration | No | 0 | 0 | 75 min |
public static final java.lang.String TXN_SERIALIZABLE_ISOLATION
Name | Type | Mutable | Default |
"je.txn.serializableIsolation" | Boolean | No | false |
public static final java.lang.String TXN_DURABILITY
Name | Type | Mutable | Default |
"je.txn.durability" | String | Yes | null |
Durability.parse(String)
public static final java.lang.String TXN_DEADLOCK_STACK_TRACE
Name | Type | Mutable | Default |
"je.txn.deadlockStackTrace" | Boolean | Yes | false |
public static final java.lang.String TXN_DUMP_LOCKS
Name | Type | Mutable | Default |
"je.txn.dumpLocks" | Boolean | Yes | false |
public static final java.lang.String TRACE_FILE
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.public static final java.lang.String TRACE_CONSOLE
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.public static final java.lang.String TRACE_DB
public static final java.lang.String TRACE_FILE_LIMIT
public static final java.lang.String TRACE_FILE_COUNT
public static final java.lang.String TRACE_LEVEL
public static final java.lang.String CONSOLE_LOGGING_LEVEL
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" |
public static final java.lang.String FILE_LOGGING_LEVEL
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" |
public static final java.lang.String TRACE_LEVEL_LOCK_MANAGER
public static final java.lang.String TRACE_LEVEL_RECOVERY
public static final java.lang.String TRACE_LEVEL_EVICTOR
public static final java.lang.String TRACE_LEVEL_CLEANER
public static final java.lang.String STARTUP_DUMP_THRESHOLD
Name | Type | Mutable | Default | Minimum | Maximum |
"je.env.startupThreshold" | Duration | No | 5 min | 0 | none |
public static final java.lang.String STATS_COLLECT
Name | Type | Mutable | Default | Minimum | Maximum |
"je.stats.collect" | Boolean | Yes | True | 0 | none |
public static final java.lang.String STATS_MAX_FILES
Name | Type | Mutable | Default | Minimum | Maximum |
"je.stats.max.files" | Integer | Yes | 10 | 1 | -none- |
public static final java.lang.String STATS_FILE_ROW_COUNT
Name | Type | Mutable | Default | Minimum | Maximum |
"je.stats.file.row.count" | Integer | Yes | 1440 | 1 | -none- |
public static final java.lang.String STATS_COLLECT_INTERVAL
Name | Type | Mutable | Default | Minimum | Maximum |
"je.stats.collect.interval" | Duration | Yes | 1 min | 1 s | 24 d |
public static final java.lang.String STATS_FILE_DIRECTORY
Name | Type | Mutable | Default |
"je.stats.file.directory" | String | No | "NULL-> Environment home directory" |
public EnvironmentConfig()
public EnvironmentConfig(java.util.Properties properties) throws java.lang.IllegalArgumentException
properties
- Supported properties are described in this classjava.lang.IllegalArgumentException
- If any properties read from the
properties param are invalid.public EnvironmentConfig setAllowCreate(boolean allowCreate)
allowCreate
- If true, the database environment is created if it
doesn't already exist.public boolean getAllowCreate()
public EnvironmentConfig setLockTimeout(long timeout, java.util.concurrent.TimeUnit unit) throws java.lang.IllegalArgumentException
LOCK_TIMEOUT
.timeout
- The lock timeout for all transactional and
non-transactional operations, or zero to disable lock timeouts.unit
- the TimeUnit
of the timeout value. May be null only
if timeout is zero.java.lang.IllegalArgumentException
- if the value of timeout is invalidLOCK_TIMEOUT
,
Transaction.setLockTimeout(long,TimeUnit)
public EnvironmentConfig setLockTimeout(long timeout) throws java.lang.IllegalArgumentException
setLockTimeout(long,
TimeUnit)
.setLockTimeout(long, TimeUnit.MICROSECONDS);
java.lang.IllegalArgumentException
public long getLockTimeout(java.util.concurrent.TimeUnit unit)
unit
- the TimeUnit
of the returned value. May not be null.
A value of 0 means no timeout is set.public long getLockTimeout()
getLockTimeout(TimeUnit)
.getLockTimeout(TimeUnit.MICROSECONDS);
public EnvironmentConfig setReadOnly(boolean readOnly)
ENV_READ_ONLY
.readOnly
- If true, configure the database environment to be read
only, and any attempt to modify a database will fail.public boolean getReadOnly()
This method may be called at any time during the life of the application.
public EnvironmentConfig setTransactional(boolean transactional)
ENV_IS_TRANSACTIONAL
.transactional
- If true, configure the database environment for
transactions.public boolean getTransactional()
This method may be called at any time during the life of the application.
public EnvironmentConfig setLocking(boolean locking)
ENV_IS_LOCKING
.locking
- If false, configure the database environment for no
locking. The default is true.public boolean getLocking()
This method may be called at any time during the life of the application.
public EnvironmentConfig setTxnTimeout(long timeout, java.util.concurrent.TimeUnit unit) throws java.lang.IllegalArgumentException
TXN_TIMEOUT
.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.java.lang.IllegalArgumentException
- If the value of timeout is negativeTXN_TIMEOUT
,
Transaction.setTxnTimeout(long, java.util.concurrent.TimeUnit)
public EnvironmentConfig setTxnTimeout(long timeout) throws java.lang.IllegalArgumentException
setTxnTimeout(long,
TimeUnit)
.setTxnTimeout(long, TimeUnit.MICROSECONDS);
java.lang.IllegalArgumentException
public long getTxnTimeout(java.util.concurrent.TimeUnit unit)
TXN_TIMEOUT
.
A value of 0 means transaction timeouts are not configured.
unit
- the TimeUnit
of the returned value. May not be null.public long getTxnTimeout()
getTxnTimeout(TimeUnit)
.getTxnTimeout(TimeUnit.MICROSECONDS);
public EnvironmentConfig setTxnSerializableIsolation(boolean txnSerializableIsolation)
TXN_SERIALIZABLE_ISOLATION
.LockMode
public boolean getTxnSerializableIsolation()
TXN_SERIALIZABLE_ISOLATION
.LockMode
public EnvironmentConfig setSharedCache(boolean sharedCache)
SHARED_CACHE
parameter.sharedCache
- If true, the shared cache is used by this
environment.public boolean getSharedCache()
SHARED_CACHE
parameter.public EnvironmentConfig setNodeName(java.lang.String nodeName)
public java.lang.String getNodeName()
public EnvironmentConfig setCustomStats(CustomStats customStats)
public CustomStats getCustomStats()
public EnvironmentConfig setLoggingHandler(java.util.logging.Handler handler)
Handler
is not serializable, and the logging
handler should be set within the same process.public java.util.logging.Handler getLoggingHandler()
public EnvironmentConfig setConfigParam(java.lang.String paramName, java.lang.String value) throws java.lang.IllegalArgumentException
EnvironmentMutableConfig
setConfigParam
in class EnvironmentMutableConfig
paramName
- the configuration parameter name, one of the String
constants in this classvalue
- The configuration valuejava.lang.IllegalArgumentException
- if the paramName or value is invalid.public EnvironmentConfig setRecoveryProgressListener(ProgressListener<RecoveryProgress> progressListener)
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.
progressListener
- The ProgressListener to callback during
environment startup (recovery).public ProgressListener<RecoveryProgress> getRecoveryProgressListener()
public EnvironmentConfig setClassLoader(java.lang.ClassLoader classLoader)
public java.lang.ClassLoader getClassLoader()
public EnvironmentConfig clone()
public java.lang.String toString()
toString
in class EnvironmentMutableConfig
Copyright (c) 2002, 2017 Oracle and/or its affiliates. All rights reserved.