public class Environment
extends java.lang.Object
implements java.io.Closeable
To open an existing environment with default attributes the application may use a default environment configuration object or null:
or// Open an environment handle with default attributes. Environment env = new Environment(home, new EnvironmentConfig());
Environment env = new Environment(home, null);
Note that many Environment objects may access a single environment.
To create an environment or customize attributes, the application should customize the configuration class. For example:
EnvironmentConfig envConfig = new EnvironmentConfig(); envConfig.setTransactional(true); envConfig.setAllowCreate(true); envConfig.setCacheSize(1000000); Environment newlyCreatedEnv = new Environment(home, envConfig);
Note that environment configuration parameters can also be set through the <environment home>/je.properties file. This file takes precedence over any programmatically specified configuration parameters so that configuration changes can be made without recompiling. Environment configuration follows this order of precedence:
An environment handle is an Environment instance. More than one Environment instance may be created for the same physical directory, which is the same as saying that more than one Environment handle may be open at one time for a given environment.
The Environment handle should not be closed while any other handle remains open that is using it as a reference (for example,Database
or Transaction
. Once Environment.close
is called, this object may not be accessed again.Constructor and Description |
---|
Environment(java.io.File envHome,
EnvironmentConfig configuration)
Creates a database environment handle.
|
Modifier and Type | Method and Description |
---|---|
Transaction |
beginTransaction(Transaction parent,
TransactionConfig txnConfig)
Creates a new transaction in the database environment.
|
void |
checkpoint(CheckpointConfig ckptConfig)
Synchronously checkpoint the database environment.
|
int |
cleanLog()
Synchronously invokes log file (data file) cleaning until the target
disk space utilization has been reached; this method is called
periodically by the cleaner background threads.
|
boolean |
cleanLogFile()
Synchronously invokes cleaning of a single log file (data file), if
the target disk space utilization has not been reached.
|
void |
close()
The Environment.close method closes the Berkeley DB environment.
|
void |
compress()
Synchronously invokes the compressor mechanism which compacts in memory
data structures after delete operations.
|
void |
evictMemory()
Synchronously invokes the mechanism for keeping memory usage within the
cache size boundaries.
|
void |
flushLog(boolean fsync)
Writes buffered data to the log, and optionally performs an fsync to
guarantee that data is written to the physical device.
|
EnvironmentConfig |
getConfig()
Returns this object's configuration.
|
java.util.List<java.lang.String> |
getDatabaseNames()
Returns a List of database names for the database environment.
|
java.io.File |
getHome()
Returns the database environment's home directory.
|
EnvironmentFailureException |
getInvalidatingException()
Returns the exception that caused the environment to be invalidated, or
null if the environment was not invalidated by an exception.
|
LockStats |
getLockStats(StatsConfig config)
Deprecated.
as of 4.0.10, replaced by
getStats(StatsConfig) . |
EnvironmentMutableConfig |
getMutableConfig()
Returns database environment attributes.
|
EnvironmentStats |
getStats(StatsConfig config)
Returns the general database environment statistics.
|
Transaction |
getThreadTransaction()
Returns the transaction associated with this thread if implied
transactions are being used.
|
TransactionStats |
getTransactionStats(StatsConfig config)
Returns the database environment's transactional statistics.
|
boolean |
isClosed()
Returns whether the environment has been closed by the application.
|
protected boolean |
isInternalHandle() |
boolean |
isValid()
Returns whether this
Environment is open, valid and can be used. |
Database |
openDatabase(Transaction txn,
java.lang.String databaseName,
DatabaseConfig dbConfig)
Opens, and optionally creates, a
Database . |
DiskOrderedCursor |
openDiskOrderedCursor(Database[] databases,
DiskOrderedCursorConfig config)
Create a DiskOrderedCursor to iterate over the records of a given set
of databases.
|
SecondaryDatabase |
openSecondaryDatabase(Transaction txn,
java.lang.String databaseName,
Database primaryDatabase,
SecondaryConfig dbConfig)
Opens and optionally creates a
SecondaryDatabase . |
PreloadStats |
preload(Database[] databases,
PreloadConfig config)
Preloads the cache with multiple databases.
|
void |
printStartupInfo(java.io.PrintStream out)
Print a detailed report about the costs of different phases of
environment startup.
|
void |
removeDatabase(Transaction txn,
java.lang.String databaseName)
Removes a database from the environment, discarding all records in the
database and removing the database name itself.
|
void |
renameDatabase(Transaction txn,
java.lang.String databaseName,
java.lang.String newName)
Renames a database, without removing the records it contains.
|
void |
setMutableConfig(EnvironmentMutableConfig mutableConfig)
Sets database environment attributes.
|
void |
setThreadTransaction(Transaction txn)
Sets the transaction associated with this thread if implied transactions
are being used.
|
void |
sync()
Synchronously flushes database environment databases to stable storage.
|
long |
truncateDatabase(Transaction txn,
java.lang.String databaseName,
boolean returnCount)
Empties the database, discarding all the records it contains, without
removing the database name.
|
boolean |
verify(VerifyConfig config,
java.io.PrintStream out)
Returns if the database environment is consistent and correct.
|
public Environment(java.io.File envHome, EnvironmentConfig configuration) throws EnvironmentNotFoundException, EnvironmentLockedException, VersionMismatchException, DatabaseException, java.lang.IllegalArgumentException
envHome
- The database environment's home directory.configuration
- The database environment attributes. If null,
default attributes are used.EnvironmentNotFoundException
- if the environment does not exist
(does not contain at least one log file) and the EnvironmentConfig AllowCreate
parameter is false.EnvironmentLockedException
- when an environment cannot be opened
for write access because another process has the same environment open
for write access. Warning: This exception should be
handled when an environment is opened by more than one process.VersionMismatchException
- when the existing log is not compatible
with the version of JE that is running. This occurs when a later
version of JE was used to create the log. Warning:
This exception should be handled when more than one version of JE may be
used to access an environment.EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.UnsupportedOperationException
- if this environment was previously
opened for replication and is not being opened read-only.java.lang.IllegalArgumentException
- if an invalid parameter is specified,
for example, an invalid EnvironmentConfig
parameter.DatabaseException
public void close() throws DatabaseException
When the last environment handle is closed, allocated resources are freed, and daemon threads are stopped, even if they are performing work. For example, if the cleaner is still cleaning the log, it will be stopped at the next reasonable opportunity and perform no more cleaning operations. After stopping background threads, a final checkpoint is performed by this method, in order to reduce the time to recover the next time the environment is opened.
When minimizing recovery time is desired, it is often useful to stop
all application activity and perform an additional checkpoint prior to
calling close
. This additional checkpoint will write most of
dirty Btree information, so that that the final checkpoint is very
small (and recovery is fast). To ensure that recovery time is minimized,
the log cleaner threads should also be stopped prior to the extra
checkpoint. This prevents log cleaning from dirtying the Btree, which
can make the final checkpoint larger (and recovery time longer). The
recommended procedure for minimizing recovery time is:
// Stop/finish all application operations that are using JE. ... // Stop the cleaner daemon threads. EnvironmentMutableConfig config = env.getMutableConfig(); config.setConfigParam(EnvironmentConfig.ENV_RUN_CLEANER, "false"); env.setMutableConfig(config); // Perform an extra checkpoint env.checkpoint(new CheckpointConfig().setForce(true)); // Finally, close the environment. env.close();
The Environment handle should not be closed while any other handle
that refers to it is not yet closed; for example, database environment
handles must not be closed while database handles remain open, or
transactions in the environment have not yet committed or aborted.
Specifically, this includes Database
,
and Transaction
handles.
If this handle has already been closed, this method does nothing and returns without throwing an exception.
In multithreaded applications, only a single thread should call Environment.close.
The environment handle may not be used again after this method has
been called, regardless of the method's success or failure, with one
exception: the close
method itself may be called any number of
times.
WARNING: To guard against memory leaks, the application should discard all references to the closed handle. While BDB makes an effort to discard references from closed objects to the allocated memory for an environment, this behavior is not guaranteed. The safe course of action for an application is to discard all references to closed BDB objects.
close
in interface java.io.Closeable
close
in interface java.lang.AutoCloseable
EnvironmentWedgedException
- when the current process must be
shut down and restarted before re-opening the Environment.EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.DiskLimitException
- if the final checkpoint cannot be performed
because a disk limit has been violated. The Environment will be closed,
but this exception will be thrown so that the application is aware that
a checkpoint was not performed.java.lang.IllegalStateException
- if any open databases or transactions
refer to this handle. The Environment will be closed, but this exception
will be thrown so that the application is aware that not all databases
and transactions were closed.DatabaseException
public Database openDatabase(Transaction txn, java.lang.String databaseName, DatabaseConfig dbConfig) throws DatabaseNotFoundException, DatabaseExistsException, java.lang.IllegalArgumentException, java.lang.IllegalStateException
Database
.txn
- For a transactional database, an explicit transaction may be
specified, or null may be specified to use auto-commit. For a
non-transactional database, null must be specified.databaseName
- The name of the database.dbConfig
- The database attributes. If null, default attributes
are used.DatabaseExistsException
- if the database already exists and the
DatabaseConfig ExclusiveCreate
parameter is true.DatabaseNotFoundException
- if the database does not exist and the
DatabaseConfig AllowCreate
parameter is false.OperationFailureException
- if one of the Read Operation
Failures occurs. If the database does not exist and the AllowCreate
parameter is true, then one
of the Write
Operation Failures may also occur.EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.java.lang.IllegalArgumentException
- if an invalid parameter is specified,
for example, an invalid DatabaseConfig
property.java.lang.IllegalStateException
- if DatabaseConfig properties are changed
and there are other open handles for this database.public SecondaryDatabase openSecondaryDatabase(Transaction txn, java.lang.String databaseName, Database primaryDatabase, SecondaryConfig dbConfig) throws DatabaseNotFoundException, DatabaseExistsException, DatabaseException, java.lang.IllegalArgumentException, java.lang.IllegalStateException
SecondaryDatabase
.
Note that the associations between primary and secondary databases are not stored persistently. Whenever a primary database is opened for write access by the application, the appropriate associated secondary databases should also be opened by the application. This is necessary to ensure data integrity when changes are made to the primary database.
txn
- For a transactional database, an explicit transaction may be
specified, or null may be specified to use auto-commit. For a
non-transactional database, null must be specified.databaseName
- The name of the database.primaryDatabase
- the primary database with which the secondary
database will be associated. The primary database must not be
configured for duplicates.dbConfig
- The secondary database attributes. If null, default
attributes are used.DatabaseExistsException
- if the database already exists and the
DatabaseConfig ExclusiveCreate
parameter is true.DatabaseNotFoundException
- if the database does not exist and the
DatabaseConfig AllowCreate
parameter is false.OperationFailureException
- if one of the Read Operation
Failures occurs. If the database does not exist and the AllowCreate
parameter is true, then one
of the Write
Operation Failures may also occur.EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.java.lang.IllegalArgumentException
- if an invalid parameter is specified,
for example, an invalid SecondaryConfig
property.java.lang.IllegalStateException
- if DatabaseConfig properties are changed
and there are other open handles for this database.DatabaseException
public void removeDatabase(Transaction txn, java.lang.String databaseName) throws DatabaseNotFoundException
Compared to deleting all the records in a database individually,
removeDatabase
is a very efficient operation. Some internal
housekeeping information is updated, but the database records are not
read or written, and very little I/O is needed.
When called on a database configured with secondary indices, the application is responsible for also removing all associated secondary indices. To guarantee integrity, a primary database and all of its secondary databases should be removed atomically using a single transaction.
Applications should not remove a database with open Database
handles. If the database is open with the same transaction as
passed in the txn
parameter, IllegalStateException
is
thrown by this method. If the database is open using a different
transaction, this method will block until all database handles are
closed, or until the conflict is resolved by throwing LockConflictException
.
txn
- For a transactional environment, an explicit transaction
may be specified or null may be specified to use auto-commit. For a
non-transactional environment, null must be specified.databaseName
- The database to be removed.DatabaseNotFoundException
- if the database does not exist.OperationFailureException
- if one of the Write
Operation Failures occurs.EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.UnsupportedOperationException
- if this is a read-only
environment.java.lang.IllegalStateException
- if the database is currently open using
the transaction passed in the txn
parameter, or if this handle
or the underlying environment has been closed.java.lang.IllegalArgumentException
- if an invalid parameter is specified.public void renameDatabase(Transaction txn, java.lang.String databaseName, java.lang.String newName) throws DatabaseNotFoundException
Applications should not rename a database with open Database
handles. If the database is open with the same transaction as
passed in the txn
parameter, IllegalStateException
is
thrown by this method. If the database is open using a different
transaction, this method will block until all database handles are
closed, or until the conflict is resolved by throwing LockConflictException
.
txn
- For a transactional environment, an explicit transaction
may be specified or null may be specified to use auto-commit. For a
non-transactional environment, null must be specified.databaseName
- The new name of the database.DatabaseNotFoundException
- if the database does not exist.OperationFailureException
- if one of the Write
Operation Failures occurs.EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.UnsupportedOperationException
- if this is a read-only
environment.java.lang.IllegalStateException
- if the database is currently open using
the transaction passed in the txn
parameter, or if this handle
or the underlying environment has been closed.java.lang.IllegalArgumentException
- if an invalid parameter is specified.public long truncateDatabase(Transaction txn, java.lang.String databaseName, boolean returnCount) throws DatabaseNotFoundException
Compared to deleting all the records in a database individually,
truncateDatabase
is a very efficient operation. Some internal
housekeeping information is updated, but the database records are not
read or written, and very little I/O is needed.
When called on a database configured with secondary indices, the application is responsible for also truncating all associated secondary indices. To guarantee integrity, a primary database and all of its secondary databases should be truncated atomically using a single transaction.
Applications should not truncate a database with open Database
handles. If the database is open with the same transaction as
passed in the txn
parameter, IllegalStateException
is
thrown by this method. If the database is open using a different
transaction, this method will block until all database handles are
closed, or until the conflict is resolved by throwing LockConflictException
.
txn
- For a transactional environment, an explicit transaction may
be specified or null may be specified to use auto-commit. For a
non-transactional environment, null must be specified.databaseName
- The database to be truncated.returnCount
- If true, count and return the number of records
discarded.DatabaseNotFoundException
- if the database does not exist.OperationFailureException
- if one of the Write
Operation Failures occurs.EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.UnsupportedOperationException
- if this is a read-only
environment.java.lang.IllegalStateException
- if the database is currently open using
the transaction passed in the txn
parameter, or if this handle
or the underlying environment has been closed.java.lang.IllegalArgumentException
- if an invalid parameter is specified.public java.io.File getHome() throws DatabaseException
EnvironmentFailureException
is
never thrown by this method.java.lang.IllegalStateException
- if this handle has been closed.DatabaseException
public Transaction beginTransaction(Transaction parent, TransactionConfig txnConfig) throws DatabaseException, java.lang.IllegalArgumentException
Transaction handles are free-threaded; transactions handles may be used concurrently by multiple threads.
Cursors may not span transactions; that is, each cursor must be opened and closed within a single transaction. The parent parameter is a placeholder for nested transactions, and must currently be null.
txnConfig
- The transaction attributes. If null, default
attributes are used.InsufficientReplicasException
- if the Master
in a replicated environment could not contact a quorum of replicas as
determined by the Durability.ReplicaAckPolicy
.ReplicaConsistencyException
- if a replica
in a replicated environment cannot become consistent within the timeout
period.EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.UnsupportedOperationException
- if this is not a transactional
environment.java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.java.lang.IllegalArgumentException
- if an invalid parameter is specified,
for example, an invalid TransactionConfig
parameter.DatabaseException
public void checkpoint(CheckpointConfig ckptConfig) throws DatabaseException
This is an optional action for the application since this activity is, by default, handled by a database environment owned background thread.
A checkpoint has the side effect of flushing all preceding
non-transactional write operations, as well as any preceding
transactions that were committed with no-sync durability
. However, for best
performance, checkpoints should be used only to bound recovery time.
flushLog(boolean)
can be used to write buffered data for durability
purposes.
ckptConfig
- The checkpoint attributes. If null, default
attributes are used.EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.DiskLimitException
- if the checkpoint cannot be performed
because a disk limit has been violated.java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.DatabaseException
public void sync() throws DatabaseException
CheckpointConfig.setMinimizeRecoveryTime(boolean)
to true.
A checkpoint has the side effect of flushing all preceding
non-transactional write operations, as well as any preceding
transactions that were committed with no-sync durability
. However, for best
performance, checkpoints should be used only to bound recovery time.
flushLog(boolean)
can be used to write buffered data for durability
purposes.
EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.DiskLimitException
- if the sync cannot be performed
because a disk limit has been violated.java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.DatabaseException
public void flushLog(boolean fsync)
This method is used to make durable, by writing to the log, all
preceding non-transactional write operations, as well as any preceding
transactions that were committed with no-sync durability
. If the fsync
parameter is true, it can also be used to flush all logged data to the
physical storage device, by performing an fsync.
Note that this method does not flush previously unwritten data
in deferred-write databases; that is done by calling Database.sync()
or performing a checkpoint.
fsync
- is true to perform an fsync as well as a file write, or
false to perform only a file write.EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.public int cleanLog() throws DatabaseException
Zero or more log files will be cleaned as necessary to bring the
current disk space
utilization
of the environment above the configured utilization threshold
.
Note that this method does not perform the complete task of cleaning a log file. Eviction and checkpointing log Btree information that is marked dirty by the cleaner, and a full checkpoint is necessary, following cleaning, before cleaned files will be deleted (or renamed). Checkpoints occur periodically and when the environment is closed.
This is an optional action for the application since this activity is, by default, handled by one or more Environment-owned background threads.
The intended use case for the cleanLog
method is when the
application wishes to disable the built-in cleaner threads using the
EnvironmentConfig.ENV_RUN_CLEANER
property. To replace the
functionality of the cleaner threads, the application should call
cleanLog
periodically.
Note that because this method cleans multiple files before returning,
in an attempt to reach the target utilization, it may not return for a
long time when there is a large backlog
of files to be cleaned. This
method cannot be aborted except by closing the environment. If the
application needs the ability to abort the cleaning process, the
cleanLogFile()
method should be used instead.
Note that in certain unusual situations the cleaner may not be able to make forward progress and the target utilization will never be reached. For example, this can occur if the target utilization is set too high or checkpoints are performed too often. To guard against cleaning "forever", this method will return when all files have been cleaned, even when the target utilization has not been reached.
EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.UnsupportedOperationException
- if this is a read-only or
memory-only environment.java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.DatabaseException
public boolean cleanLogFile() throws DatabaseException
One log file will be cleaned if the current disk space utilization
of the
environment is below the configured utilization threshold
. No
files will be cleaned if disk space utilization is currently above the
threshold. The lowest utilized file is selected for cleaning, since it
has the lowest cleaning cost.
Note that this method does not perform the complete task of cleaning a log file. Eviction and checkpointing log Btree information that is marked dirty by the cleaner, and a full checkpoint is necessary, following cleaning, before cleaned files will be deleted (or renamed). Checkpoints occur periodically and when the environment is closed.
The intended use case for the cleanLog
method is "batch
cleaning". This is when the application disables the cleaner threads
(using the EnvironmentConfig.ENV_RUN_CLEANER
property)
for maximum performance during active periods, and calls cleanLog
during periods when the application is quiescent or less
active than usual. Similarly, there may be times when an application
wishes to perform cleaning explicitly until the target utilization
rather than relying on the cleaner's background threads. For example,
some applications may wish to perform batch cleaning prior to closing
the environment, to reclaim as much disk space as possible at that
time.
To clean until the target utilization threshold is reached, cleanLogFile
can be called in a loop until it returns false
.
When there is a large backlog
of files to be cleaned, the application may wish to limit the
amount of cleaning. Batch cleaning can be aborted simply by breaking out
of the loop. The cleaning of a single file is not a long operation; it
should take several minutes at most. For example:
boolean cleaningAborted; boolean anyCleaned = false; while (!cleaningAborted && env.cleanLogFile()) { anyCleaned = true; }
Note that in certain unusual situations the cleaner may not be able to make forward progress and the target utilization will never be reached. For example, this can occur if the target utilization is set too high or checkpoints are performed too often. To guard against cleaning "forever", the application may wish to cancel the batch cleaning (break out of the loop) when the cleaning time or number of files cleaned exceeds some reasonable limit.
As mentioned above, the cleaned log files will not be deleted until the next full checkpoint. If the application wishes to reclaim this disk space as soon as possible, an explicit checkpoint may be performed after the batch cleaning operation. For example:
if (anyCleaned) { env.checkpoint(new CheckpointConfig().setForce(true)); }
However, even an explicit checkpoint is not guaranteed to delete the cleaned log files if, at the time the file was cleaned, records in the file were locked or were part of a database that was being removed, due to concurrent application activity that was accessing records or removing databases. In this case the files will be deleted only after these operations are complete and a subsequent checkpoint is performed. To guarantee that the cleaned files will be deleted, an application may stop all concurrent activity (ensure all operations and transactions have ended) and then perform a checkpoint.
When closing the environment and minimizing recovery time is desired
(see close()
), as well as reclaiming disk space, the recommended
procedure is as follows:
// Stop/finish all application operations that are using JE. ... // Stop the cleaner daemon threads. EnvironmentMutableConfig config = env.getMutableConfig(); config.setConfigParam(EnvironmentConfig.ENV_RUN_CLEANER, "false"); env.setMutableConfig(config); // Perform batch cleaning. while (!cleaningAborted && env.cleanLogFile()) { } // Perform an extra checkpoint env.checkpoint(new CheckpointConfig().setForce(true)); // Finally, close the environment. env.close();
EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.UnsupportedOperationException
- if this is a read-only or
memory-only environment.java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.DatabaseException
public void evictMemory() throws DatabaseException
This is an optional action for the application since this activity is, by default, handled by a database environment owned background thread.
EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.DatabaseException
public void compress() throws DatabaseException
This is an optional action for the application since this activity is, by default, handled by a database environment owned background thread.
EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.DatabaseException
public PreloadStats preload(Database[] databases, PreloadConfig config) throws DatabaseException
ReplicationConfig.FEEDER_TIMEOUT
.config
- The PreloadConfig object that specifies the parameters
of the preload.OperationFailureException
- if one of the Read Operation
Failures occurs.EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException
- if any of the databases has been closed.DatabaseException
Database.preload(PreloadConfig)
public DiskOrderedCursor openDiskOrderedCursor(Database[] databases, DiskOrderedCursorConfig config) throws DatabaseException
See DiskOrderedCursor
for more details and a description of the
consistency guarantees provided by the scan.
WARNING: After calling this method, deletion of log files by
the JE log cleaner will be disabled until DiskOrderedCursor.close()
is called. To prevent unbounded growth of
disk usage, be sure to call DiskOrderedCursor.close()
to
re-enable log file deletion.
databases
- An array containing the handles to the database that
are to be scanned. All these handles must be currently open.
Furthermore, all the databases must belong to this environments, and
they should all support duplicates or none of them should support
duplicates. Note: this method does not make a copy of this array,
and as a result, the contents of the array should not be modified
while the returned DiskOrderedCursor is still in use.config
- The DiskOrderedCursorConfig object that specifies the
parameters of the disk ordered scan.java.lang.IllegalArgumentException
- if (a) the databases parameter is
null or an empty array, or (b) any of the handles in the databases
parameter is null, or (c) the databases do not all belong to this
environment, or (d) some databases support duplicates and some don't.java.lang.IllegalStateException
- if any of the databases has been
closed or invalidated.EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.DatabaseException
public EnvironmentConfig getConfig() throws DatabaseException
Unlike most Environment methods, this method may be called if the environment is invalid, but not yet closed.
java.lang.IllegalStateException
- if this handle has been closed.DatabaseException
public void setMutableConfig(EnvironmentMutableConfig mutableConfig) throws DatabaseException
Attributes only apply to a specific Environment object and are not necessarily shared by other Environment objects accessing this database environment.
Unlike most Environment methods, this method may be called if the environment is invalid, but not yet closed.
mutableConfig
- The database environment attributes. If null,
default attributes are used.EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException
- if this handle has been closed.DatabaseException
public EnvironmentMutableConfig getMutableConfig() throws DatabaseException
Unlike most Environment methods, this method may be called if the environment is invalid, but not yet closed.
java.lang.IllegalStateException
- if this handle has been closed.DatabaseException
public EnvironmentStats getStats(StatsConfig config) throws DatabaseException
config
- The general statistics attributes. If null, default
attributes are used.EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.DatabaseException
public LockStats getLockStats(StatsConfig config) throws DatabaseException
getStats(StatsConfig)
.config
- The locking statistics attributes. If null, default
attributes are used.EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.DatabaseException
public TransactionStats getTransactionStats(StatsConfig config) throws DatabaseException
config
- The transactional statistics attributes. If null,
default attributes are used.EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.DatabaseException
public java.util.List<java.lang.String> getDatabaseNames() throws DatabaseException
Each element in the list is a String.
OperationFailureException
- if one of the Read Operation
Failures occurs.EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.DatabaseException
public boolean verify(VerifyConfig config, java.io.PrintStream out) throws DatabaseException
Verification is an expensive operation that should normally only be used for troubleshooting and debugging.
config
- The verification attributes. If null, default
attributes are used.out
- is unused. To specify the output stream for verification
information, use VerifyConfig.setShowProgressStream(java.io.PrintStream)
.EnvironmentFailureException
- if a corruption is detected, or if
an unexpected, internal or environment-wide failure occurs. If a
persistent corruption is detected,
EnvironmentFailureException.isCorrupted()
will return true.java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.DatabaseException
public Transaction getThreadTransaction() throws DatabaseException
java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.DatabaseException
public void setThreadTransaction(Transaction txn)
java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.public boolean isValid()
Environment
is open, valid and can be used.
When an EnvironmentFailureException
, or one of its
subclasses, is caught, the isValid
method can be called to
determine whether the Environment
can continue to be used, or
should be closed. Some EnvironmentFailureExceptions invalidate the
environment and others do not.
If this method returns false, the environment may have been closed by
the application, or may have been invalidated by an exception and not
yet closed. The isClosed()
method may be used to distinguish
between these two cases, and getInvalidatingException()
can be
used to return the exception. Note that it is safe to call close()
redundantly, so it is safe to always call close()
when
this method returns false.
public boolean isClosed()
If this method returns true, close()
} has been called. If
the environment was previously invalidated by an exception, it will be
returned by getInvalidatingException()
.
If this method returns false, the environment may or may not be
usable, since it may have been invalidated by an exception but not yet
closed. To determine whether it was invalidated, call isValid()
or getInvalidatingException()
.
public EnvironmentFailureException getInvalidatingException()
This method may be used to determine whether the environment was
invalidated by an exception, by checking for a non-null return value.
This method will return the invalidating exception, regardless of
whether the environment is closed. Note that isValid()
will
return false when the environment is closed, even when it was not
invalidated by an exception.
This method may also be used to identify and handle the original invalidating exception, when more than one exception is thrown. When an environment is first invalidated by an EnvironmentFailureException, the exception is saved so that it can be returned by this method. Other EnvironmentFailureExceptions may be thrown later as side effects of the original problem, or possibly as separate problems. It is normally the first invalidating exception that is most relevant.
public void printStartupInfo(java.io.PrintStream out)
Unlike most Environment methods, this method may be called if the environment is invalid, but not yet closed.
java.lang.IllegalStateException
- if this handle or the underlying
environment has been closed.protected boolean isInternalHandle()
Copyright (c) 2002, 2017 Oracle and/or its affiliates. All rights reserved.