Environment (Sleepycat Software, Inc. - Berkeley DB Java API)
Keywords: com.sleepycat.db.Environment class

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB version 4.3.29
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sleepycat.db
Class Environment

    java.lang.Object
      com.sleepycat.db.Environment

public class Environment
extends Object

A database environment. Environments include support for some or all of caching, locking, logging and transactions.

To open an existing environment with default attributes the application may use a default environment configuration object or null:

>         // Open an environment handle with default attributes.
>         Environment env = new Environment(home, new EnvironmentConfig());

or

>         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);

Environment handles are free-threaded unless `EnvironmentConfig.setThreaded` is called to disable this before the environment is opened.

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, regardless of whether or not it throws an exception.

Constructor Summary
`Environment(File envHome, EnvironmentConfig envConfig)` Create a database environment handle.

Method Summary
`Transaction` | `beginTransaction(Transaction parent, TransactionConfig txnConfig)` Create a new transaction in the database environment.
`void` | `checkpoint(CheckpointConfig checkpointConfig)` Synchronously checkpoint the database environment.
`void` | `close()` Close the database environment, freeing any allocated resources and closing any underlying subsystems.
`int` | `createLockerID()` Allocate a locker ID.
`int` | `detectDeadlocks(LockDetectMode mode)` Run one iteration of the deadlock detector.
`int` | `electReplicationMaster(int nsites, int nvotes, int priority, int timeout)` Hold an election for the master of a replication group.
`void` | `freeLockerID(int id)` Free a locker ID.
`File[]` | `getArchiveDatabases()` Return the names of the database files that need to be archived in order to recover the database from catastrophic failure.
`File[]` | `getArchiveLogFiles(boolean includeInUse)` Return the names of all of the log files that are no longer in use.
`CacheFileStats[]` | `getCacheFileStats(StatsConfig config)` Return the database environment's per-file memory pool (that is, the buffer cache) statistics.
`CacheStats` | `getCacheStats(StatsConfig config)`
`EnvironmentConfig` | `getConfig()` Return this object's configuration.
`File` | `getHome()` Return the database environment's home directory.
`Lock` | `getLock(int locker, boolean noWait, DatabaseEntry object, LockRequestMode mode)` Acquire a lock from the lock table.
`LockStats` | `getLockStats(StatsConfig config)` Return the database environment's locking statistics.
`String` | `getLogFileName(LogSequenceNumber lsn)` Return the name of the log file that contains the log record specified by a LogSequenceNumber object.
`LogStats` | `getLogStats(StatsConfig config)` Return the database environment's logging statistics.
`ReplicationStats` | `getReplicationStats(StatsConfig config)` Return the database environment's replication statistics.
`TransactionStats` | `getTransactionStats(StatsConfig config)` Return the database environment's transactional statistics.
`static int` | `getVersionMajor()` Return the release major number.
`static int` | `getVersionMinor()` Return the release minor number.
`static int` | `getVersionPatch()` Return the release patch number.
`static String` | `getVersionString()` Return the release version information, suitable for display.
`void` | `lockVector(int locker, boolean noWait, LockRequest[] list)` Atomically obtain and release one or more locks from the lock table.
`void` | `logFlush(LogSequenceNumber lsn)` Flush log records to stable storage.
`LogSequenceNumber` | `logPut(DatabaseEntry data, boolean flush)` Append a record to the log.
`Database` | `openDatabase(Transaction txn, String fileName, String databaseName, DatabaseConfig config)` Open a database.
`LogCursor` | `openLogCursor()` Return a log cursor.
`SecondaryDatabase` | `openSecondaryDatabase(Transaction txn, String fileName, String databaseName, Database primaryDatabase, SecondaryConfig config)` Open a database.
`void` | `panic(boolean onoff)` Set the panic state for the database environment.
`ReplicationStatus` | `processReplicationMessage(DatabaseEntry control, DatabaseEntry rec, int envid)` Process an incoming replication message sent by a member of the replication group to the local database environment.
`void` | `putLock(Lock lock)` Release a lock.
`PreparedTransaction[]` | `recover(int count, boolean continued)` Return a list of prepared but not yet resolved transactions.
`static void` | `remove(File home, boolean force, EnvironmentConfig config)` Destroy a database environment.
`void` | `removeDatabase(Transaction txn, String fileName, String databaseName)` Remove a database.
`void` | `removeOldLogFiles()` Remove log files that are no longer needed.
`void` | `renameDatabase(Transaction txn, String fileName, String oldDatabaseName, String newDatabaseName)` Rename a database.
`void` | `setConfig(EnvironmentConfig config)` Change the settings in an existing environment handle.
`void` | `startReplication(DatabaseEntry cdata, boolean master)` Configure the database environment as a client or master in a group of replicated database environments.
`int` | `trickleCacheWrite(int percent)` Ensure that a specified percent of the pages in the shared memory pool are clean, by writing dirty pages to their backing files.

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

Constructor Detail

### Environment

    public Environment(File envHome,
                       EnvironmentConfig envConfig)
                throws DatabaseException,
                       FileNotFoundException

  Create a database environment handle.

Parameters:
  `envHome` - The database environment's home directory. The environment variable `DB_HOME` may be used as the path of the database home. For more information on `envHome` and filename resolution in general, see File Naming.

  `envConfig` - The database environment attributes. If null, default attributes are used.

Throws:
  `IllegalArgumentException` - if an invalid parameter was specified.

  `DatabaseException` - if a failure occurs.
  `FileNotFoundException`

Method Detail

### getHome

    public File getHome()
                 throws DatabaseException

  Return the database environment's home directory.

  Returns:
    The database environment's home directory.

  Throws:
    `DatabaseException` - if a failure occurs.

### getConfig

    public EnvironmentConfig getConfig()
                                throws DatabaseException

  Return this object's configuration.

  Returns:
    This object's configuration.

  Throws:
    `DatabaseException` - if a failure occurs.

### beginTransaction

    public Transaction beginTransaction(Transaction parent,
                                        TransactionConfig txnConfig)
                                 throws DatabaseException

  Create a new transaction in the database environment.

  Transactions may only span threads if they do so serially; that is, each transaction must be active in only a single thread of control at a time.

  This restriction holds for parents of nested transactions as well; no two children may be concurrently active in more than one thread of control at any one time.

  Cursors may not span transactions; that is, each cursor must be opened and closed within a single transaction.

  A parent transaction may not issue any Berkeley DB operations -- except for `Environment.beginTransaction`, `Transaction.abort` and `Transaction.commit` -- while it has active child transactions (child transactions that have not yet been committed or aborted).

  Parameters:
    `parent` - If the parent parameter is non-null, the new transaction will be a nested transaction, with the transaction indicated by parent as its parent. Transactions may be nested to any level. In the presence of distributed transactions and two-phase commit, only the parental transaction, that is a transaction without a parent specified, should be passed as an parameter to `Transaction.prepare`.

    `txnConfig` - The transaction attributes. If null, default attributes are used.

  Returns:
    The newly created transaction's handle.

  Throws:
    `DatabaseException` - if a failure occurs.

### checkpoint

    public void checkpoint(CheckpointConfig checkpointConfig)
                    throws DatabaseException

  Synchronously checkpoint the database environment.

  Parameters:
    `checkpointConfig` - The checkpoint attributes. If null, default attributes are used.

  Throws:
    `DatabaseException` - if a failure occurs.

### getLockStats

    public LockStats getLockStats(StatsConfig config)
                           throws DatabaseException

  Return the database environment's locking statistics.

  Parameters:
    `config` - The locking statistics attributes. If null, default attributes are used.

  Returns:
    The database environment's locking statistics.

  Throws:
    `DatabaseException` - if a failure occurs.

### getTransactionStats

    public TransactionStats getTransactionStats(StatsConfig config)
                                         throws DatabaseException

  Return the database environment's transactional statistics.

  Parameters:
    `config` - The transactional statistics attributes. If null, default attributes are used.

  Returns:
    The database environment's transactional statistics.

  Throws:
    `DatabaseException` - if a failure occurs.

### close

    public void close()
               throws DatabaseException

  Close the database environment, freeing any allocated resources and closing any underlying subsystems.

  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 been committed or aborted. Specifically, this includes `Database`, `Cursor`, `Transaction`, and `LogCursor` handles.

  Where the environment was initialized with a locking subsystem, closing the environment does not release any locks still held by the closing process, providing functionality for long-lived locks.

  Where the environment was initialized with a transaction subsystem, closing the environment aborts any unresolved transactions. Applications should not depend on this behavior for transactions involving databases; all such transactions should be explicitly resolved. The problem with depending on this semantic is that aborting an unresolved transaction involving database operations requires a database handle. Because the database handles should have been closed before closing the environment, it will not be possible to abort the transaction, and recovery will have to be run on the database environment before further operations are done.

  Where log cursors were created, closing the environment does not imply closing those cursors.

  In multithreaded applications, only a single thread may call this method.

  After this method has been called, regardless of its return, the `Environment` handle may not be accessed again.

  Throws:
    `DatabaseException` - if a failure occurs.

### remove

    public static void remove(File home,
                              boolean force,
                              EnvironmentConfig config)
                       throws DatabaseException,
                              FileNotFoundException

  Destroy a database environment.

  If the environment is not in use, the environment regions, including any backing files, are removed. Any log or database files and the environment directory itself are not removed.

  If there are processes currently using the database environment, this method will fail without further action (unless the force argument is true, in which case the environment will be removed, regardless of any processes still using it).

  The result of attempting to forcibly destroy the environment when it is in use is unspecified. Processes using an environment often maintain open file descriptors for shared regions within it. On UNIX systems, the environment removal will usually succeed, and processes that have already joined the region will continue to run in that region without change. However, processes attempting to join the environment will either fail or create new regions. On other systems in which the unlink system call will fail if any process has an open file descriptor for the file (for example Windows/NT), the region removal will fail.

  Calling this method should not be necessary for most applications because the environment is cleaned up as part of normal database recovery procedures. However, applications may want to call this method as part of application shut down to free up system resources. For example, if system shared memory was used to back the database environment, it may be useful to call this method in order to release system shared memory segments that have been allocated. Or, on architectures in which mutexes require allocation of underlying system resources, it may be useful to call this method in order to release those resources. Alternatively, if recovery is not required because no database state is maintained across failures, and no system resources need to be released, it is possible to clean up an environment by simply removing all the Berkeley DB files in the database environment's directories.

  In multithreaded applications, only a single thread may call this method.

  After this method has been called, regardless of its return, the `Environment` handle may not be accessed again.

  Parameters:
    `home` - The database environment to be removed. On Windows platforms, this argument will be interpreted as a UTF-8 string, which is equivalent to ASCII for Latin characters.

    `force` - The environment is removed, regardless of any processes that may still using it, and no locks are acquired during this process. (Generally, the force argument is specified only when applications were unable to shut down cleanly, and there is a risk that an application may have died holding a Berkeley DB mutex or lock.

  Throws:
    `DatabaseException` - if a failure occurs.
    `FileNotFoundException`

### setConfig

    public void setConfig(EnvironmentConfig config)
                   throws DatabaseException

  Change the settings in an existing environment handle.

  Parameters:
    `config` - The database environment attributes. If null, default attributes are used.

  Throws:
    `IllegalArgumentException` - if an invalid parameter was specified.

    `DatabaseException` - if a failure occurs.

### openDatabase

    public Database openDatabase(Transaction txn,
                                 String fileName,
                                 String databaseName,
                                 DatabaseConfig config)
                          throws DatabaseException,
                                 FileNotFoundException

  Open a database.

  The database is represented by the file and database parameters.

  The currently supported database file formats (or access methods) are Btree, Hash, Queue, and Recno. The Btree format is a representation of a sorted, balanced tree structure. The Hash format is an extensible, dynamic hashing scheme. The Queue format supports fast access to fixed-length records accessed sequentially or by logical record number. The Recno format supports fixed- or variable-length records, accessed sequentially or by logical record number, and optionally backed by a flat text file.

  Storage and retrieval are based on key/data pairs; see `DatabaseEntry` for more information.

  Opening a database is a relatively expensive operation, and maintaining a set of open databases will normally be preferable to repeatedly opening and closing the database for each new query.

  In-memory databases never intended to be preserved on disk may be created by setting both the fileName and databaseName parameters to null. Note that in-memory databases can only ever be shared by sharing the single database handle that created them, in circumstances where doing so is safe. The environment variable `TMPDIR` may be used as a directory in which to create temporary backing files.

  Parameters:
    `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. Note that transactionally protected operations on a Database handle require that the Database handle itself be transactionally protected during its open, either with a non-null transaction handle, or by calling `DatabaseConfig.setTransactional` on the configuration object.

    `fileName` - The name of an underlying file that will be used to back the database. On Windows platforms, this argument will be interpreted as a UTF-8 string, which is equivalent to ASCII for Latin characters.

    `databaseName` - An optional parameter that allows applications to have multiple databases in a single file. Although no databaseName parameter needs to be specified, it is an error to attempt to open a second database in a physical file that was not initially created using a databaseName parameter. Further, the databaseName parameter is not supported by the Queue format.

    `config` - The database open attributes. If null, default attributes are used.
  Throws:
    `DatabaseException`
    `FileNotFoundException`

### openSecondaryDatabase

    public SecondaryDatabase openSecondaryDatabase(Transaction txn,
                                                   String fileName,
                                                   String databaseName,
                                                   Database primaryDatabase,
                                                   SecondaryConfig config)
                                            throws DatabaseException,
                                                   FileNotFoundException

  Open a database.

  The database is represented by the file and database parameters.

  The currently supported database file formats (or access methods) are Btree, Hash, Queue, and Recno. The Btree format is a representation of a sorted, balanced tree structure. The Hash format is an extensible, dynamic hashing scheme. The Queue format supports fast access to fixed-length records accessed sequentially or by logical record number. The Recno format supports fixed- or variable-length records, accessed sequentially or by logical record number, and optionally backed by a flat text file.

  Storage and retrieval are based on key/data pairs; see `DatabaseEntry` for more information.

  Opening a database is a relatively expensive operation, and maintaining a set of open databases will normally be preferable to repeatedly opening and closing the database for each new query.

  In-memory databases never intended to be preserved on disk may be created by setting both the fileName and databaseName parameters to null. Note that in-memory databases can only ever be shared by sharing the single database handle that created them, in circumstances where doing so is safe. The environment variable `TMPDIR` may be used as a directory in which to create temporary backing files.

  Parameters:
    `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. Note that transactionally protected operations on a Database handle require that the Database handle itself be transactionally protected during its open, either with a non-null transaction handle, or by calling `DatabaseConfig.setTransactional` on the configuration object.

    `fileName` - The name of an underlying file that will be used to back the database. On Windows platforms, this argument will be interpreted as a UTF-8 string, which is equivalent to ASCII for Latin characters.

    `databaseName` - An optional parameter that allows applications to have multiple databases in a single file. Although no databaseName parameter needs to be specified, it is an error to attempt to open a second database in a physical file that was not initially created using a databaseName parameter. Further, the databaseName parameter is not supported by the Queue format.

    `primaryDatabase` - a database handle for the primary database that is to be indexed.

    `config` - The secondary database open attributes. If null, default attributes are used.
  Throws:
    `DatabaseException`
    `FileNotFoundException`

### removeDatabase

    public void removeDatabase(Transaction txn,
                               String fileName,
                               String databaseName)
                        throws DatabaseException,
                               FileNotFoundException

  Remove a database.

  If no database is specified, the underlying file specified is removed.

  Applications should never remove databases with open `Database` handles, or in the case of removing a file, when any database in the file has an open handle. For example, some architectures do not permit the removal of files with open system handles. On these architectures, attempts to remove databases currently in use by any thread of control in the system may fail.

  The environment variable DB_HOME may be used as the path of the database environment home.

  This method is affected by any database directory specified with `EnvironmentConfig.addDataDir`, or by setting the "set_data_dir" string in the database environment's DB_CONFIG file.

  The `Database` handle may not be accessed again after this method is called, regardless of this method's success or failure.

  Parameters:
    `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.

    `fileName` - The physical file which contains the database to be removed. On Windows platforms, this argument will be interpreted as a UTF-8 string, which is equivalent to ASCII for Latin characters.

    `databaseName` - The database to be removed.

  Throws:
    `DeadlockException` - if the operation was selected to resolve a deadlock.

    `DatabaseException` - if a failure occurs.
    `FileNotFoundException`

### renameDatabase

    public void renameDatabase(Transaction txn,
                               String fileName,
                               String oldDatabaseName,
                               String newDatabaseName)
                        throws DatabaseException,
                               FileNotFoundException

  Rename a database.

  If no database name is specified, the underlying file specified is renamed, incidentally renaming all of the databases it contains.

  Applications should never rename databases that are currently in use. If an underlying file is being renamed and logging is currently enabled in the database environment, no database in the file may be open when this method is called. In particular, some architectures do not permit renaming files with open handles. On these architectures, attempts to rename databases that are currently in use by any thread of control in the system may fail.

  The environment variable DB_HOME may be used as the path of the database environment home.

  This method is affected by any database directory specified with `EnvironmentConfig.addDataDir`, or by setting the "set_data_dir" string in the database environment's DB_CONFIG file.

  The `Database` handle may not be accessed again after this method is called, regardless of this method's success or failure.

  Parameters:
    `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.

    `fileName` - The physical file which contains the database to be renamed. On Windows platforms, this argument will be interpreted as a UTF-8 string, which is equivalent to ASCII for Latin characters.

    `oldDatabaseName` - The database to be renamed.

    `newDatabaseName` - The new name of the database or file.

  Throws:
    `DeadlockException` - if the operation was selected to resolve a deadlock.

    `DatabaseException` - if a failure occurs.
    `FileNotFoundException`

### trickleCacheWrite

    public int trickleCacheWrite(int percent)
                          throws DatabaseException

  Ensure that a specified percent of the pages in the shared memory pool are clean, by writing dirty pages to their backing files.

  The purpose of this method is to enable a memory pool manager to ensure that a page is always available for reading in new information without having to wait for a write.

  Parameters:
    `percent` - The percent of the pages in the cache that should be clean.

  Returns:
    The number of pages that were written to reach the specified percentage.

  Throws:
    `DatabaseException` - if a failure occurs.

### detectDeadlocks

    public int detectDeadlocks(LockDetectMode mode)
                        throws DatabaseException

  Run one iteration of the deadlock detector.

  The deadlock detector traverses the lock table and marks one of the participating lock requesters for rejection in each deadlock it finds.

  Parameters:
    `mode` - Which lock request(s) to reject.

  Returns:
    The number of lock requests that were rejected.

  Throws:
    `DatabaseException` - if a failure occurs.

### getLock

    public Lock getLock(int locker,
                        boolean noWait,
                        DatabaseEntry object,
                        LockRequestMode mode)
                 throws DatabaseException

  Acquire a lock from the lock table.

  Parameters:
    `locker` - An unsigned 32-bit integer quantity representing the entity requesting the lock.

    `mode` - The lock mode.

    `noWait` - If a lock cannot be granted because the requested lock conflicts with an existing lock, throw a `LockNotGrantedException` immediately instead of waiting for the lock to become available.

    `object` - An untyped byte string that specifies the object to be locked. Applications using the locking subsystem directly while also doing locking via the Berkeley DB access methods must take care not to inadvertently lock objects that happen to be equal to the unique file IDs used to lock files.

  Throws:
    `DatabaseException` - if a failure occurs.

### putLock

    public void putLock(Lock lock)
                 throws DatabaseException

  Release a lock.

  Parameters:
    `lock` - The lock to be released.

  Throws:
    `DatabaseException` - if a failure occurs.

### createLockerID

    public int createLockerID()
                       throws DatabaseException

  Allocate a locker ID.

  The locker ID is guaranteed to be unique for the database environment.

  Call `Environment.freeLockerID` to return the locker ID to the environment when it is no longer needed.

  Returns:
    A locker ID.
  Throws:
    `DatabaseException`

### freeLockerID

    public void freeLockerID(int id)
                      throws DatabaseException

  Free a locker ID.

  Parameters:
    `id` - The locker id to be freed.

  Throws:
    `DatabaseException` - if a failure occurs.

### lockVector

    public void lockVector(int locker,
                           boolean noWait,
                           LockRequest[] list)
                    throws DatabaseException

  Atomically obtain and release one or more locks from the lock table. This method is intended to support acquisition or trading of multiple locks under one lock table semaphore, as is needed for lock coupling or in multigranularity locking for lock escalation.

  If any of the requested locks cannot be acquired, or any of the locks to be released cannot be released, the operations before the failing operation are guaranteed to have completed successfully, and the method throws an exception.

  Parameters:
    `noWait` - If a lock cannot be granted because the requested lock conflicts with an existing lock, throw a `LockNotGrantedException` immediately instead of waiting for the lock to become available. The index of the request that was not granted will be returned by `LockNotGrantedException.getIndex`.

    `locker` - An unsigned 32-bit integer quantity representing the entity requesting the lock.

    `list` - An array of `LockRequest` objects, listing the requested lock operations.

  Throws:
    `DatabaseException` - if a failure occurs.

### openLogCursor

    public LogCursor openLogCursor()
                            throws DatabaseException

  Return a log cursor.

  Returns:
    A log cursor.

  Throws:
    `DatabaseException` - if a failure occurs.

### getLogFileName

    public String getLogFileName(LogSequenceNumber lsn)
                          throws DatabaseException

  Return the name of the log file that contains the log record specified by a LogSequenceNumber object.

  This mapping of LogSequenceNumber objects to files is needed for database administration. For example, a transaction manager typically records the earliest LogSequenceNumber object needed for restart, and the database administrator may want to archive log files to tape when they contain only log records before the earliest one needed for restart.

  Parameters:
    `lsn` - The LogSequenceNumber object for which a filename is wanted.

  Returns:
    The name of the log file that contains the log record specified by a LogSequenceNumber object.

  Throws:
    `IllegalArgumentException` - if an invalid parameter was specified.

    `DatabaseException` - if a failure occurs.

### electReplicationMaster

    public int electReplicationMaster(int nsites,
                                      int nvotes,
                                      int priority,
                                      int timeout)
                               throws DatabaseException

  Hold an election for the master of a replication group.

  If the election is successful, the new master's ID may be the ID of the previous master, or the ID of the current environment. The application is responsible for adjusting its usage of the other environments in the replication group, including directing all database updates to the newly selected master, in accordance with the results of this election.

  The thread of control that calls this method must not be the thread of control that processes incoming messages; processing the incoming messages is necessary to successfully complete an election.

  Parameters:
    `nsites` - The number of environments that the application believes are in the replication group. This number is used by Berkeley DB to avoid having two masters active simultaneously, even in the case of a network partition. During an election, a new master cannot be elected unless more than half of nsites agree on the new master. Thus, in the face of a network partition, the side of the partition with more than half the environments will elect a new master and continue, while the environments communicating with fewer than half the other environments will fail to find a new master.

    `nvotes` - The number of votes required by the application to successfully elect a new master. It must be a positive integer, no greater than nsites, or 0 if the election should use a simple majority of the nsites value as the requirement. A warning is given if half or fewer votes are required to win an election as that can potentially lead to multiple masters in the face of a network partition.

    `priority` - The priority of this environment. It must be a positive integer, or 0 if this environment is not permitted to become a master.

    `timeout` - A timeout period for an election. If the election has not completed after timeout microseconds, the election will fail.

  Returns:
    The newly elected master's ID.

  Throws:
    `DatabaseException` - if a failure occurs.

### processReplicationMessage

    public ReplicationStatus processReplicationMessage(DatabaseEntry control,
                                                       DatabaseEntry rec,
                                                       int envid)
                                                throws DatabaseException

  Process an incoming replication message sent by a member of the replication group to the local database environment.

  For implementation reasons, all incoming replication messages must be processed using the same `Environment` handle. It is not required that a single thread of control process all messages, only that all threads of control processing messages use the same handle.

  Parameters:
    `control` - A copy of the control parameter specified by Berkeley DB on the sending environment.

    `envid` - The local identifier that corresponds to the environment that sent the message to be processed.

    `rec` - A copy of the rec parameter specified by Berkeley DB on the sending environment.

  Returns:
    A `ReplicationStatus` object.
  Throws:
    `DatabaseException`

### startReplication

    public void startReplication(DatabaseEntry cdata,
                                 boolean master)
                          throws DatabaseException

  Configure the database environment as a client or master in a group of replicated database environments. Replication master environments are the only database environments where replicated databases may be modified. Replication client environments are read-only as long as they are clients. Replication client environments may be upgraded to be replication master environments in the case that the current master fails or there is no master present.

  The enclosing database environment must already have been configured to send replication messages by calling `EnvironmentConfig.setReplicationTransport`.

  Parameters:
    `cdata` - An opaque data item that is sent over the communication infrastructure when the client or master comes online. If no such information is useful, cdata should be null.

    `master` - Configure the environment as a replication master. If false, the environment will be configured as as a replication client.

  Throws:
    `DatabaseException` - if a failure occurs.

### getCacheStats

    public CacheStats getCacheStats(StatsConfig config)
                             throws DatabaseException

  Throws:
    `DatabaseException`

### getCacheFileStats

    public CacheFileStats[] getCacheFileStats(StatsConfig config)
                                       throws DatabaseException

  Return the database environment's per-file memory pool (that is, the buffer cache) statistics.

  Parameters:
    `config` - The statistics attributes. If null, default attributes are used.

  Returns:
    The database environment's per-file memory pool (that is, the buffer cache) statistics.

  Throws:
    `DatabaseException` - if a failure occurs.

### getLogStats

    public LogStats getLogStats(StatsConfig config)
                         throws DatabaseException

  Return the database environment's logging statistics.

  Parameters:
    `config` - The statistics attributes. If null, default attributes are used.

  Returns:
    The database environment's logging statistics.

  Throws:
    `DatabaseException` - if a failure occurs.

### getReplicationStats

    public ReplicationStats getReplicationStats(StatsConfig config)
                                         throws DatabaseException

  Return the database environment's replication statistics.

  Parameters:
    `config` - The statistics attributes. If null, default attributes are used.

  Returns:
    The database environment's replication statistics.

  Throws:
    `DatabaseException` - if a failure occurs.

### logFlush

    public void logFlush(LogSequenceNumber lsn)
                  throws DatabaseException

  Flush log records to stable storage.

  Parameters:
    `lsn` - All log records with LogSequenceNumber values less than or equal to the lsn parameter are written to stable storage. If lsn is null, all records in the log are flushed.

  Throws:
    `DatabaseException` - if a failure occurs.

### logPut

    public LogSequenceNumber logPut(DatabaseEntry data,
                                    boolean flush)
                             throws DatabaseException

  Append a record to the log.

  Parameters:
    `data` - The record to append to the log.

    The caller is responsible for providing any necessary structure to data. (For example, in a write-ahead logging protocol, the application must understand what part of data is an operation code, what part is redo information, and what part is undo information. In addition, most transaction managers will store in data the LogSequenceNumber of the previous log record for the same transaction, to support chaining back through the transaction's log records during undo.)

    `flush` - The log is forced to disk after this record is written, guaranteeing that all records with LogSequenceNumber values less than or equal to the one being "put" are on disk before this method returns.

  Returns:
    The LogSequenceNumber of the put record.
  Throws:
    `DatabaseException`

### getArchiveLogFiles

    public File[] getArchiveLogFiles(boolean includeInUse)
                              throws DatabaseException

  Return the names of all of the log files that are no longer in use.

  This method returns the names of all of the log files that are no longer in use (for example, that are no longer involved in active transactions), and that may safely be archived for catastrophic recovery and then removed from the system. If there are no filenames to return, the method returns null.

  Log cursor handles (returned by the `Environment.openLogCursor`) may have open file descriptors for log files in the database environment. Also, the Berkeley DB interfaces to the database environment logging subsystem (for example, `logPut Environment logPut` and `Transaction.abort` may allocate log cursors and have open file descriptors for log files as well. On operating systems where filesystem related system calls (for example, rename and unlink on Windows/NT) can fail if a process has an open file descriptor for the affected file, attempting to move or remove the log files listed by this method may fail. All Berkeley DB internal use of log cursors operates on active log files only and furthermore, is short-lived in nature. So, an application seeing such a failure should be restructured to close any open log cursors it may have, and otherwise to retry the operation until it succeeds. (Although the latter is not likely to be necessary; it is hard to imagine a reason to move or rename a log file in which transactions are being logged or aborted.)

  Parameters:
    `includeInUse` - Return all the log filenames, regardless of whether or not they are in use.

  Throws:
    `DatabaseException` - if a failure occurs.

### getArchiveDatabases

    public File[] getArchiveDatabases()
                               throws DatabaseException

  Return the names of the database files that need to be archived in order to recover the database from catastrophic failure.

  If any of the database files have not been accessed during the lifetime of the current log files, their names will not be included in this list. It is also possible that some of the files referred to by the log have since been deleted from the system.

  Throws:
    `DatabaseException` - if a failure occurs.

### removeOldLogFiles

    public void removeOldLogFiles()
                           throws DatabaseException

  Remove log files that are no longer needed.

  Automatic log file removal is likely to make catastrophic recovery impossible.

  Throws:
    `DatabaseException` - if a failure occurs.

### recover

    public PreparedTransaction[] recover(int count,
                                         boolean continued)
                                  throws DatabaseException

  Return a list of prepared but not yet resolved transactions.

  This method should only be called after the environment has been recovered. Because database environment state must be preserved between recovery and the application calling this method, applications must either call this method using the same environment handle used when recovery is done, or the database environment must not be configured using the `EnvironmentConfig.setPrivate` method.

  This method returns a list of transactions that must be resolved by the application (either committed, aborted or discarded). The return value is an array of objects of type DbPreplist.

  The application must call `Transaction.abort`, `Transaction.commit` or `Transaction.discard` on each returned `Transaction` handle before starting any new operations.

  Parameters:
    `count` - The maximum number of transactions to return.

    `continued` - If false, begin returning a list of prepared, but not yet resolved transactions. If true, continue returning a list of prepared transactions, starting where the last call to this method left off.

  Returns:
    A list of prepared but not yet resolved transactions.
  Throws:
    `DatabaseException`

### panic

    public void panic(boolean onoff)
               throws DatabaseException

  Set the panic state for the database environment. Database environments in a panic state normally refuse all attempts to call library functions, throwing a `RunRecoveryException`.

  This method configures a database environment, including all threads of control accessing the database environment, not only the operations performed using a specified `Environment` handle.

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

  Parameters:
    `onoff` - If true, set the panic state for the database environment.
  Throws:
    `DatabaseException`

### getVersionString

    public static String getVersionString()

  Return the release version information, suitable for display.

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

  Returns:
    The release version information, suitable for display.

### getVersionMajor

    public static int getVersionMajor()

  Return the release major number.

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

  Returns:
    The release major number.

### getVersionMinor

    public static int getVersionMinor()

  Return the release minor number.

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

  Returns:
    The release minor number.

### getVersionPatch

    public static int getVersionPatch()

  Return the release patch number.

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

  Returns:
    The release patch number.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB version 4.3.29
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 1996-2004 Sleepycat Software, Inc. - All rights reserved.