|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.sleepycat.db.DbEnv
public class DbEnv
The DbEnv object is the handle for a Berkeley DB environment -- a collection including support for some or all of caching, locking, logging and transaction subsystems, as well as databases and log files. Methods off the DbEnv handle are used to configure the environment as well as to operate on subsystems and databases in the environment.
DbEnv handles are free-threaded if the Db.DB_THREAD
flag is specified to
the DbEnv.open
method when the
environment is opened. The DbEnv handle should not be closed while
any other handle remains open that is using it as a reference (for
example, Db
or DbTxn
). Once either the DbEnv.close
or DbEnv.remove
methods are called,
the handle may not be accessed again, regardless of the method's
return.
Nested Class Summary | |
---|---|
static class |
DbEnv.RepProcessMessage
|
Field Summary | |
---|---|
protected boolean |
swigCMemOwn
|
Constructor Summary | |
---|---|
protected |
DbEnv()
|
|
DbEnv(int flags)
The constructor creates the DbEnv object. |
protected |
DbEnv(long cPtr,
boolean cMemoryOwn)
|
Method Summary | |
---|---|
void |
close(int flags)
The DbEnv.close method closes the Berkeley DB environment, freeing any allocated resources and closing any underlying subsystems. |
void |
dbremove(DbTxn txnid,
java.lang.String file,
java.lang.String database,
int flags)
Deprecated. As of Berkeley DB 4.2, replaced by dbRemove(DbTxn,String,String,int) |
void |
dbRemove(DbTxn txnid,
java.lang.String file,
java.lang.String database,
int flags)
The DbEnv.dbRemove method removes the database specified by the file and database parameters. |
void |
dbrename(DbTxn txnid,
java.lang.String file,
java.lang.String database,
java.lang.String newname,
int flags)
Deprecated. As of Berkeley DB 4.2, replaced by dbRename(DbTxn,String,String,String,int) |
void |
dbRename(DbTxn txnid,
java.lang.String file,
java.lang.String database,
java.lang.String newname,
int flags)
The DbEnv.dbRename method renames the database specified by the file and database parameters to newname . |
protected void |
delete()
|
void |
err(int error,
java.lang.String message)
The DbEnv.err, DbEnv.errx, Db.err and Db.errx methods
provide error-messaging functionality for applications written
using the Berkeley DB library. |
void |
errx(java.lang.String message)
The DbEnv.errx and Db.errx
methods perform identically to the DbEnv.err and Db.err methods, except that they do
not append the final separator characters and standard error
string to the error message. |
int |
get_cachesize_ncache()
Deprecated. As of Berkeley DB 4.2, replaced by getCacheSizeNcache() |
long |
get_cachesize()
Deprecated. As of Berkeley DB 4.2, replaced by getCacheSize() |
java.lang.String[] |
get_data_dirs()
Deprecated. As of Berkeley DB 4.2, replaced by getDataDirs() |
int |
get_encrypt_flags()
Deprecated. As of Berkeley DB 4.2, replaced by getEncryptFlags() |
java.lang.String |
get_errpfx()
Deprecated. As of Berkeley DB 4.2, replaced by getErrorPrefix() |
int |
get_flags()
Deprecated. As of Berkeley DB 4.2, replaced by getFlags() |
java.lang.String |
get_home()
Deprecated. As of Berkeley DB 4.2, replaced by getDbEnvHome() |
int |
get_lg_bsize()
Deprecated. As of Berkeley DB 4.2, replaced by getLogBufferSize() |
java.lang.String |
get_lg_dir()
Deprecated. As of Berkeley DB 4.2, replaced by getLogDir() |
int |
get_lg_max()
Deprecated. As of Berkeley DB 4.2, replaced by getLogMax() |
int |
get_lg_regionmax()
Deprecated. As of Berkeley DB 4.2, replaced by getLogRegionMax() |
byte[][] |
get_lk_conflicts()
Deprecated. As of Berkeley DB 4.2, replaced by getLockConflicts() |
int |
get_lk_detect()
Deprecated. As of Berkeley DB 4.2, replaced by getLockDetect() |
int |
get_lk_max_lockers()
Deprecated. As of Berkeley DB 4.2, replaced by getLockMaxLockers() |
int |
get_lk_max_locks()
Deprecated. As of Berkeley DB 4.2, replaced by getLockMaxLocks() |
int |
get_lk_max_objects()
Deprecated. As of Berkeley DB 4.2, replaced by getLockMaxObjects() |
long |
get_mp_mmapsize()
Deprecated. As of Berkeley DB 4.2, replaced by getMemoryPoolMapSize() |
int |
get_open_flags()
Deprecated. As of Berkeley DB 4.2, replaced by getOpenFlags() |
long |
get_rep_limit()
Deprecated. As of Berkeley DB 4.2, replaced by getReplicationLimit() |
long |
get_shm_key()
Deprecated. As of Berkeley DB 4.2, replaced by getSegmentId() |
int |
get_tas_spins()
Deprecated. As of Berkeley DB 4.2, replaced by getTestAndSetSpins() |
long |
get_timeout(int flag)
Deprecated. As of Berkeley DB 4.2, replaced by getTimeout(int) |
java.lang.String |
get_tmp_dir()
Deprecated. As of Berkeley DB 4.2, replaced by getTmpDir() |
int |
get_tx_max()
Deprecated. As of Berkeley DB 4.2, replaced by getTxnMax() |
long |
get_tx_timestamp()
Deprecated. As of Berkeley DB 4.2, replaced by getTxnTimestamp() |
boolean |
get_verbose(int which)
Deprecated. As of Berkeley DB 4.2, replaced by getVerbose(int) |
static int |
get_version_major()
Deprecated. As of Berkeley DB 4.2, replaced by getVersionMajor() |
static int |
get_version_minor()
Deprecated. As of Berkeley DB 4.2, replaced by getVersionMinor() |
static int |
get_version_patch()
Deprecated. As of Berkeley DB 4.2, replaced by getVersionPatch() |
static java.lang.String |
get_version_string()
Deprecated. As of Berkeley DB 4.2, replaced by getVersionString() |
long |
getCacheSize()
The DbEnv.getCacheSize method returns the size of the cache. |
int |
getCacheSizeNcache()
The DbEnv.getCacheSizeNcache method returns the number of caches. |
protected static long |
getCPtr(DbEnv obj)
|
java.lang.String[] |
getDataDirs()
The DbEnv.getDataDirs method returns the array of directories. |
java.lang.String |
getDbEnvHome()
The DbEnv.getDbEnvHome method returns the database environment home directory. |
int |
getEncryptFlags()
The DbEnv.getEncryptFlags method returns the encryption flags. |
java.lang.String |
getErrorPrefix()
The DbEnv.getErrorPrefix method returns the error prefix. |
int |
getFlags()
The DbEnv.getFlags method returns the configuration flags. |
byte[][] |
getLockConflicts()
The DbEnv.getLockConflicts method returns the conflicts array. |
int |
getLockDetect()
The DbEnv.getLockDetect method returns the deadlock detector configuration. |
int |
getLockMaxLockers()
The DbEnv.getLockMaxLockers method returns the maximum number of lockers. |
int |
getLockMaxLocks()
The DbEnv.setLockMaxLocks method returns the maximum number of locks. |
int |
getLockMaxObjects()
The DbEnv.getLockMaxObjects method returns the maximum number of locked objects. |
int |
getLogBufferSize()
The DbEnv.getLogBufferSize method returns the size of the log buffer, in bytes. |
java.lang.String |
getLogDir()
The DbEnv.getLogDir method returns the log directory. |
int |
getLogMax()
The DbEnv.getLogMax method returns the maximum log file size. |
int |
getLogRegionMax()
The DbEnv.getLogRegionMax method returns the size of the underlying logging subsystem region. |
long |
getMemoryPoolMapSize()
The DbEnv.getMemoryPoolMapSize method returns the maximum file map size. |
int |
getOpenFlags()
The DbEnv.getOpenFlags method returns the open method flags. |
long |
getReplicationLimit()
The DbEnv.getReplicationLimit method returns the transmit limit in bytes. |
long |
getSegmentId()
The DbEnv.getSegmentId method returns the base segment ID. |
int |
getTestAndSetSpins()
The DbEnv.getTestAndSetSpins method returns the test-and-set spin count. |
long |
getTimeout(int flag)
The DbEnv.getTimeout method returns a timeout value, in microseconds. |
java.lang.String |
getTmpDir()
The DbEnv.getTmpDir method returns the database environment temporary file directory. |
int |
getTxnMax()
The DbEnv.getTxnMax method returns the number of active transactions. |
long |
getTxnTimestamp()
The DbEnv.getTxnTimestamp method returns the recovery timestamp. |
boolean |
getVerbose(int which)
The DbEnv.getVerbose method returns whether the specified which parameter is currently set or not. |
static int |
getVersionMajor()
The DbEnv.getVersionMajor method returns the release major number. |
static int |
getVersionMinor()
The DbEnv.getVersionMinor method returns the release minor number. |
static int |
getVersionPatch()
The DbEnv.getVersionPatch method returns the release patch number. |
static java.lang.String |
getVersionString()
The DbEnv.getVersionString method returns the release verbose version information, suitable for display. |
int |
lock_detect(int flags,
int atype)
Deprecated. As of Berkeley DB 4.2, replaced by lockDetect(int,int) |
DbLock |
lock_get(int locker,
int flags,
Dbt object,
int lock_mode)
Deprecated. As of Berkeley DB 4.2, replaced by lockGet(int,int,Dbt,int) |
void |
lock_id_free(int id)
Deprecated. As of Berkeley DB 4.2, replaced by lockIdFree(int) |
int |
lock_id()
Deprecated. As of Berkeley DB 4.2, replaced by lockId() |
void |
lock_put(DbLock lock)
Deprecated. As of Berkeley DB 4.2, replaced by lockPut(DbLock) |
DbLockStat |
lock_stat(int flags)
Deprecated. As of Berkeley DB 4.2, replaced by lockStat(int) |
void |
lock_vec(int locker,
int flags,
DbLockRequest[] list,
int offset,
int count)
Deprecated. As of Berkeley DB 4.2, replaced by lockVector(int,int,DbLockRequest[],int,int) |
int |
lockDetect(int flags,
int atype)
The DbEnv.lockDetect method runs one iteration of the deadlock detector. |
DbLock |
lockGet(int locker,
int flags,
Dbt object,
int lock_mode)
The DbEnv.lockGet method acquires a lock from the lock table, returning information about it in a DbLock object. |
int |
lockId()
The DbEnv.lockId method returns a locker ID, which is guaranteed to be unique in the specified lock table. |
void |
lockIdFree(int id)
The DbEnv.lockIdFree method frees a locker ID allocated by the DbEnv.lockId method. |
void |
lockPut(DbLock lock)
The DbEnv.lockPut method releases lock . |
DbLockStat |
lockStat(int flags)
The DbEnv.lockStat method returns the locking subsystem statistics. |
void |
lockVector(int locker,
int flags,
DbLockRequest[] list,
int offset,
int count)
The DbEnv.lockVector method atomically obtains and releases one or more locks from the lock table. |
java.lang.String[] |
log_archive(int flags)
Deprecated. As of Berkeley DB 4.2, replaced by logArchive(int) |
static int |
log_compare(DbLsn lsn0,
DbLsn lsn1)
Deprecated. As of Berkeley DB 4.2, replaced by logCompare(DbLsn,DbLsn) |
DbLogc |
log_cursor(int flags)
Deprecated. As of Berkeley DB 4.2, replaced by logCursor(int) |
java.lang.String |
log_file(DbLsn lsn)
Deprecated. As of Berkeley DB 4.2, replaced by logFile(DbLsn) |
void |
log_flush(DbLsn lsn)
Deprecated. As of Berkeley DB 4.2, replaced by logFlush(DbLsn) |
void |
log_put(DbLsn lsn,
Dbt data,
int flags)
Deprecated. As of Berkeley DB 4.2, replaced by logPut(DbLsn,Dbt,int) |
DbLogStat |
log_stat(int flags)
Deprecated. As of Berkeley DB 4.2, replaced by logStat(int) |
java.lang.String[] |
logArchive(int flags)
The DbEnv.logArchive method returns an array of log or database filenames. |
static int |
logCompare(DbLsn lsn0,
DbLsn lsn1)
The DbEnv.logCompare method allows the caller to compare two DbLsn objects, returning 0 if
they are equal, 1 if lsn0 is greater than lsn1 ,
and -1 if lsn0 is less than lsn1 . |
DbLogc |
logCursor(int flags)
The DbEnv.logCursor method returns a created log cursor. |
java.lang.String |
logFile(DbLsn lsn)
The DbEnv.logFile method maps DbLsn objects to filenames, returning the name of the file
containing the record named by lsn . |
void |
logFlush(DbLsn lsn)
The DbEnv.logFlush method writes log records to disk. |
void |
logPut(DbLsn lsn,
Dbt data,
int flags)
The DbEnv.logPut method appends records to the log. |
DbLogStat |
logStat(int flags)
The DbEnv.logStat method returns the logging subsystem statistics. |
DbMpoolFStat[] |
memoryPoolFileStat(int flags)
The DbEnv.memoryPoolFileStat method creates an array of DbMpoolFStat objects containing statistics for individual files in the cache. |
DbMpoolStat |
memoryPoolStat(int flags)
The DbEnv.memoryPoolStat method returns the memory pool (that is, the buffer cache) subsystem statistics. |
int |
memoryPoolTrickle(int percent)
The DbEnv.memoryPoolTrickle method ensures that a specified percent of the pages in the shared memory pool are clean, by writing dirty pages to their backing files. |
DbMpoolFStat[] |
memp_fstat(int flags)
Deprecated. As of Berkeley DB 4.2, replaced by memoryPoolFileStat(int) |
DbMpoolStat |
memp_stat(int flags)
Deprecated. As of Berkeley DB 4.2, replaced by memoryPoolStat(int) |
int |
memp_trickle(int percent)
Deprecated. As of Berkeley DB 4.2, replaced by memoryPoolTrickle(int) |
void |
open(java.lang.String db_home,
int flags,
int mode)
The DbEnv.open method opens a Berkeley DB environment. |
void |
remove(java.lang.String db_home,
int flags)
The DbEnv.remove method destroys a Berkeley DB environment if it is not currently in use. |
int |
rep_elect(int nsites,
int priority,
int timeout)
Deprecated. As of Berkeley DB 4.2, replaced by replicationElect(int,int,int) |
int |
rep_process_message(Dbt control,
Dbt rec,
DbEnv.RepProcessMessage envid,
DbLsn ret_lsn)
Deprecated. As of Berkeley DB 4.2, replaced by replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn) |
void |
rep_start(Dbt cdata,
int flags)
Deprecated. As of Berkeley DB 4.2, replaced by replicationStart(Dbt,int) |
DbRepStat |
rep_stat(int flags)
Deprecated. As of Berkeley DB 4.2, replaced by replicationStat(int) |
int |
replicationElect(int nsites,
int priority,
int timeout)
The DbEnv.replicationElect method holds an election for the master of a replication group. |
int |
replicationProcessMessage(Dbt control,
Dbt rec,
DbEnv.RepProcessMessage envid,
DbLsn ret_lsn)
The DbEnv.replicationProcessMessage method processes an incoming replication message sent by a member of the replication group to the local database environment. |
void |
replicationStart(Dbt cdata,
int flags)
The DbEnv.replicationStart method configures the database environment as a client or master in a group of replicated database environments. |
DbRepStat |
replicationStat(int flags)
The DbEnv.replicationStat method returns the replication subsystem statistics. |
void |
set_app_dispatch(DbAppDispatch tx_recover)
Deprecated. As of Berkeley DB 4.2, replaced by setAppDispatch(DbAppDispatch) |
void |
set_cachesize(int gbytes,
int bytes,
int ncache)
Deprecated. Replaced in Berkeley DB 4.2 by setCacheSize(long,int) |
void |
set_cachesize(long bytes,
int ncache)
Deprecated. As of Berkeley DB 4.2, replaced by setCacheSize(long,int) |
void |
set_data_dir(java.lang.String dir)
Deprecated. As of Berkeley DB 4.2, replaced by setDataDir(String) |
void |
set_encrypt(java.lang.String passwd,
int flags)
Deprecated. As of Berkeley DB 4.2, replaced by setEncrypted(String,int) |
void |
set_errcall(DbErrcall db_errcall_fcn)
Deprecated. Replaced in Berkeley DB 4.2 by setErrorHandler(DbErrorHandler) |
void |
set_error_stream(java.io.OutputStream stream)
Deprecated. As of Berkeley DB 4.2, replaced by setErrorStream(java.io.OutputStream) |
void |
set_errpfx(java.lang.String errpfx)
Deprecated. As of Berkeley DB 4.2, replaced by setErrorPrefix(String) |
void |
set_feedback(DbEnvFeedback feedback)
Deprecated. Replaced in Berkeley DB 4.2 by setFeedbackHandler(DbEnvFeedbackHandler) |
void |
set_flags(int flags,
boolean onoff)
Deprecated. As of Berkeley DB 4.2, replaced by setFlags(int,boolean) |
void |
set_lg_bsize(int lg_bsize)
Deprecated. As of Berkeley DB 4.2, replaced by setLogBufferSize(int) |
void |
set_lg_dir(java.lang.String dir)
Deprecated. As of Berkeley DB 4.2, replaced by setLogDir(String) |
void |
set_lg_max(int lg_max)
Deprecated. As of Berkeley DB 4.2, replaced by setLogMax(int) |
void |
set_lg_regionmax(int lg_regionmax)
Deprecated. As of Berkeley DB 4.2, replaced by setLogRegionMax(int) |
void |
set_lk_conflicts(byte[][] conflicts)
Deprecated. As of Berkeley DB 4.2, replaced by setLockConflicts(byte[][]) |
void |
set_lk_detect(int detect)
Deprecated. As of Berkeley DB 4.2, replaced by setLockDetect(int) |
void |
set_lk_max_lockers(int max)
Deprecated. As of Berkeley DB 4.2, replaced by setLockMaxLockers(int) |
void |
set_lk_max_locks(int max)
Deprecated. As of Berkeley DB 4.2, replaced by setLockMaxLocks(int) |
void |
set_lk_max_objects(int max)
Deprecated. As of Berkeley DB 4.2, replaced by setLockMaxObjects(int) |
void |
set_mp_mmapsize(long mp_mmapsize)
Deprecated. As of Berkeley DB 4.2, replaced by setMemoryPoolMapSize(long) |
void |
set_rep_limit(int gbytes,
int bytes)
Deprecated. Replaced in Berkeley DB 4.2 by setReplicationLimit(long) |
void |
set_rep_limit(long bytes)
Deprecated. As of Berkeley DB 4.2, replaced by setReplicationLimit(long) |
void |
set_rep_transport(int envid,
DbRepTransport send)
Deprecated. As of Berkeley DB 4.2, replaced by setReplicationTransport(int,DbRepTransport) |
void |
set_rpc_server(DbClient client,
java.lang.String host,
long cl_timeout,
long sv_timeout,
int flags)
Deprecated. As of Berkeley DB 4.2, replaced by setRpcServer(DbClient,String,long,long,int) |
void |
set_shm_key(long shm_key)
Deprecated. As of Berkeley DB 4.2, replaced by setSegmentId(long) |
void |
set_tas_spins(int tas_spins)
Deprecated. As of Berkeley DB 4.2, replaced by setTestAndSetSpins(int) |
void |
set_timeout(long timeout,
int flags)
Deprecated. As of Berkeley DB 4.2, replaced by setTimeout(long,int) |
void |
set_tmp_dir(java.lang.String dir)
Deprecated. As of Berkeley DB 4.2, replaced by setTmpDir(String) |
void |
set_tx_max(int max)
Deprecated. As of Berkeley DB 4.2, replaced by setTxnMax(int) |
void |
set_tx_timestamp(java.util.Date timestamp)
Deprecated. As of Berkeley DB 4.2, replaced by setTxnTimestamp(java.util.Date) |
void |
set_verbose(int which,
boolean onoff)
Deprecated. As of Berkeley DB 4.2, replaced by setVerbose(int,boolean) |
void |
setAppDispatch(DbAppDispatch tx_recover)
|
void |
setCacheSize(long bytes,
int ncache)
Set the size of the shared memory buffer pool -- that is, the cache. |
void |
setDataDir(java.lang.String dir)
Set the path of a directory to be used as the location of the access method database files. |
void |
setEncrypted(java.lang.String passwd,
int flags)
Set the password used by the Berkeley DB library to perform encryption and decryption. |
void |
setErrorHandler(DbErrorHandler db_errcall_fcn)
When an error occurs in the Berkeley DB library, an exception is thrown. |
void |
setErrorPrefix(java.lang.String errpfx)
Set the prefix string that appears before error messages issued by Berkeley DB. |
void |
setErrorStream(java.io.OutputStream stream)
When an error occurs in the Berkeley DB library, an exception is thrown. |
void |
setFeedbackHandler(DbEnvFeedbackHandler db_feedback_fcn)
|
void |
setFlags(int flags,
boolean onoff)
Configure a database environment. |
void |
setLockConflicts(byte[][] conflicts)
Set the locking conflicts matrix. |
void |
setLockDetect(int detect)
Set if the deadlock detector is to be run whenever a lock conflict occurs, and specify what lock request(s) should be rejected. |
void |
setLockMaxLockers(int max)
Set the maximum number of locking entities supported by the Berkeley DB environment. |
void |
setLockMaxLocks(int max)
Set the maximum number of locks supported by the Berkeley DB environment. |
void |
setLockMaxObjects(int max)
Set the maximum number of locked objects supported by the Berkeley DB environment. |
void |
setLogBufferSize(int lg_bsize)
Set the size of the in-memory log buffer, in bytes. |
void |
setLogDir(java.lang.String dir)
The path of a directory to be used as the location of logging files. |
void |
setLogMax(int lg_max)
Set the maximum size of a single file in the log, in bytes. |
void |
setLogRegionMax(int lg_regionmax)
Set the size of the underlying logging area of the Berkeley DB environment, in bytes. |
void |
setMemoryPoolMapSize(long mp_mmapsize)
Files that are opened read-only in the pool (and that satisfy a few other criteria) are, by default, mapped into the process address space instead of being copied into the local cache. |
void |
setPanicHandler(DbPanicHandler db_panic_fcn)
|
void |
setReplicationLimit(long bytes)
The DbEnv.setReplicationLimit method imposes a byte-count limit on the amount of data that will be transmitted from a site in a single call to DbEnv.replicationProcessMessage method. |
void |
setReplicationTransport(int envid,
DbRepTransport send)
|
void |
setRpcServer(DbClient client,
java.lang.String host,
long cl_timeout,
long sv_timeout,
int flags)
Establishes a connection for this dbenv to a RPC server. |
void |
setSegmentId(long shm_key)
Specify a base segment ID for Berkeley DB environment shared memory regions created in system memory on VxWorks or systems supporting X/Open-style shared memory interfaces; for example, UNIX systems supporting shmget (2) and related System V IPC interfaces. |
void |
setTestAndSetSpins(int tas_spins)
Specify that test-and-set mutexes should spin tas_spins times without blocking. |
void |
setTimeout(long timeout,
int flags)
The DbEnv.setTimeout method sets timeout values for locks or transactions in the database environment. |
void |
setTmpDir(java.lang.String dir)
Specify the path of a directory to be used as the location of temporary files. |
void |
setTxnMax(int max)
Configure the Berkeley DB database environment to support at least max active transactions. |
void |
setTxnTimestamp(java.util.Date timestamp)
Recover to the time specified by timestamp rather than to the most current possible date. |
void |
setVerbose(int which,
boolean onoff)
The DbEnv.setVerbose method turns specific additional informational and debugging messages in the Berkeley DB message output on and off. |
static java.lang.String |
strerror(int error)
The DbEnv.strerror method returns an error message string corresponding to the error number error parameter. |
DbTxn |
txn_begin(DbTxn parent,
int flags)
Deprecated. As of Berkeley DB 4.2, replaced by txnBegin(DbTxn,int) |
void |
txn_checkpoint(int kbyte,
int min,
int flags)
Deprecated. As of Berkeley DB 4.2, replaced by txnCheckpoint(int,int,int) |
DbPreplist[] |
txn_recover(int count,
int flags)
Deprecated. As of Berkeley DB 4.2, replaced by txnRecover(int,int) |
DbTxnStat |
txn_stat(int flags)
Deprecated. As of Berkeley DB 4.2, replaced by txnStat(int) |
DbTxn |
txnBegin(DbTxn parent,
int flags)
The DbEnv.txnBegin method creates a new transaction in the environment and returns a DbTxn
that uniquely identifies it. |
void |
txnCheckpoint(int kbyte,
int min,
int flags)
The DbEnv.txnCheckpoint method flushes the underlying memory pool, writes a checkpoint record to the log, and then flushes the log. |
DbPreplist[] |
txnRecover(int count,
int flags)
The DbEnv.txnRecover method returns a list of prepared but not yet resolved transactions. |
DbTxnStat |
txnStat(int flags)
The DbEnv.txnStat method returns the transaction subsystem statistics. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
protected boolean swigCMemOwn
Constructor Detail |
---|
protected DbEnv(long cPtr, boolean cMemoryOwn)
protected DbEnv()
public DbEnv(int flags) throws DbException
DbEnv.close
or DbEnv.remove
methods will free
that memory.
flags
- The following flags value may be
specified:
Db.DB_RPCCLIENT
Create a client environment to connect to a server.
The Db.DB_RPCCLIENT
flag indicates to the
system that this environment is remote on a server. The
use of this flag causes the environment methods to use
functions that call a server instead of local functions.
Prior to making any environment or database method
calls, the application must call the DbEnv.setRpcServer
function to establish the connection to the server.
DbException
- Signals that an exception of some sort
has occurred.Method Detail |
---|
protected void delete()
protected static long getCPtr(DbEnv obj)
public void close(int flags) throws DbException
The DbEnv
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 Db
,
Dbc
, DbTxn
, DbLogc
and DbMpoolFile
handles.
Where the environment was initialized with the Db.DB_INIT_LOCK
flag,
calling DbEnv.close does not release any locks still held by
the closing process, providing functionality for long-lived
locks.
Where the environment was initialized with the Db.DB_INIT_TXN
flag, calling
DbEnv.close aborts any unresolved transactions. Applications
should not depend on this behavior for transactions involving
Berkeley DB 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 calling
DbEnv.close, it will not be possible to abort the transaction,
and recovery will have to be run on the Berkeley DB
environment before further operations are done.
Where log cursors were created using the DbEnv.logCursor
method,
calling DbEnv.close does not imply closing those cursors.
In multithreaded applications, only a single thread may call DbEnv.close.
After DbEnv.close has been called, regardless of its return, the Berkeley DB environment handle may not be accessed again.
flags
- currently unused, and must be set to 0.
DbException
- Signals that an exception of some sort
has occurred.public void lock_vec(int locker, int flags, DbLockRequest[] list, int offset, int count) throws DbException
lockVector(int,int,DbLockRequest[],int,int)
DbException
public void lockVector(int locker, int flags, DbLockRequest[] list, int offset, int count) throws DbException
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 DbEnv.lockVector throws an exception
flags
- must be set to 0 or the
following value:
Db.DB_LOCK_NOWAIT
If a lock cannot be granted because the requested lock
conflicts with an existing lock, throw a DbLockNotGrantedException
immediately instead of
waiting for the lock to become available. In this case,
the index of the request that was not granted can be
found by calling DbLockNotGrantedException.get_index.
locker
- an unsigned 32-bit integer
quantity. It represents the entity requesting or releasing
the lock.list
- The list array
provided to DbEnv.lockVector is a set of DbLockRequest
objects. Only count elements of list
starting at offset are considered by
DbEnv.lockVector. A DbLockRequest object has at least the
following fields: A DB_LOCKREQ structure has at least the following fields:
The operation to be performed, which must be set to one of the following values:
Db.DB_LOCK_GET
Get the lock defined by the values of the mode
and obj structure fields, for the specified
locker . Upon return from DbEnv.lockVector, if the
lock field is non-null, a reference to the
acquired lock is stored there. (This reference is
invalidated by any call to DbEnv.lockVector or DbEnv.lockPut
that
releases the lock.)
Db.DB_LOCK_GET_TIMEOUT
Identical to Db.DB_LOCK_GET
except that the
value in the timeout structure field overrides
any previously specified timeout value for this lock. A
value of 0 turns off any previously specified timeout.
Db.DB_LOCK_PUT
The lock to which the lock structure field refers is released. The locker parameter, and mode and obj fields are ignored.
Db.DB_LOCK_PUT_ALL
All locks held by the specified locker are
released. The lock , mode , and obj
structure fields are ignored. Locks acquired in
operations performed by the current call to
DbEnv.lockVector which appear before the Db.DB_LOCK_PUT_ALL
operation are released; those acquired in operations
appearing after the Db.DB_LOCK_PUT_ALL
operation are not released.
Db.DB_LOCK_PUT_OBJ
All locks held on obj are released. The locker
parameter and the lock and mode
structure fields are ignored. Locks acquired in
operations performed by the current call to
DbEnv.lockVector that appear before the Db.DB_LOCK_PUT_OBJ
operation are released; those acquired in operations
appearing after the Db.DB_LOCK_PUT_OBJ
operation are not released.
Db.DB_LOCK_TIMEOUT
Cause the specified locker to timeout immediately. If the database environment has not configured automatic deadlock detection, the transaction will timeout the next time deadlock detection is performed. As transactions acquire locks on behalf of a single locker ID, timing out the locker ID associated with a transaction will time out the transaction itself.
The lock mode, used as an index into the environment's lock conflict matrix. When using the default lock conflict matrix, mode must be set to one of the following values:
Db.DB_LOCK_READ
read (shared)
Db.DB_LOCK_WRITE
write (exclusive)
Db.DB_LOCK_IWRITE
intention to write (shared)
Db.DB_LOCK_IREAD
intention to read (shared)
Db.DB_LOCK_IWR
intention to read and write (shared)
DbEnv.setLockConflicts
and Standard Lock
Modes for more information on the lock conflict
matrix. An untyped byte string that specifies the object to be locked or released. 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. See Access method locking conventions for more information.
The lock timeout value.
DbDeadlockException
- If a transactional database
environment operation was selected to resolve a deadlock,
the DbEnv.lockVector method will fail and throw a DbDeadlockException
exception.
DbLockNotGrantedException
- If a Berkeley DB Concurrent
Data Store database environment configured for lock
timeouts was unable to grant a lock in the allowed time,
the DbEnv.lockVector method will fail and throw a DbLockNotGrantedException
exception.
DbLockNotGrantedException
- If the Db.DB_LOCK_NOWAIT
flag
or lock timers were configured and the lock could not be
granted before the wait-time expired, the DbEnv.lockVector
method will fail and throw a DbLockNotGrantedException
exception.
java.lang.IllegalArgumentException
- The DbEnv.lockVector method
will fail and throw a IllegalArgumentException exception
if an invalid flag value or parameter was specified.
DbMemoryException
- If the maximum number of
locks has been reached, the DbEnv.lockVector method will
fail and throw a DbMemoryException
exception.
DbException
public void open(java.lang.String db_home, int flags, int mode) throws DbException, java.io.FileNotFoundException
db_home
- the database environment's
home directory. For more information on db_home ,
and filename resolution in general, see Berkeley DB File
Naming . The environment variable DB_HOME may
be used as the path of the database home, as described in
Berkeley DB
File Naming .flags
- specifies the subsystems
that are initialized and how the application's environment
affects Berkeley DB file naming, among other things. The
flags parameter must be set to 0 or by bitwise
inclusively OR 'ing together one or more of the
following values: Because there are a large number of flags that can be specified, they have been grouped together by functionality. The first group of flags indicates which of the Berkeley DB subsystems should be initialized:
Db.DB_JOINENV
Join an existing environment. This option allows applications to join an existing environment without knowing which Berkeley DB subsystems the environment supports.
Db.DB_INIT_CDB
Initialize locking for the Berkeley DB
Concurrent Data Store product. In this mode,
Berkeley DB provides multiple reader/single writer
access. The only other subsystem that should be
specified with the Db.DB_INIT_CDB
flag is
Db.DB_INIT_MPOOL
.
Db.DB_INIT_LOCK
Initialize the locking subsystem. This subsystem should
be used when multiple processes or threads are going to
be reading and writing a Berkeley DB database, so that
they do not interfere with each other. If all threads
are accessing the database(s) read-only, locking is
unnecessary. When the Db.DB_INIT_LOCK
flag
is specified, it is usually necessary to run a deadlock
detector, as well. See
db_deadlock and DbEnv.lockDetect
for
more information.
Db.DB_INIT_LOG
Initialize the logging subsystem. This subsystem should be used when recovery from application or system failure is necessary. If the log region is being created and log files are already present, the log files are reviewed; subsequent log writes are appended to the end of the log, rather than overwriting current log entries.
Db.DB_INIT_MPOOL
Initialize the shared memory buffer pool subsystem. This subsystem should be used whenever an application is using any Berkeley DB access method.
Db.DB_INIT_REP
Initialize the replication subsystem. This subsystem
should be used whenever an application plans on using
replication. The Db.DB_INIT_REP
flag
requires the Db.DB_INIT_TXN
and Db.DB_INIT_LOCK
flags also be configured.
Db.DB_INIT_TXN
Initialize the transaction subsystem. This subsystem
should be used when recovery and atomicity of multiple
operations are important. The Db.DB_INIT_TXN
flag implies the Db.DB_INIT_LOG
flag.
Db.DB_RECOVER
Run normal recovery on this environment before opening
it for normal use. If this flag is set, the Db.DB_CREATE
flag must also be set because the regions will be
removed and re-created.
Db.DB_RECOVER_FATAL
Run catastrophic recovery on this environment before
opening it for normal use. If this flag is set, the
Db.DB_CREATE
flag must also be set because
the regions will be removed and re-created.
All Berkeley DB recovery processing must be single-threaded; that is, only a single thread of control may perform recovery or access a Berkeley DB environment while recovery is being performed. Because it is not an error to specify Db.DB_RECOVER for an environment for which no recovery is required, it is reasonable programming practice for the thread of control responsible for performing recovery and creating the environment to always specify the Db.DB_CREATE and Db.DB_RECOVER flags during startup.
The DbEnv.open function returns successfully if Db.DB_RECOVER or Db.DB_RECOVER_FATAL is specified and no log files exist, so it is necessary to ensure that all necessary log files are present before running recovery. For further information, consult db_archive and db_recover .
The third group of flags govern file-naming extensions in the environment:
Db.DB_USE_ENVIRON
The Berkeley DB process' environment may be permitted to
specify information to be used when naming files; see Berkeley DB
File Naming . Because permitting users to specify
which files are used can create security problems,
environment information will be used in file naming for
all users only if the Db.DB_USE_ENVIRON
flag is set.
Db.DB_USE_ENVIRON_ROOT
The Berkeley DB process' environment may be permitted to
specify information to be used when naming files; see Berkeley DB
File Naming . Because permitting users to specify
which files are used can create security problems, if
the Db.DB_USE_ENVIRON_ROOT
flag is set,
environment information will be used for file naming
only for users with appropriate permissions (for
example, users with a user-ID of 0 on UNIX systems).
Db.DB_CREATE
Cause Berkeley DB subsystems to create any underlying files, as necessary.
Db.DB_LOCKDOWN
Lock shared Berkeley DB environment files and memory-mapped databases into memory.
Db.DB_PRIVATE
Specify that the environment will only be accessed by a single process (although that process may be multithreaded). This flag has two effects on the Berkeley DB environment. First, all underlying data structures are allocated from per-process memory instead of from shared memory that is potentially accessible to more than a single process. Second, mutexes are only configured to work between threads.
This flag should not be specified if more than a single
process is accessing the environment because it is
likely to cause database corruption and unpredictable
behavior. For example, if both a server application and
the Berkeley DB utility db_stat
are expected to access the environment, the Db.DB_PRIVATE
flag should not be specified.
Db.DB_SYSTEM_MEM
Allocate memory from system shared memory instead of from memory backed by the filesystem. See Shared Memory Regions for more information.
Db.DB_THREAD
Cause the DbEnv
handle
returned by DbEnv.open to be free-threaded ; that
is, usable by multiple threads within a single address
space.
Threading is always assumed in the Java API, so no
special flags are required and Berkeley DB functions
will always behave as if the Db.DB_THREAD
flag was specified.
mode
- On UNIX systems or in
IEEE/ANSI Std 1003.1 (POSIX) environments, all files
created by Berkeley DB are created with mode mode
(as described in chmod (2)) and modified by the
process' umask value at the time of creation (see umask
(2)). If mode is 0, Berkeley DB will use a
default mode of readable and writable by both owner and
group. On Windows systems, the mode parameter is ignored.
The group ownership of created files is based on the
system and directory defaults, and is not further
specified by Berkeley DB.
DbException
- The DbEnv.open method may
fail and throw DbException
, encapsulating one of the following non-zero
errors:
java.lang.IllegalArgumentException
- The DbEnv.open method will
fail and throw a IllegalArgumentException exception if the
Db.DB_THREAD flag was specified and fast mutexes are not
available for this architecture; The DB_HOME or TMPDIR
environment variables were set, but empty; An incorrectly
formatted NAME VALUE entry or line was found; or if
an invalid flag value or parameter was specified.
FileNotFoundException
- If the file or directory
does not exist, the DbEnv.open method will fail and throw
a FileNotFoundException exception.public void remove(java.lang.String db_home, int flags) throws DbException, java.io.FileNotFoundException
If there are processes that have called DbEnv.open
without calling DbEnv.close
(that is, there are
processes currently using the environment), DbEnv.remove will
fail without further action unless the Db.DB_FORCE
flag is set, in
which case DbEnv.remove will attempt to remove the
environment, 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 (2) 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 DbEnv.remove should not be necessary for most
applications because the Berkeley DB environment is cleaned up
as part of normal database recovery procedures. However,
applications may want to call DbEnv.remove as part of
application shut down to free up system resources. For
example, if the Db.DB_SYSTEM_MEM
flag was specified to DbEnv.open
, it may be useful to
call DbEnv.remove 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 DbEnv.remove 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 DbEnv.remove.
A DbEnv
handle that has already
been used to open an environment should not be used to call
the DbEnv.remove method; a new DbEnv
handle should be created for that purpose.
After DbEnv.remove has been called, regardless of its return, the Berkeley DB environment handle may not be accessed again.
db_home
- The db_home parameter
names the database environment to be removed.flags
- must be set to 0 or by bitwise
inclusively OR 'ing together one or more of the
following values:
Db.DB_FORCE
If the
flag is set, the environment is removed, regardless of
any processes that may still using it, and no locks are
acquired during this process. (Generally, the Db.DB_FORCE
flag 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 lock.)
Db.DB_FORCE
Db.DB_USE_ENVIRON
The Berkeley DB process' environment may be permitted to
specify information to be used when naming files; see Berkeley DB
File Naming . Because permitting users to specify
which files are used can create security problems,
environment information will be used in file naming for
all users only if the Db.DB_USE_ENVIRON
flag is set.
Db.DB_USE_ENVIRON_ROOT
The Berkeley DB process' environment may be permitted to
specify information to be used when naming files; see Berkeley DB
File Naming . Because permitting users to specify
which files are used can create security problems, if
the Db.DB_USE_ENVIRON_ROOT
flag is set,
environment information will be used for file naming
only for users with appropriate permissions (for
example, users with a user-ID of 0 on UNIX systems).
DbException
- The DbEnv.remove method may
fail and throw DbException
, encapsulating one of the following non-zero
errors:
FileNotFoundException
- If the file or directory does
not exist, the DbEnv.remove method will fail and throw a
FileNotFoundException exception.public void set_cachesize(int gbytes, int bytes, int ncache) throws DbException
setCacheSize(long,int)
DbException
public java.lang.String get_errpfx()
getErrorPrefix()
public java.lang.String getErrorPrefix()
The DbEnv.getErrorPrefix method may be called at any time during the life of the application.
public void set_errcall(DbErrcall db_errcall_fcn) throws DbException
setErrorHandler(DbErrorHandler)
DbException
public void set_error_stream(java.io.OutputStream stream)
setErrorStream(java.io.OutputStream)
public void setErrorStream(java.io.OutputStream stream)
The DbEnv.setErrorStream and Db.setErrorStream
methods
are used to enhance the mechanism for reporting error messages
to the application by setting a OutputStream to be used for
displaying additional Berkeley DB error messages. In some
cases, when an error occurs, Berkeley DB will output an
additional error message to the specified stream.
The error message will consist of the prefix string and a
colon (": ") (if a prefix string was previously
specified using DbEnv.setErrorPrefix
), an error string, and a trailing
<newline> character.
Alternatively, you can use the DbEnv.setErrorHandler
method to capture the additional error information in a way
that does not use output streams. You should not mix these
approaches.
This error-logging enhancement does not slow performance or significantly increase application size, and may be run during normal operation as well as during application debugging.
stream
- the application-specified output stream to be
used for additional error information.public void set_errpfx(java.lang.String errpfx)
setErrorPrefix(String)
public void setErrorPrefix(java.lang.String errpfx)
The DbEnv.setErrorPrefix method may be called at any time during the life of the application.
errpfx
- the application-specified error prefix for
additional error messages.public void set_feedback(DbEnvFeedback feedback) throws DbException
setFeedbackHandler(DbEnvFeedbackHandler)
DbException
public void set_rep_limit(int gbytes, int bytes) throws DbException
setReplicationLimit(long)
DbException
public void set_tx_timestamp(java.util.Date timestamp) throws DbException
setTxnTimestamp(java.util.Date)
DbException
public void setTxnTimestamp(java.util.Date timestamp) throws DbException
Once a database environment has been upgraded to a new version of Berkeley DB involving a log format change (see Upgrading Berkeley DB installations ), it is no longer possible to recover to a specific time before that upgrade.
The DbEnv.setTxnTimestamp method configures operations
performed using the specified DbEnv
handle, not all operations performed on the underlying
database environment.
The DbEnv.setTxnTimestamp method may not be called after the
DbEnv.open
method is
called.
timestamp
- references the memory
location where the recovery timestamp is located. Note that only the seconds (not the milliseconds) of the timestamp are used
java.lang.IllegalArgumentException
- The DbEnv.setTxnTimestamp
method will fail and throw a IllegalArgumentException
exception if it is not possible to recover to the
specified time using the log files currently present in
the environment; or if an invalid flag value or parameter
was specified.
DbException
public void dbremove(DbTxn txnid, java.lang.String file, java.lang.String database, int flags) throws DbException, DbDeadlockException, DbLockNotGrantedException, java.io.FileNotFoundException
dbRemove(DbTxn,String,String,int)
DbException
DbDeadlockException
DbLockNotGrantedException
java.io.FileNotFoundException
public void dbRemove(DbTxn txnid, java.lang.String file, java.lang.String database, int flags) throws DbException, DbDeadlockException, DbLockNotGrantedException, java.io.FileNotFoundException
Applications should never remove databases with open Db
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 will fail.
The environment variable DB_HOME may be used as the path of the database environment home.
DbEnv.dbRemove is affected by any database directory specified
using the DbEnv.setDataDir
method, or by setting the "set_data_dir"
string in the environment's DB_CONFIG file.
database
- the database to be removed.file
- the physical file which
contains the database(s) to be removed.flags
- must be set to 0 or the
following value:
Db.DB_AUTO_COMMIT
Enclose the DbEnv.dbRemove call within a transaction. If the call succeeds, changes made by the operation will be recoverable. If the call fails, the operation will have made no changes.
txnid
- If the operation is to be
transaction-protected, the txnid parameter is a
transaction handle returned from DbEnv.txnBegin
;
otherwise, null.
DbException
- The DbEnv.dbRemove method
may fail and throw DbException
, encapsulating one of the following non-zero
errors:
DbDeadlockException
- If a transactional database
environment operation was selected to resolve a deadlock,
the DbEnv.dbRemove method will fail and throw a DbDeadlockException
exception.
DbLockNotGrantedException
- If a Berkeley DB Concurrent
Data Store database environment configured for lock
timeouts was unable to grant a lock in the allowed time,
the DbEnv.dbRemove method will fail and throw a DbLockNotGrantedException
exception.
java.lang.IllegalArgumentException
- The DbEnv.dbRemove method
will fail and throw a IllegalArgumentException exception
if DbEnv.dbRemove called before DbEnv.open
was called; or if
an invalid flag value or parameter was specified.
FileNotFoundException
- If the file or directory
does not exist, the DbEnv.dbRemove method will fail and
throw a FileNotFoundException exception.public void dbrename(DbTxn txnid, java.lang.String file, java.lang.String database, java.lang.String newname, int flags) throws DbException, DbDeadlockException, DbLockNotGrantedException, java.io.FileNotFoundException
dbRename(DbTxn,String,String,String,int)
DbException
DbDeadlockException
DbLockNotGrantedException
java.io.FileNotFoundException
public void dbRename(DbTxn txnid, java.lang.String file, java.lang.String database, java.lang.String newname, int flags) throws DbException, DbDeadlockException, DbLockNotGrantedException, java.io.FileNotFoundException
Applications should not 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 the DbEnv.dbRename 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 will fail.
The environment variable DB_HOME may be used as the path of the database environment home.
DbEnv.dbRename is affected by any database directory specified
using the DbEnv.setDataDir
method, or by setting the "set_data_dir"
string in the environment's DB_CONFIG file.
database
- the database to be removed.file
- the physical file which
contains the database(s) to be removed.flags
- must be set to 0 or the
following value:
Db.DB_AUTO_COMMIT
Enclose the DbEnv.dbRename call within a transaction. If the call succeeds, changes made by the operation will be recoverable. If the call fails, the operation will have made no changes.
newname
- the new name of the
database or file.txnid
- If the operation is to be
transaction-protected, the txnid parameter is a
transaction handle returned from DbEnv.txnBegin
;
otherwise, null.
DbException
- The DbEnv.dbRename method
may fail and throw DbException
, encapsulating one of the following non-zero
errors:
DbDeadlockException
- If a transactional database
environment operation was selected to resolve a deadlock,
the DbEnv.dbRename method will fail and throw a DbDeadlockException
exception.
DbLockNotGrantedException
- If a Berkeley DB Concurrent
Data Store database environment configured for lock
timeouts was unable to grant a lock in the allowed time,
the DbEnv.dbRename method will fail and throw a DbLockNotGrantedException
exception.
java.lang.IllegalArgumentException
- The DbEnv.dbRename method
will fail and throw a IllegalArgumentException exception
if DbEnv.dbRename called before DbEnv.open
was called; or if
an invalid flag value or parameter was specified.
FileNotFoundException
- If the file or directory
does not exist, the DbEnv.dbRename method will fail and
throw a FileNotFoundException exception.public void err(int error, java.lang.String message)
Db.err
and Db.errx
methods
provide error-messaging functionality for applications written
using the Berkeley DB library. The DbEnv.err method constructs an error message consisting of the following elements:
If no error callback function has been set using the
DbEnv.setErrorHandler
method, any prefix string specified using theDbEnv.setErrorPrefix
method, followed by two separating characters: a colon and a <space> character.
Two separating characters: a colon and a <space> character.
The standard system or Berkeley DB library error string associated with the error value, as returned by the
DbEnv.strerror
method.
This constructed error message is then handled as follows:
If an error callback function has been set (see
Db.setErrorHandler
andDbEnv.setErrorHandler
), that function is called with two parameters: any prefix string specified (seeDb.setErrorPrefix
andDbEnv.setErrorPrefix
) and the error message.If an OutputStream has been set (see
DbEnv.setErrorStream
andDb.setErrorStream
), the error message is written to that stream.If none of these output options has been configured, the error message is written to System.err, the standard error output stream.
error
- the error value for which the DbEnv.err and
Db.err
methods will
display a explanatory string.message
- an error message to display.public void errx(java.lang.String message)
Db.errx
methods perform identically to the DbEnv.err and Db.err
methods, except that they do
not append the final separator characters and standard error
string to the error message.
error
- the error value for which the DbEnv.err and
Db.err
methods will
display a explanatory string.message
- an error message to display.public java.lang.String[] get_data_dirs() throws DbException
getDataDirs()
DbException
public java.lang.String[] getDataDirs() throws DbException
The DbEnv.getDataDirs method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public int get_encrypt_flags() throws DbException
getEncryptFlags()
DbException
public int getEncryptFlags() throws DbException
The DbEnv.getEncryptFlags method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public int get_flags() throws DbException
getFlags()
DbException
public int getFlags() throws DbException
The DbEnv.getFlags method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public java.lang.String get_home() throws DbException
getDbEnvHome()
DbException
public java.lang.String getDbEnvHome() throws DbException
The DbEnv.getDbEnvHome method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public int get_open_flags() throws DbException
getOpenFlags()
DbException
public int getOpenFlags() throws DbException
The DbEnv.getOpenFlags method may not be called before the DbEnv.open method has been called.
DbException
- Signals that an exception of some sort
has occurred.public long get_shm_key() throws DbException
getSegmentId()
DbException
public long getSegmentId() throws DbException
The DbEnv.getSegmentId method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public int get_tas_spins() throws DbException
getTestAndSetSpins()
DbException
public int getTestAndSetSpins() throws DbException
The DbEnv.getTestAndSetSpins method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public java.lang.String get_tmp_dir() throws DbException
getTmpDir()
DbException
public java.lang.String getTmpDir() throws DbException
The DbEnv.getTmpDir method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public boolean get_verbose(int which) throws DbException
getVerbose(int)
DbException
public boolean getVerbose(int which) throws DbException
The DbEnv.getVerbose method may be called at any time during the life of the application.
which
- the message value for which configuration
is being checked.
DbException
- Signals that an exception of some sort
has occurred.public void set_cachesize(long bytes, int ncache) throws DbException
setCacheSize(long,int)
DbException
public void setCacheSize(long bytes, int ncache) throws DbException
The default cache size is 256KB, and may not be specified as less than 20KB. Any cache size less than 500MB is automatically increased by 25% to account for buffer pool overhead; cache sizes larger than 500MB are used as specified. The current maximum size of a single cache is 4GB. (All sizes are in powers-of-two, that is, 256KB is 2^32 not 256,000.) For information on tuning the Berkeley DB cache size, see Selecting a cache size .
It is possible to specify caches to Berkeley DB larger than 4GB and/or large enough they cannot be allocated contiguously on some architectures. For example, some releases of Solaris limit the amount of memory that may be allocated contiguously by a process. If ncache is 0 or 1, the cache will be allocated contiguously in memory. If it is greater than 1, the cache will be broken up into ncache equally sized, separate pieces of memory.
The database environment's cache size may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_cachesize", one or more whitespace characters, and the cache size specified in three parts: the gigabytes of cache, the additional bytes of cache, and the number of caches, also separated by whitespace characters. For example, "set_cachesize 2 524288000 3" would create a 2.5GB logical cache, split between three physical caches. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
The DbEnv.setCacheSize method configures a database
environment, not only operations performed using the specified
DbEnv
handle.
The DbEnv.setCacheSize method may not be called after the
DbEnv.open
method is
called. If the database environment already exists when DbEnv.open
is called, the
information specified to DbEnv.setCacheSize will be ignored.
bytes
- The size of the cache in
bytes.ncache
- the number of caches to
create.
java.lang.IllegalArgumentException
- The DbEnv.setCacheSize
method will fail and throw a IllegalArgumentException
exception if the specified cache size was impossibly
small; the method was called after DbEnv.open
was called; or if
an invalid flag value or parameter was specified.
DbException
public void set_data_dir(java.lang.String dir) throws DbException
setDataDir(String)
DbException
public void setDataDir(java.lang.String dir) throws DbException
Db.open
function will be searched
relative to this path. Paths set using this method are
additive, and specifying more than one will result in each
specified directory being searched for database files. If any
directories are specified, created database files will always
be created in the first path specified. If no database directories are specified, database files can exist only in the environment home directory. See Berkeley DB File Naming for more information.
For the greatest degree of recoverability from system or application failure, database files and log files should be located on separate physical devices.
The database environment's data directories may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_data_dir", one or more whitespace characters, and the directory name.
The DbEnv.setDataDir method configures operations performed
using the specified DbEnv
handle, not all operations performed on the underlying
database environment.
The DbEnv.setDataDir method may not be called after the DbEnv.open
method is called. If
the database environment already exists when DbEnv.open
is called, the
information specified to DbEnv.setDataDir must be consistent
with the existing environment or corruption can occur.
dir
- a directory to be used as a
location for database files.
java.lang.IllegalArgumentException
- The DbEnv.setDataDir method
will fail and throw a IllegalArgumentException exception
if the method was called after DbEnv.open
was called; or if
an invalid flag value or parameter was specified.
DbException
public void set_encrypt(java.lang.String passwd, int flags) throws DbException
setEncrypted(String,int)
DbException
public void setEncrypted(java.lang.String passwd, int flags) throws DbException
The DbEnv.setEncrypted method configures a database
environment, not only operations performed using the specified
DbEnv
handle.
The DbEnv.setEncrypted method may not be called after the
DbEnv.open
method is
called. If the database environment already exists when DbEnv.open
is called, the
information specified to DbEnv.setEncrypted must be consistent
with the existing environment or an error will be returned.
flags
- must be set to 0 or the
following value:
Db.DB_ENCRYPT_AES
Use the Rijndael/AES (also known as the Advanced Encryption Standard and Federal Information Processing Standard (FIPS) 197) algorithm for encryption or decryption.
passwd
- the password used to perform
encryption and decryption.
DbException
- The DbEnv.setEncrypted
method may fail and throw DbException
, encapsulating
one of the following non-zero errors:
java.lang.IllegalArgumentException
- The DbEnv.setEncrypted
method will fail and throw a IllegalArgumentException
exception if the method was called after DbEnv.open
was called; or if
an invalid flag value or parameter was specified.public void setErrorHandler(DbErrorHandler db_errcall_fcn) throws DbException
The DbEnv.setOnError and Db.setErrorHandler
methods are used to enhance the mechanism
for reporting error messages to the application. The
DbEnv.setOnError and Db.setErrorHandler
methods must be called with a single
object parameter. The object's class must implement the
DbErrorHandler interface.
In some cases, when an error occurs, Berkeley DB will invoke
the object's errcall() method with two parameters; the first
is the prefix string (as previously set by Db.setErrorPrefix
or
DbEnv.setErrorPrefix
), the second will be an error message
string. It is up to this method to display the message in an
appropriate manner.
Alternatively, you can use the DbEnv.setErrorStream
and Db.setErrorStream
methods to display the additional
information via an output stream. You should not mix these
approaches.
This error-logging enhancement does not slow performance or significantly increase application size, and may be run during normal operation as well as during application debugging.
The DbEnv.setOnError method may be called at any time during the life of the application.
db_errcall_fcn
- the application-specified error
reporting function. The function takes two parameters:
The errpfx parameter is the prefix string (as
previously set by Db.setErrorPrefix
or DbEnv.setErrorPrefix
).
The msg parameter is the error message string.
DbException
- Signals that an exception of some sort
has occurred.public void set_flags(int flags, boolean onoff) throws DbException
setFlags(int,boolean)
DbException
public void setFlags(int flags, boolean onoff) throws DbException
The database environment's flag values may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_flags", one or more whitespace characters, and the method flag parameter as a string; for example, "set_flags DB_TXN_NOSYNC". Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
flags
- must be set by bitwise
inclusively OR 'ing together one or more of the
following values:
Db.DB_AUTO_COMMIT
If set, operations for which no explicit transaction handle was specified, and which modify databases in the database environment, will be automatically enclosed within a transaction. If the call succeeds, changes made by the operation will be recoverable. If the call fails, the operation will have made no changes.
Calling DbEnv.setFlags with the
flag only affects the specified Db.DB_AUTO_COMMIT
DbEnv
handle (and any other
Berkeley DB handles opened within the scope of that
handle). For consistent behavior across the environment,
all DbEnv
handles opened
in the environment must either set the
flag or the flag should be specified in the
DB_CONFIG configuration file.Db.DB_AUTO_COMMIT
The
flag may be used to configure Berkeley DB at any time
during the life of the application.Db.DB_AUTO_COMMIT
Db.DB_CDB_ALLDB
If set, Berkeley DB Concurrent Data Store applications will perform locking on an environment-wide basis rather than on a per-database basis.
Calling DbEnv.setFlags with the Db.DB_CDB_ALLDB
flag only affects the specified DbEnv
handle (and any other
Berkeley DB handles opened within the scope of that
handle). For consistent behavior across the environment,
all DbEnv
handles opened
in the environment must either set the Db.DB_CDB_ALLDB
flag or the flag should be specified in the DB_CONFIG
configuration file.
The Db.DB_CDB_ALLDB
flag may be used to
configure Berkeley DB only before the DbEnv.open
method is
called.
Db.DB_DIRECT_DB
Turn off system buffering of Berkeley DB database files to avoid double caching.
Calling DbEnv.setFlags with the Db.DB_DIRECT_DB
flag only affects the specified DbEnv
handle (and any other
Berkeley DB handles opened within the scope of that
handle). For consistent behavior across the environment,
all DbEnv
handles opened
in the environment must either set the Db.DB_DIRECT_DB
flag or the flag should be specified in the DB_CONFIG
configuration file.
The Db.DB_DIRECT_DB
flag may be used to
configure Berkeley DB at any time during the life of the
application.
Db.DB_DIRECT_LOG
Turn off system buffering of Berkeley DB log files to avoid double caching.
Calling DbEnv.setFlags with the Db.DB_DIRECT_LOG
flag only affects the specified DbEnv
handle (and any other
Berkeley DB handles opened within the scope of that
handle). For consistent behavior across the environment,
all DbEnv
handles opened
in the environment must either set the Db.DB_DIRECT_LOG
flag or the flag should be specified in the DB_CONFIG
configuration file.
The Db.DB_DIRECT_LOG
flag may be used to
configure Berkeley DB at any time during the life of the
application.
Db.DB_LOG_AUTOREMOVE
If set, Berkeley DB will automatically remove log files that are no longer needed. Automatic log file removal is likely to make catastrophic recovery impossible.
Calling DbEnv.setFlags with the Db.DB_LOG_AUTOREMOVE
flag only affects the specified DbEnv
handle (and any other
Berkeley DB handles opened within the scope of that
handle). For consistent behavior across the environment,
all DbEnv
handles opened
in the environment must either set the Db.DB_LOG_AUTOREMOVE
flag or the flag should be specified in the DB_CONFIG
configuration file.
The Db.DB_LOG_AUTOREMOVE
flag may be used
to configure Berkeley DB at any time during the life of
the application.
Db.DB_NOLOCKING
If set, Berkeley DB will grant all requested mutual exclusion mutexes and database locks without regard for their actual availability. This functionality should never be used for purposes other than debugging.
Calling DbEnv.setFlags with the Db.DB_NOLOCKING
flag only affects the specified DbEnv
handle (and any other
Berkeley DB handles opened within the scope of that
handle).
The Db.DB_NOLOCKING
flag may be used to
configure Berkeley DB at any time during the life of the
application.
Db.DB_NOMMAP
If set, Berkeley DB will copy read-only database files
into the local cache instead of potentially mapping them
into process memory (see the description of the DbEnv.setMemoryPoolMapSize
method for further
information).
Calling DbEnv.setFlags with the Db.DB_NOMMAP
flag only affects the specified DbEnv
handle (and any other
Berkeley DB handles opened within the scope of that
handle). For consistent behavior across the environment,
all DbEnv
handles opened
in the environment must either set the Db.DB_NOMMAP
flag or the flag should be specified in the DB_CONFIG
configuration file.
The Db.DB_NOMMAP
flag may be used to
configure Berkeley DB at any time during the life of the
application.
Db.DB_NOPANIC
If set, Berkeley DB will ignore any panic state in the
database environment. (Database environments in a panic
state normally refuse all attempts to call Berkeley DB
functions, returning
Db.DB_RUNRECOVERY
.) This functionality
should never be used for purposes other than debugging.
Calling DbEnv.setFlags with the Db.DB_NOPANIC
flag only affects the specified DbEnv
handle (and any other
Berkeley DB handles opened within the scope of that
handle).
The Db.DB_NOPANIC
flag may be used to
configure Berkeley DB at any time during the life of the
application.
Db.DB_OVERWRITE
Overwrite files stored in encrypted formats before deleting them. Berkeley DB overwrites files using alternating 0xff, 0x00 and 0xff byte patterns. For file overwriting to be effective, the underlying file must be stored on a fixed-block filesystem. Systems with journaling or logging filesystems will require operating system support and probably modification of the Berkeley DB sources.
Calling DbEnv.setFlags with the Db.DB_OVERWRITE
flag only affects the specified DbEnv
handle (and any other
Berkeley DB handles opened within the scope of that
handle).
The Db.DB_OVERWRITE
flag may be used to
configure Berkeley DB at any time during the life of the
application.
Db.DB_PANIC_ENVIRONMENT
If set, Berkeley DB will set the panic state for the
database environment. (Database environments in a panic
state normally refuse all attempts to call Berkeley DB
functions, returning
Db.DB_RUNRECOVERY
.) This flag may not
be specified using the environment's DB_CONFIG
file. This flag may be used to configure Berkeley DB
only after the DbEnv.open
method is called.
Calling DbEnv.setFlags with the Db.DB_PANIC_ENVIRONMENT
flag affects the database environment, including all
threads of control accessing the database environment.
The Db.DB_PANIC_ENVIRONMENT
flag may be
used to configure Berkeley DB at any time during the
life of the application.
Db.DB_REGION_INIT
In some applications, the expense of page-faulting the underlying shared memory regions can affect performance. (For example, if the page-fault occurs while holding a lock, other lock requests can convoy, and overall throughput may decrease.) If set, Berkeley DB will page-fault shared regions into memory when initially creating or joining a Berkeley DB environment. In addition, Berkeley DB will write the shared regions when creating an environment, forcing the underlying virtual memory and filesystems to instantiate both the necessary memory and the necessary disk space. This can also avoid out-of-disk space failures later on.
Calling DbEnv.setFlags with the Db.DB_REGION_INIT
flag only affects the specified DbEnv
handle (and any other
Berkeley DB handles opened within the scope of that
handle). For consistent behavior across the environment,
all DbEnv
handles opened
in the environment must either set the Db.DB_REGION_INIT
flag or the flag should be specified in the DB_CONFIG
configuration file.
The Db.DB_REGION_INIT
flag may be used to
configure Berkeley DB at any time during the life of the
application.
Db.DB_TIME_NOTGRANTED
If set, database calls timing out based on lock or
transaction timeout values will throw a DbLockNotGrantedException
exception instead of DbDeadlockException
. This allows applications to
distinguish between operations which have deadlocked and
operations which have exceeded their time limits.
Calling DbEnv.setFlags with the
flag only affects the specified Db.DB_TIME_NOTGRANTED
DbEnv
handle (and any other
Berkeley DB handles opened within the scope of that
handle). For consistent behavior across the environment,
all DbEnv
handles opened
in the environment must either set the
flag or the flag should be specified in the
DB_CONFIG configuration file.Db.DB_TIME_NOTGRANTED
The
flag may be used to configure Berkeley DB at any time
during the life of the application.Db.DB_TIME_NOTGRANTED
Db.DB_TXN_NOSYNC
If set, Berkeley DB will not write or synchronously flush the log on transaction commit. This means that transactions exhibit the ACI (atomicity, consistency, and isolation) properties, but not D (durability); that is, database integrity will be maintained, but if the application or system fails, it is possible some number of the most recently committed transactions may be undone during recovery. The number of transactions at risk is governed by how many log updates can fit into the log buffer, how often the operating system flushes dirty buffers to disk, and how often the log is checkpointed.
Calling DbEnv.setFlags with the Db.DB_TXN_NOSYNC
flag only affects the specified DbEnv
handle (and any other
Berkeley DB handles opened within the scope of that
handle). For consistent behavior across the environment,
all DbEnv
handles opened
in the environment must either set the Db.DB_TXN_NOSYNC
flag or the flag should be specified in the DB_CONFIG
configuration file.
The Db.DB_TXN_NOSYNC
flag may be used to
configure Berkeley DB at any time during the life of the
application.
Db.DB_TXN_NOT_DURABLE
If set, Berkeley DB will not write log records. This
means that transactions exhibit the ACI (atomicity,
consistency, and isolation) properties, but not D
(durability); that is, database integrity will be
maintained, but if the application or system fails,
integrity will not persist. All database files must be
verified and/or restored from backup after a failure. In
order to ensure integrity after application shut down,
all database handles must be closed without specifying
, or all database changes must be flushed from the
database environment cache using the Db.DB_NOSYNC
DbEnv.txnCheckpoint
method.
Calling DbEnv.setFlags with the Db.DB_TXN_NOT_DURABLE
flag only affects the specified DbEnv
handle (and any other
Berkeley DB handles opened within the scope of that
handle). For consistent behavior across the environment,
all DbEnv
handles opened
in the environment must either set the Db.DB_TXN_NOT_DURABLE
flag or the flag should be specified in the DB_CONFIG
configuration file.
The Db.DB_TXN_NOT_DURABLE
flag may be used
to configure Berkeley DB at any time during the life of
the application.
Db.DB_TXN_WRITE_NOSYNC
If set, Berkeley DB will write, but will not synchronously flush, the log on transaction commit. This means that transactions exhibit the ACI (atomicity, consistency, and isolation) properties, but not D (durability); that is, database integrity will be maintained, but if the system fails, it is possible some number of the most recently committed transactions may be undone during recovery. The number of transactions at risk is governed by how often the system flushes dirty buffers to disk and how often the log is checkpointed.
Calling DbEnv.setFlags with the Db.DB_TXN_WRITE_NOSYNC
flag only affects the specified DbEnv
handle (and any other
Berkeley DB handles opened within the scope of that
handle). For consistent behavior across the environment,
all DbEnv
handles opened
in the environment must either set the Db.DB_TXN_WRITE_NOSYNC
flag or the flag should be specified in the DB_CONFIG
configuration file.
The Db.DB_TXN_WRITE_NOSYNC
flag may be used
to configure Berkeley DB at any time during the life of
the application.
Db.DB_YIELDCPU
If set, Berkeley DB will yield the processor immediately after each page or mutex acquisition. This functionality should never be used for purposes other than stress testing.
Calling DbEnv.setFlags with the Db.DB_YIELDCPU
flag only affects the specified DbEnv
handle (and any other
Berkeley DB handles opened within the scope of that
handle). For consistent behavior across the environment,
all DbEnv
handles opened
in the environment must either set the Db.DB_YIELDCPU
flag or the flag should be specified in the DB_CONFIG
configuration file.
The Db.DB_YIELDCPU
flag may be used to
configure Berkeley DB at any time during the life of the
application.
onoff
- If the onoff
parameter is false, the specified flags are cleared;
otherwise they are set.
java.lang.IllegalArgumentException
- The DbEnv.setFlags method
will fail and throw a IllegalArgumentException exception
if an invalid flag value or parameter was specified.
DbException
public void setFeedbackHandler(DbEnvFeedbackHandler db_feedback_fcn) throws DbException
DbException
public void set_mp_mmapsize(long mp_mmapsize) throws DbException
setMemoryPoolMapSize(long)
DbException
public void setMemoryPoolMapSize(long mp_mmapsize) throws DbException
The DbEnv.getMemoryPoolMapSize method sets the maximum file size, in bytes, for a file to be mapped into the process address space. If no value is specified, it defaults to 10MB.
The database environment's maximum mapped file size may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_mp_mmapsize", one or more whitespace characters, and the size in bytes. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
The DbEnv.setMemoryPoolMapSize method configures operations
performed using the specified DbEnv
handle, not all operations performed on the underlying
database environment.
The DbEnv.setMemoryPoolMapSize method may be called at any time during the life of the application.
mp_mmapsize
- the maximum file size, in
bytes, for a file to be mapped into the process address
space.
java.lang.IllegalArgumentException
- The
DbEnv.setMemoryPoolMapSize method will fail and throw a
IllegalArgumentException exception if the method was
called after DbEnv.open
was called; or if an invalid flag value or
parameter was specified.
DbException
public void setPanicHandler(DbPanicHandler db_panic_fcn) throws DbException
DbException
public void set_rpc_server(DbClient client, java.lang.String host, long cl_timeout, long sv_timeout, int flags) throws DbException
setRpcServer(DbClient,String,long,long,int)
DbException
public void setRpcServer(DbClient client, java.lang.String host, long cl_timeout, long sv_timeout, int flags) throws DbException
DbEnv
handle, not all operations
performed on the underlying database environment.
The DbEnv.setRpcServer method may not be called after the
DbEnv.open
method is
called.
cl_timeout
- specifies the number of
seconds the client should wait for results to come back
from the server. Once the timeout has expired on any
communication with the server, Db.DB_NOSERVER will be
returned. If this value is zero, a default timeout is
used.client
- reserved for future use. If
it is not NULL, an exception is thrown.host
- the host to which the
Berkeley DB server will connect and create a channel for
communication.flags
- currently unused, and must
be set to 0.sv_timeout
- specifies the number of
seconds the server should allow a client connection to
remain idle before assuming that the client is gone. Once
that timeout has been reached, the server releases all
resources associated with that client connection.
Subsequent attempts by that client to communicate with the
server result in Db.DB_NOSERVER_ID, indicating that an
invalid identifier has been given to the server. This
value can be considered a hint to the server. The server
may alter this value based on its own policies or allowed
values. If this value is zero, a default timeout is used.
java.lang.IllegalArgumentException
- The DbEnv.setRpcServer
method will fail and throw a IllegalArgumentException
exception if an invalid flag value or parameter was
specified.
DbException
public void set_shm_key(long shm_key) throws DbException
setSegmentId(long)
DbException
public void setSegmentId(long shm_key) throws DbException
This base segment ID will be used when Berkeley DB shared memory regions are first created. It will be incremented a small integer value each time a new shared memory region is created; that is, if the base ID is 35, the first shared memory region created will have a segment ID of 35, and the next one will have a segment ID between 36 and 40 or so. A Berkeley DB environment always creates a master shared memory region; an additional shared memory region for each of the subsystems supported by the environment (Locking, Logging, Memory Pool and Transaction); plus an additional shared memory region for each additional memory pool cache that is supported. Already existing regions with the same segment IDs will be removed. See Shared Memory Regions for more information.
The intent behind this method is two-fold: without it, applications have no way to ensure that two Berkeley DB applications don't attempt to use the same segment IDs when creating different Berkeley DB environments. In addition, by using the same segment IDs each time the environment is created, previously created segments will be removed, and the set of segments on the system will not grow without bound.
The database environment's base segment ID may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_shm_key", one or more whitespace characters, and the ID. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
The DbEnv.setSegmentId method configures operations performed
using the specified DbEnv
handle, not all operations performed on the underlying
database environment.
The DbEnv.setSegmentId method may not be called after the
DbEnv.open
method is
called. If the database environment already exists when DbEnv.open
is called, the
information specified to DbEnv.setSegmentId must be consistent
with the existing environment or corruption can occur.
shm_key
- the base segment ID for the
database environment.
java.lang.IllegalArgumentException
- The DbEnv.setSegmentId
method will fail and throw a IllegalArgumentException
exception if the method was called after DbEnv.open
was called; or if
an invalid flag value or parameter was specified.
DbException
public void set_tas_spins(int tas_spins) throws DbException
setTestAndSetSpins(int)
DbException
public void setTestAndSetSpins(int tas_spins) throws DbException
The database environment's test-and-set spin count may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_tas_spins", one or more whitespace characters, and the number of spins. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
The DbEnv.setTestAndSetSpins method configures operations
performed using the specified DbEnv
handle, not all operations performed on the underlying
database environment.
The DbEnv.setTestAndSetSpins method may be called at any time during the life of the application.
tas_spins
- the number of spins
test-and-set mutexes should execute before blocking.
java.lang.IllegalArgumentException
- The DbEnv.setTestAndSetSpins
method will fail and throw a IllegalArgumentException
exception if an invalid flag value or parameter was
specified.
DbException
public void set_timeout(long timeout, int flags) throws DbException
setTimeout(long,int)
DbException
public void setTimeout(long timeout, int flags) throws DbException
Timeouts are checked whenever a thread of control blocks on a lock or when deadlock detection is performed. (In the case of Db.DB_SET_LOCK_TIMEOUT, the lock is one requested explicitly through the Lock subsystem interfaces. In the case of Db.DB_SET_TXN_TIMEOUT, the lock is one requested on behalf of a transaction. In either case, it may be a lock requested by the database access methods underlying the application.) As timeouts are only checked when the lock request first blocks or when deadlock detection is performed, the accuracy of the timeout depends on how often deadlock detection is performed.
Timeout values specified for the database environment may be
overridden on a per-lock or per-transaction basis. See DbEnv.lockVector
and DbTxn.setTimeout
for more
information.
The DbEnv.setTimeout method configures a database environment,
not only operations performed using the specified DbEnv
handle.
The DbEnv.setTimeout method may be called at any time during the life of the application.
flags
- must be set to one of the
following values:
Db.DB_SET_LOCK_TIMEOUT
Set the timeout value for locks in this database environment.
The database environment's lock timeout value may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lock_timeout", one or more whitespace characters, and the lock timeout value. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
Db.DB_SET_TXN_TIMEOUT
Set the timeout value for transactions in this database environment.
The database environment's transaction timeout value may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_txn_timeout", one or more whitespace characters, and the transaction timeout value. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
timeout
- the timeout value. It must
be specified as an unsigned 32-bit number of microseconds,
limiting the maximum timeout to roughly 71 minutes.
java.lang.IllegalArgumentException
- The DbEnv.setTimeout method
will fail and throw a IllegalArgumentException exception
if an invalid flag value or parameter was specified.
DbException
public void set_tmp_dir(java.lang.String dir) throws DbException
setTmpDir(String)
DbException
public void setTmpDir(java.lang.String dir) throws DbException
If no directories are specified, the following alternatives are checked in the specified order. The first existing directory path is used for all temporary files.
Note: environment variables are only checked if one of the
Db.DB_USE_ENVIRON
or Db.DB_USE_ENVIRON_ROOT
flags were specified.
Note: the GetTempPath interface is only checked on Win/32 platforms.
The database environment's temporary file directory may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_tmp_dir", one or more whitespace characters, and the directory name. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
The DbEnv.setTmpDir method configures operations performed
using the specified DbEnv
handle, not all operations performed on the underlying
database environment.
The DbEnv.setTmpDir method may not be called after the DbEnv.open
method is called. If
the database environment already exists when DbEnv.open
is called, the
information specified to DbEnv.setTmpDir must be consistent
with the existing environment or corruption can occur.
dir
- the directory to be used to
store temporary files.
java.lang.IllegalArgumentException
- The DbEnv.setTmpDir method
will fail and throw a IllegalArgumentException exception
if the method was called after DbEnv.open
was called; or if
an invalid flag value or parameter was specified.
DbException
public void set_tx_max(int max) throws DbException
setTxnMax(int)
DbException
public void setTxnMax(int max) throws DbException
When all of the memory available in the database environment
for transactions is in use, calls to DbEnv.txnBegin
will fail
(until some active transactions complete). If this interface
is never called, the database environment is configured to
support at least 20 active transactions.
The database environment's number of active transactions may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_tx_max", one or more whitespace characters, and the number of transactions. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
The DbEnv.setTxnMax method configures a database environment,
not only operations performed using the specified DbEnv
handle.
The DbEnv.setTxnMax method may not be called after the DbEnv.open
method is called. If
the database environment already exists when DbEnv.open
is called, the
information specified to DbEnv.setTxnMax will be ignored.
max
- The max parameter
configures the minimum number of simultaneously active
transactions supported by Berkeley DB database
environment.
java.lang.IllegalArgumentException
- The DbEnv.setTxnMax method
will fail and throw a IllegalArgumentException exception
if the method was called after DbEnv.open
was called; or if
an invalid flag value or parameter was specified.
DbException
public void set_app_dispatch(DbAppDispatch tx_recover) throws DbException
setAppDispatch(DbAppDispatch)
DbException
public void setAppDispatch(DbAppDispatch tx_recover) throws DbException
DbException
public void set_verbose(int which, boolean onoff) throws DbException
setVerbose(int,boolean)
DbException
public void setVerbose(int which, boolean onoff) throws DbException
Db.setErrorStream
method.
The database environment's messages may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_verbose", one or more whitespace characters, and the method which parameter as a string; for example, "set_verbose DB_VERB_CHKPOINT". Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
The DbEnv.setVerbose method configures operations performed
using the specified DbEnv
handle, not all operations performed on the underlying
database environment.
The DbEnv.setVerbose method may be called at any time during the life of the application.
onoff
- If the onoff
parameter is set to true, the additional messages are
output.which
- must be set to one of the
following values:
Db.DB_VERB_CHKPOINT
Display checkpoint location information when searching the log for checkpoints.
Db.DB_VERB_DEADLOCK
Display additional information when doing deadlock detection.
Db.DB_VERB_RECOVERY
Display additional information when performing recovery.
Db.DB_VERB_REPLICATION
Display additional information when processing replication messages.
Note, to get complete replication logging when debugging replication applications, you must also configure and build the Berkeley DB library with the --enable-diagnostic configuration option as well as call the DbEnv.setVerbose method.
Db.DB_VERB_WAITSFOR
Display the waits-for table when doing deadlock detection.
java.lang.IllegalArgumentException
- The DbEnv.setVerbose method
will fail and throw a IllegalArgumentException exception
if an invalid flag value or parameter was specified.
DbException
public byte[][] get_lk_conflicts() throws DbException
getLockConflicts()
DbException
public byte[][] getLockConflicts() throws DbException
The DbEnv.getLockConflicts method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public int get_lk_detect() throws DbException
getLockDetect()
DbException
public int getLockDetect() throws DbException
The DbEnv.getLockDetect method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public int get_lk_max_locks() throws DbException
getLockMaxLocks()
DbException
public int getLockMaxLocks() throws DbException
The DbEnv.setLockMaxLocks method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public int get_lk_max_lockers() throws DbException
getLockMaxLockers()
DbException
public int getLockMaxLockers() throws DbException
The DbEnv.getLockMaxLockers method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public int get_lk_max_objects() throws DbException
getLockMaxObjects()
DbException
public int getLockMaxObjects() throws DbException
The DbEnv.getLockMaxObjects method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public int lock_detect(int flags, int atype) throws DbException
lockDetect(int,int)
DbException
public int lockDetect(int flags, int atype) throws DbException
atype
- specifies which lock
request(s) to reject. It must be set to one of the
following list:
Db.DB_LOCK_DEFAULT
Use whatever lock policy was specified when the database
environment was created. If no lock policy has yet been
specified, set the lock policy to Db.DB_LOCK_RANDOM
.
Db.DB_LOCK_EXPIRE
Reject lock requests which have timed out. No other deadlock detection is performed.
Db.DB_LOCK_MAXLOCKS
Reject the lock request for the locker ID with the greatest number of locks.
Db.DB_LOCK_MINLOCKS
Reject the lock request for the locker ID with the fewest number of locks.
Db.DB_LOCK_MINWRITE
Reject the lock request for the locker ID with the fewest number of write locks.
Db.DB_LOCK_OLDEST
Reject the lock request for the oldest locker ID.
Db.DB_LOCK_RANDOM
Reject the lock request for a random locker ID.
Db.DB_LOCK_YOUNGEST
Reject the lock request for the youngest locker ID.
flags
- currently unused, and must
be set to 0.
java.lang.IllegalArgumentException
- The DbEnv.lockDetect method
will fail and throw a IllegalArgumentException exception
if an invalid flag value or parameter was specified.
DbException
public DbLock lock_get(int locker, int flags, Dbt object, int lock_mode) throws DbException
lockGet(int,int,Dbt,int)
DbException
public DbLock lockGet(int locker, int flags, Dbt object, int lock_mode) throws DbException
flags
- must be set to 0 or the
following value:
Db.DB_LOCK_NOWAIT
If a lock cannot be granted because the requested lock
conflicts with an existing lock, throw a DbLockNotGrantedException
immediately instead of
waiting for the lock to become available.
lock_mode
- used as an index into the
environment's lock conflict matrix. When using the default
lock conflict matrix, lock_mode must be set to one
of the following values: read (shared) write (exclusive)
intention to write (shared) intention to read (shared)
intention to read and write (shared)
See DbEnv.setLockConflicts
and Standard Lock
Modes for more information on the lock conflict
matrix.
locker
- an unsigned 32-bit integer
quantity. It represents the entity requesting the lock.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. See Access method
locking conventions for more information.
DbDeadlockException
- If a transactional database
environment operation was selected to resolve a deadlock,
the DbEnv.lockGet method will fail and throw a DbDeadlockException
exception.
DbLockNotGrantedException
- If a Berkeley DB Concurrent
Data Store database environment configured for lock
timeouts was unable to grant a lock in the allowed time,
the DbEnv.lockGet method will fail and throw a DbLockNotGrantedException
exception.
DbLockNotGrantedException
- If the Db.DB_LOCK_NOWAIT
flag
or lock timers were configured and the lock could not be
granted before the wait-time expired, the DbEnv.lockGet
method will fail and throw a DbLockNotGrantedException
exception.
java.lang.IllegalArgumentException
- The DbEnv.lockGet method
will fail and throw a IllegalArgumentException exception
if an invalid flag value or parameter was specified.
DbMemoryException
- If the maximum number of
locks has been reached, the DbEnv.lockGet method will fail
and throw a DbMemoryException
exception.
DbException
public int lock_id() throws DbException
lockId()
DbException
public int lockId() throws DbException
The DbEnv.lockIdFree
method should be called to return the locker ID to the
Berkeley DB library when it is no longer needed.
DbException
- Signals that an exception of some sort
has occurred.public void lock_id_free(int id) throws DbException
lockIdFree(int)
DbException
public void lockIdFree(int id) throws DbException
DbEnv.lockId
method.
id
- the locker id to be freed.
java.lang.IllegalArgumentException
- The DbEnv.lockIdFree method
will fail and throw a IllegalArgumentException exception
if the locker ID is invalid or locks are still held by
this locker ID; or if an invalid flag value or parameter
was specified.
DbException
public void lock_put(DbLock lock) throws DbException
lockPut(DbLock)
DbException
public void lockPut(DbLock lock) throws DbException
lock
- the lock to be released.
java.lang.IllegalArgumentException
- The DbEnv.lockPut method
will fail and throw a IllegalArgumentException exception
if an invalid flag value or parameter was specified.
DbException
public DbLockStat lock_stat(int flags) throws DbException
lockStat(int)
DbException
public DbLockStat lockStat(int flags) throws DbException
The DbEnv.lockStat method creates a DbLockStat object encapsulating the locking subsystem statistics. The following data fields are available from the DbLockStat object:
For convenience, the DbLockStat class has a toString method that lists all the data fields.
flags
- must be set to 0 or the
following value:
Db.DB_STAT_CLEAR
Reset statistics after returning their values.
java.lang.IllegalArgumentException
- The DbEnv.lockStat method
will fail and throw a IllegalArgumentException exception
if an invalid flag value or parameter was specified.
DbException
public void set_lk_conflicts(byte[][] conflicts) throws DbException
setLockConflicts(byte[][])
DbException
public void setLockConflicts(byte[][] conflicts) throws DbException
If DbEnv.setLockConflicts is never called, a standard conflicts array is used; see Standard Lock Modes for more information.
The DbEnv.setLockConflicts method configures a database
environment, not only operations performed using the specified
DbEnv
handle.
The DbEnv.setLockConflicts method may not be called after the
DbEnv.open
method is
called. If the database environment already exists when DbEnv.open
is called, the
information specified to DbEnv.setLockConflicts will be
ignored.
conflicts
- the new locking conflicts
matrix. A non-0 value for the array element indicates that
requested_mode and held_mode conflict: conflicts[requested_mode][held_mode]
The not-granted mode must be represented by 0.
java.lang.IllegalArgumentException
- The DbEnv.setLockConflicts
method will fail and throw a IllegalArgumentException
exception if the method was called after DbEnv.open
was called; or if
an invalid flag value or parameter was specified.
DbMemoryException
- If the conflicts array could
not be copied, the DbEnv.setLockConflicts method will fail
and throw a DbMemoryException
exception.
DbException
public void set_lk_detect(int detect) throws DbException
setLockDetect(int)
DbException
public void setLockDetect(int detect) throws DbException
The database environment's deadlock detector configuration may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lk_detect", one or more whitespace characters, and the method detect parameter as a string; for example, "set_lk_detect DB_LOCK_OLDEST". Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
The DbEnv.setLockDetect method configures a database
environment, not only operations performed using the specified
DbEnv
handle.
The DbEnv.setLockDetect method may not be called after the
DbEnv.open
method is
called. If the database environment already exists when DbEnv.open
is called, the
information specified to DbEnv.setLockDetect must be
consistent with the existing environment or an error will be
returned.
detect
- The detect parameter
configures the deadlock detector. The specified value must
be one of the following list:
Db.DB_LOCK_DEFAULT
Use whatever lock policy was specified when the database
environment was created. If no lock policy has yet been
specified, set the lock policy to Db.DB_LOCK_RANDOM
.
Db.DB_LOCK_EXPIRE
Reject lock requests which have timed out. No other deadlock detection is performed.
Db.DB_LOCK_MAXLOCKS
Reject the lock request for the locker ID with the greatest number of locks.
Db.DB_LOCK_MINLOCKS
Reject the lock request for the locker ID with the fewest number of locks.
Db.DB_LOCK_MINWRITE
Reject the lock request for the locker ID with the fewest number of write locks.
Db.DB_LOCK_OLDEST
Reject the lock request for the oldest locker ID.
Db.DB_LOCK_RANDOM
Reject the lock request for a random locker ID.
Db.DB_LOCK_YOUNGEST
Reject the lock request for the youngest locker ID.
java.lang.IllegalArgumentException
- The DbEnv.setLockDetect
method will fail and throw a IllegalArgumentException
exception if the method was called after DbEnv.open
was called; or if
an invalid flag value or parameter was specified.
DbException
public void set_lk_max_lockers(int max) throws DbException
setLockMaxLockers(int)
DbException
public void setLockMaxLockers(int max) throws DbException
DbEnv.open
to estimate how much
space to allocate for various lock-table data structures. The
default value is 1000 lockers. For specific information on
configuring the size of the lock subsystem, see Configuring locking:
sizing the system . The database environment's maximum number of lockers may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lk_max_lockers", one or more whitespace characters, and the number of lockers. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
The DbEnv.setLockMaxLockers method configures a database
environment, not only operations performed using the specified
DbEnv
handle.
The DbEnv.setLockMaxLockers method may not be called after the
DbEnv.open
method is
called. If the database environment already exists when DbEnv.open
is called, the
information specified to DbEnv.setLockMaxLockers will be
ignored.
max
- the maximum number
simultaneous locking entities supported by the Berkeley DB
environment.
java.lang.IllegalArgumentException
- The DbEnv.setLockMaxLockers
method will fail and throw a IllegalArgumentException
exception if the method was called after DbEnv.open
was called; or if
an invalid flag value or parameter was specified.
DbException
public void set_lk_max_locks(int max) throws DbException
setLockMaxLocks(int)
DbException
public void setLockMaxLocks(int max) throws DbException
DbEnv.open
to estimate how much
space to allocate for various lock-table data structures. The
default value is 1000 locks. For specific information on
configuring the size of the lock subsystem, see Configuring locking:
sizing the system . The database environment's maximum number of locks may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lk_max_locks", one or more whitespace characters, and the number of locks. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
The DbEnv.setLockMaxLocks method configures a database
environment, not only operations performed using the specified
DbEnv
handle.
The DbEnv.setLockMaxLocks method may not be called after the
DbEnv.open
method is
called. If the database environment already exists when DbEnv.open
is called, the
information specified to DbEnv.setLockMaxLocks will be
ignored.
max
- the maximum number of locks
supported by the Berkeley DB environment.
java.lang.IllegalArgumentException
- The DbEnv.setLockMaxLocks
method will fail and throw a IllegalArgumentException
exception if the method was called after DbEnv.open
was called; or if
an invalid flag value or parameter was specified.
DbException
public void set_lk_max_objects(int max) throws DbException
setLockMaxObjects(int)
DbException
public void setLockMaxObjects(int max) throws DbException
DbEnv.open
to estimate how much
space to allocate for various lock-table data structures. The
default value is 1000 objects. For specific information on
configuring the size of the lock subsystem, see Configuring locking:
sizing the system . The database environment's maximum number of objects may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lk_max_objects", one or more whitespace characters, and the number of objects. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
The DbEnv.setLockMaxObjects method configures a database
environment, not only operations performed using the specified
DbEnv
handle.
The DbEnv.setLockMaxObjects method may not be called after the
DbEnv.open
method is
called. If the database environment already exists when DbEnv.open
is called, the
information specified to DbEnv.setLockMaxObjects will be
ignored.
max
- the maximum number of locked
objects supported by the Berkeley DB environment.
java.lang.IllegalArgumentException
- The DbEnv.setLockMaxObjects
method will fail and throw a IllegalArgumentException
exception if the method was called after DbEnv.open
was called; or if
an invalid flag value or parameter was specified.
DbException
public int get_lg_bsize() throws DbException
getLogBufferSize()
DbException
public int getLogBufferSize() throws DbException
The DbEnv.getLogBufferSize method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public java.lang.String get_lg_dir() throws DbException
getLogDir()
DbException
public java.lang.String getLogDir() throws DbException
The DbEnv.getLogDir method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public int get_lg_max() throws DbException
getLogMax()
DbException
public int getLogMax() throws DbException
The DbEnv.getLogMax method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public int get_lg_regionmax() throws DbException
getLogRegionMax()
DbException
public int getLogRegionMax() throws DbException
The DbEnv.getLogRegionMax method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public java.lang.String[] log_archive(int flags) throws DbException
logArchive(int)
DbException
public java.lang.String[] logArchive(int flags) throws DbException
By default, DbEnv.logArchive 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, DbEnv.logArchive returns null.
Log cursor handles (returned by the DbEnv.logCursor
method) 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, DbEnv.logPut
and DbTxn.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
DbEnv.logArchive 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.)
See db_archive for more information on database archival procedures.
flags
- must be set to 0 or by
bitwise inclusively OR 'ing together one or more of
the following values:
Db.DB_ARCH_ABS
All pathnames are returned as absolute pathnames, instead of relative to the database home directory.
Db.DB_ARCH_DATA
Return 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, DbEnv.logArchive will not include them in this list. It is also possible that some of the files referred to by the log have since been deleted from the system.
The Db.DB_ARCH_DATA
and Db.DB_ARCH_LOG
flags are mutually exclusive.
Db.DB_ARCH_LOG
Return all the log filenames, regardless of whether or not they are in use.
The Db.DB_ARCH_DATA
and Db.DB_ARCH_LOG
flags are mutually exclusive.
Db.DB_ARCH_REMOVE
Remove log files that are no longer needed; no filenames are returned. Automatic log file removal is likely to make catastrophic recovery impossible.
The Db.DB_ARCH_REMOVE
flag may not be
specified with any other flag.
java.lang.IllegalArgumentException
- The DbEnv.logArchive method
will fail and throw a IllegalArgumentException exception
if an invalid flag value or parameter was specified.
DbException
public static int log_compare(DbLsn lsn0, DbLsn lsn1)
logCompare(DbLsn,DbLsn)
public static int logCompare(DbLsn lsn0, DbLsn lsn1)
DbLsn
objects, returning 0 if
they are equal, 1 if lsn0 is greater than lsn1 ,
and -1 if lsn0 is less than lsn1 .
lsn0
- one of the DbLsn
objects to be compared.lsn1
- one of the DbLsn
objects to be compared.
DbLsn
object parameters are
equal, 1 if lsn0 is greater than lsn1 , and
-1 if lsn0 is less than lsn1 .public DbLogc log_cursor(int flags) throws DbException
logCursor(int)
DbException
public DbLogc logCursor(int flags) throws DbException
flags
- currently unused, and must
be set to 0.
java.lang.IllegalArgumentException
- The DbEnv.logCursor method
will fail and throw a IllegalArgumentException exception
if an invalid flag value or parameter was specified.
DbException
public java.lang.String log_file(DbLsn lsn) throws DbException
logFile(DbLsn)
DbException
public java.lang.String logFile(DbLsn lsn) throws DbException
DbLsn
objects to filenames, returning the name of the file
containing the record named by lsn .
This mapping of DbLsn
objects
to files is needed for database administration. For example, a
transaction manager typically records the earliest DbLsn
needed for restart, and the
database administrator may want to archive log files to tape
when they contain only DbLsn
entries before the earliest one needed for restart.
lsn
- the DbLsn
object for which a filename is wanted.
DbMemoryException
- If the supplied buffer was too
small to hold the log filename, the DbEnv.logFile method
will fail and throw a DbMemoryException
exception.
DbException
public void log_flush(DbLsn lsn) throws DbException
logFlush(DbLsn)
DbException
public void logFlush(DbLsn lsn) throws DbException
lsn
- All log records with DbLsn
values less than or equal to
the lsn parameter are written to disk. If lsn
is null, all records in the log are flushed.
java.lang.IllegalArgumentException
- The DbEnv.logFlush method
will fail and throw a IllegalArgumentException exception
if an invalid flag value or parameter was specified.
DbException
public void log_put(DbLsn lsn, Dbt data, int flags) throws DbException
logPut(DbLsn,Dbt,int)
DbException
public void logPut(DbLsn lsn, Dbt data, int flags) throws DbException
DbLsn
of the put record is returned in
the lsn parameter.
data
- the record to write 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 DbLsn
of the
previous log record for the same transaction, to support
chaining back through the transaction's log records during
undo.)
flags
- must be set to 0 or the
following value:
Db.DB_FLUSH
The log is forced to disk after this record is written,
guaranteeing that all records with DbLsn
values less than or equal
to the one being "put" are on disk before DbEnv.logPut
returns.
lsn
- references memory into which
the DbLsn
of the put record
is copied.
java.lang.IllegalArgumentException
- The DbEnv.logFlush
method
will fail and throw a IllegalArgumentException exception
if the record to be logged is larger than the maximum log
record; or if an invalid flag value or parameter was
specified.
DbException
public DbLogStat log_stat(int flags) throws DbException
logStat(int)
DbException
public DbLogStat logStat(int flags) throws DbException
The DbEnv.logStat method creates a DbLogStat object encapsulating the logging subsystem statistics. The following data fields are available from the DbLogStat object:
For convenience, the DbLogStat class has a toString method that lists all the data fields.
flags
- must be set to 0 or the
following value:
Db.DB_STAT_CLEAR
Reset statistics after returning their values.
java.lang.IllegalArgumentException
- The DbEnv.logStat method
will fail and throw a IllegalArgumentException exception
if an invalid flag value or parameter was specified.
DbException
public void set_lg_bsize(int lg_bsize) throws DbException
setLogBufferSize(int)
DbException
public void setLogBufferSize(int lg_bsize) throws DbException
DbEnv.setLogMax
) must be at
least four times the size of the in-memory log buffer. Log information is stored in-memory until the storage space fills up or transaction commit forces the information to be flushed to stable storage. In the presence of long-running transactions or transactions producing large amounts of data, larger buffer sizes can increase throughput.
The database environment's log buffer size may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lg_bsize", one or more whitespace characters, and the size in bytes. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
The DbEnv.setLogBufferSize method configures a database
environment, not only operations performed using the specified
DbEnv
handle.
The DbEnv.setLogBufferSize method may not be called after the
DbEnv.open
method is
called. If the database environment already exists when DbEnv.open
is called, the
information specified to DbEnv.setLogBufferSize will be
ignored.
lg_bsize
- the size of the in-memory
log buffer, in bytes.
java.lang.IllegalArgumentException
- The DbEnv.setLogBufferSize
method will fail and throw a IllegalArgumentException
exception if the method was called after DbEnv.open
was called; The
size of the log file is less than four times the size of
the in-memory log buffer; or if an invalid flag value or
parameter was specified.
DbException
public void set_lg_dir(java.lang.String dir) throws DbException
setLogDir(String)
DbException
public void setLogDir(java.lang.String dir) throws DbException
If no logging directory is specified, log files are created in the environment home directory. See Berkeley DB File Naming for more information.
For the greatest degree of recoverability from system or application failure, database files and log files should be located on separate physical devices.
The database environment's logging directory may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lg_dir", one or more whitespace characters, and the directory name. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
The DbEnv.setLogDir method configures operations performed
using the specified DbEnv
handle, not all operations performed on the underlying
database environment.
The DbEnv.setLogDir method may not be called after the DbEnv.open
method is called. If
the database environment already exists when DbEnv.open
is called, the
information specified to DbEnv.setLogDir must be consistent
with the existing environment or corruption can occur.
dir
- the directory used to store
the logging files.
java.lang.IllegalArgumentException
- The DbEnv.setLogDir method
will fail and throw a IllegalArgumentException exception
if the method was called after DbEnv.open
was called; or if
an invalid flag value or parameter was specified.
DbException
public void set_lg_max(int lg_max) throws DbException
setLogMax(int)
DbException
public void setLogMax(int lg_max) throws DbException
DbLsn
file offsets are unsigned four-byte values, the set value may
not be larger than the maximum unsigned four-byte value. The
size of the log file must be at least four times the size of
the in-memory log buffer (see DbEnv.setLogBufferSize
). See Log File Limits for more information.
The database environment's log file size may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lg_max", one or more whitespace characters, and the size in bytes. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
The DbEnv.setLogMax method configures a database environment,
not only operations performed using the specified DbEnv
handle.
The DbEnv.setLogMax method may be called at any time during the life of the application.
If no size is specified by the application, the size last specified for the database region will be used, or if no database region previously existed, the default will be used.
lg_max
- the size of a single log
file, in bytes.
java.lang.IllegalArgumentException
- The DbEnv.setLogMax method
will fail and throw a IllegalArgumentException exception
if the method was called after DbEnv.open
was called; the
size of the log file is less than four times the size of
the in-memory log buffer; The specified log file size was
too large; or if an invalid flag value or parameter was
specified.
DbException
public void set_lg_regionmax(int lg_regionmax) throws DbException
setLogRegionMax(int)
DbException
public void setLogRegionMax(int lg_regionmax) throws DbException
The database environment's log region size may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lg_regionmax", one or more whitespace characters, and the size in bytes. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.
The DbEnv.setLogRegionMax method configures a database
environment, not only operations performed using the specified
DbEnv
handle.
The DbEnv.setLogRegionMax method may not be called after the
DbEnv.open
method is
called. If the database environment already exists when DbEnv.open
is called, the
information specified to DbEnv.setLogRegionMax will be
ignored.
lg_regionmax
- the size of the logging area
in the Berkeley DB environment, in bytes.
java.lang.IllegalArgumentException
- The DbEnv.setLogRegionMax
method will fail and throw a IllegalArgumentException
exception if the method was called after DbEnv.open
was called; or if
an invalid flag value or parameter was specified.
DbException
public long get_cachesize() throws DbException
getCacheSize()
DbException
public long getCacheSize() throws DbException
The DbEnv.getCacheSize method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public int get_cachesize_ncache() throws DbException
getCacheSizeNcache()
DbException
public int getCacheSizeNcache() throws DbException
The DbEnv.getCacheSizeNcache method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public long get_mp_mmapsize() throws DbException
getMemoryPoolMapSize()
DbException
public long getMemoryPoolMapSize() throws DbException
The DbEnv.getMemoryPoolMapSize method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public DbMpoolStat memp_stat(int flags) throws DbException
memoryPoolStat(int)
DbException
public DbMpoolStat memoryPoolStat(int flags) throws DbException
The DbEnv.memoryPoolStat method creates a DbMpoolStat object encapsulating memory pool (that is, the buffer cache) statistics. The following data fields are available from the DbMpoolStat object:
For convenience, the DbMpoolStat class has a toString method that lists all the data fields.
flags
- must be set to 0 or the following value:
Db.DB_STAT_CLEAR
Reset statistics after returning their values.
DbException
- Signals that an exception of some sort
has occurred.public DbMpoolFStat[] memp_fstat(int flags) throws DbException
memoryPoolFileStat(int)
DbException
public DbMpoolFStat[] memoryPoolFileStat(int flags) throws DbException
flags
- must be set to 0 or the
following value:
Db.DB_STAT_CLEAR
Reset statistics after returning their values.
java.lang.IllegalArgumentException
- The DbEnv.memoryPoolStat
method will fail and throw a IllegalArgumentException
exception if an invalid flag value or parameter was
specified.
DbException
public int memp_trickle(int percent) throws DbException
memoryPoolTrickle(int)
DbException
public int memoryPoolTrickle(int percent) throws DbException
The purpose of the DbEnv.memoryPoolTrickle function 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.
nwrotep
- references memory into which
the number of pages written to reach the specified
percentage is copied.percent
- the percent of the pages in
the cache that should be clean.
java.lang.IllegalArgumentException
- The DbEnv.memoryPoolTrickle
method will fail and throw a IllegalArgumentException
exception if an invalid flag value or parameter was
specified.
DbException
public int get_tx_max() throws DbException
getTxnMax()
DbException
public int getTxnMax() throws DbException
The DbEnv.getTxnMax method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public long get_tx_timestamp() throws DbException
getTxnTimestamp()
DbException
public long getTxnTimestamp() throws DbException
The DbEnv.getTxnTimestamp method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public long get_timeout(int flag) throws DbException
getTimeout(int)
DbException
public long getTimeout(int flag) throws DbException
The DbEnv.getTimeout method may be called at any time during the life of the application.
flag
- must be set to one of the following
values:
Db.DB_SET_LOCK_TIMEOUT
Return the timeout value for locks in this database environment.
Db.DB_SET_TXN_TIMEOUT
Return the timeout value for transactions in this database environment.
DbException
- Signals that an exception of some sort
has occurred.public DbTxn txn_begin(DbTxn parent, int flags) throws DbException
txnBegin(DbTxn,int)
DbException
public DbTxn txnBegin(DbTxn parent, int flags) throws DbException
DbTxn
that uniquely identifies it. Calling the DbTxn.abort
, DbTxn.commit
or DbTxn.discard
methods will
discard the returned handle. Note: 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; not two children may be concurrently active in more than one thread of control at any one time.
Note: Cursors may not span transactions; that is, each cursor must be opened and closed within a single transaction.
Note: A parent transaction may not issue any Berkeley DB
operations -- except for DbEnv.txnBegin, DbTxn.abort
and DbTxn.commit
-- while it has
active child transactions (child transactions that have not
yet been committed or aborted).
flags
- must be set to 0 or by bitwise
inclusively OR 'ing together one or more of the
following values:
Db.DB_DIRTY_READ
All read operations performed by the transaction may
read modified but not yet committed data. Silently
ignored if the
flag was not specified
when the underlying database was opened. Db.DB_DIRTY_READ
Db.DB_TXN_NOSYNC
Do not synchronously flush the log when this transaction commits or prepares. This means the transaction will exhibit the ACI (atomicity, consistency, and isolation) properties, but not D (durability); that is, database integrity will be maintained but it is possible that this transaction may be undone during recovery.
This behavior may be set for a Berkeley DB environment
using the DbEnv.setFlags
method. Any value specified to this
method overrides that setting.
Db.DB_TXN_NOWAIT
If a lock is unavailable for any Berkeley DB operation
performed in the context of this transaction, cause the
operation to throw a DbDeadlockException
immediately instead of blocking on
the lock.
Db.DB_TXN_SYNC
Synchronously flush the log when this transaction commits or prepares. This means the transaction will exhibit all of the ACID (atomicity, consistency, isolation, and durability) properties.
This behavior is the default for Berkeley DB
environments unless the
flag was specified to the Db.DB_TXN_NOSYNC
DbEnv.setFlags
method.
Any value specified to this method overrides that
setting.
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 DbTxn.prepare
.
DbMemoryException
- If the maximum number of concurrent
transactions has been reached, the DbEnv.txnBegin method
will fail and throw a DbMemoryException
exception.
DbException
public void txn_checkpoint(int kbyte, int min, int flags) throws DbException
txnCheckpoint(int,int,int)
DbException
public void txnCheckpoint(int kbyte, int min, int flags) throws DbException
flags
- must be set to 0 or the
following value:
Db.DB_FORCE
Force a checkpoint record, even if there has been no activity since the last checkpoint.
kbyte
- If the kbyte
parameter is non-zero, a checkpoint will be done if more
than kbyte kilobytes of log data have been written
since the last checkpoint.min
- If the min parameter
is non-zero, a checkpoint will be done if more than min
minutes have passed since the last checkpoint.
java.lang.IllegalArgumentException
- The DbEnv.txnCheckpoint
method will fail and throw a IllegalArgumentException
exception if an invalid flag value or parameter was
specified.
DbException
public DbPreplist[] txn_recover(int count, int flags) throws DbException
txnRecover(int,int)
DbException
public DbPreplist[] txnRecover(int count, int flags) throws DbException
Db.DB_PRIVATE
flag. The DbEnv.txnRecover method returns a list of transactions that must be resolved by the application (committed, aborted or discarded). The return value is an array of objects of type DbPreplist; the following DbPreplist fields will be filled in:
The application must callDbTxn.abort
, DbTxn.commit
or DbTxn.discard
on each returned
DbTxn
handle before starting
any new operations.
count
- specifies the number of maximum size of
the array that should be returned.flags
- must be set to one of the following
values:
Db.DB_FIRST
Begin returning a list of prepared, but not yet resolved transactions.
Db.DB_NEXT
Continue returning a list of prepared, but not yet resolved transactions, starting where the last call to DbEnv.txnRecover left off.
DbException
- Signals that an exception of some sort
has occurred.public DbTxnStat txn_stat(int flags) throws DbException
txnStat(int)
DbException
public DbTxnStat txnStat(int flags) throws DbException
The DbEnv.txnStat method creates a DbTxnStat object encapsulating the transaction subsystem statistics. The following data fields are available from the DbTxnStat object:
For convenience, the DbTxnStat class has a toString method that lists all the data fields.
flags
- must be set to 0 or the
following value:
Db.DB_STAT_CLEAR
Reset statistics after returning their values.
java.lang.IllegalArgumentException
- The DbEnv.txnStat method
will fail and throw a IllegalArgumentException exception
if an invalid flag value or parameter was specified.
DbException
public long get_rep_limit() throws DbException
getReplicationLimit()
DbException
public long getReplicationLimit() throws DbException
The DbEnv.getReplicationLimit method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public int rep_elect(int nsites, int priority, int timeout) throws DbException
replicationElect(int,int,int)
DbException
public int replicationElect(int nsites, int priority, int timeout) throws DbException
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 the DbEnv.replicationElect method must not be the thread of control that processes incoming messages; processing the incoming messages is necessary to successfully complete an election.
nsites
- The nsites parameter indicates 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.priority
- the priority of this environment. It must
be a positive integer, or 0 if this environment is not
permitted to become a master (see Replication
environment priorities for more information).timeout
- specifies a timeout period for an
election. If the election has not completed after
timeout microseconds, the election will fail.
DbException
- The DbEnv.replicationElect method may
fail and throw DbException
, encapsulating one of the following non-zero
errors:
public int rep_process_message(Dbt control, Dbt rec, DbEnv.RepProcessMessage envid, DbLsn ret_lsn) throws DbException
replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn)
DbException
public int replicationProcessMessage(Dbt control, Dbt rec, DbEnv.RepProcessMessage envid, DbLsn ret_lsn) throws DbException
For implementation reasons, all incoming replication messages
must be processed using the same DbEnv
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.
The DbEnv.replicationProcessMessage method has additional return values:
control
- The control parameter should
reference a copy of the control parameter specified
by Berkeley DB on the sending environment.envid
- The envid parameter should contain
the local identifier that corresponds to the environment
that sent the message to be processed (see Replication
environment IDs for more information).rec
- The rec parameter should reference
a copy of the rec parameter specified by Berkeley
DB on the sending environment.ret_lsn
- If DbEnv.replicationProcessMessage method
returns Db.DB_REP_NOTPERM then the ret_lsn
parameter will contain the log sequence number of this
permanent log message that could not be written to disk.
If DbEnv.replicationProcessMessage method returns
Db.DB_REP_ISPERM then the ret_lsn parameter will
contain largest log sequence number of the permanent
records that are now written to disk as a result of
processing this message. In all other cases the value of
ret_lsn is undefined.
DB_REP_DUPMASTER
The DbEnv.replicationProcessMessage method will throw an
exception that encapsulates Db.DB_REP_DUPMASTER
if the replication group has more than one master.
DbEnv.replicationStart
method, and then call for an
election by calling DbEnv.replicationElect
.
DB_REP_HOLDELECTION
The DbEnv.replicationProcessMessage method will throw an
exception that encapsulates Db.DB_REP_HOLDELECTION
if an election is needed.
DbEnv.replicationElect
.
DB_REP_ISPERM
The DbEnv.replicationProcessMessage method will return
Db.DB_REP_ISPERM
if processing this message
results in the processing of records that are permanent.
DB_REP_NEWMASTER
The DbEnv.replicationProcessMessage method will return
Db.DB_REP_NEWMASTER
if a new master has
been elected.
DB_REP_NEWSITE
The DbEnv.replicationProcessMessage method will return
Db.DB_REP_NEWSITE
if the system received
contact information from a new environment.
DbEnv.replicationStart
. The application should take
whatever action is needed to establish a communication
channel with this new environment.
DB_REP_NOTPERM
The DbEnv.replicationProcessMessage method will return
Db.DB_REP_NOTPERM
if a message carrying a
flag was processed successfully, but was not written
to disk. Db.DB_REP_PERMANENT
DB_REP_OUTDATED
The DbEnv.replicationProcessMessage method will throw an
exception that encapsulates Db.DB_REP_OUTDATED
if the current environment's logs are too far out of
date with respect to the master to be automatically
synchronized.
DbException
- Signals that an exception of some sort
has occurred.public void rep_start(Dbt cdata, int flags) throws DbException
replicationStart(Dbt,int)
DbException
public void replicationStart(Dbt cdata, int flags) throws DbException
The enclosing database environment must already have been
opened by calling the DbEnv.open
method and must already have been configured to
send replication messages by calling the DbEnv.setReplicationTransport
method.
cdata
- an opaque data item that is
sent over the communication infrastructure when the client
or master comes online (see Connecting to a
new site for more information). If no such information
is useful, cdata should be null.flags
- must be set to one of the
following values:
Db.DB_REP_CLIENT
Configure the environment as a replication client.
Db.DB_REP_LOGSONLY
Configure the environment as a log files-only client.
Db.DB_REP_MASTER
Configure the environment as a replication master.
java.lang.IllegalArgumentException
- The DbEnv.replicationStart
method will fail and throw a IllegalArgumentException
exception if the database environment was not already
configured to communicate with a replication group by a
call to DbEnv.setReplicationTransport
; the database environment
was not already opened; or if an invalid flag value or
parameter was specified.
DbException
public DbRepStat rep_stat(int flags) throws DbException
replicationStat(int)
DbException
public DbRepStat replicationStat(int flags) throws DbException
The DbEnv.replicationStat method creates a DbRepStat object encapsulating the replication subsystem statistics. The following data fields are available from the DbRepStat object:
For convenience, the DbRepStat class has a toString method that lists all the data fields.
flags
- must be set to 0 or the
following value:
Db.DB_STAT_CLEAR
Reset statistics after returning their values.
java.lang.IllegalArgumentException
- The DbEnv.replicationStat
method will fail and throw a IllegalArgumentException
exception if an invalid flag value or parameter was
specified.
DbException
public void set_rep_limit(long bytes) throws DbException
setReplicationLimit(long)
DbException
public void setReplicationLimit(long bytes) throws DbException
DbEnv.replicationProcessMessage
method.
The DbEnv.setReplicationLimit method configures a database
environment, not only operations performed using the specified
DbEnv
handle.
The DbEnv.setReplicationLimit method may not be called before
the DbEnv.open
method has
been called.
bytes
- specifies the maximum number of bytes
that will be sent in a single call to DbEnv.replicationProcessMessage
method.
DbException
- Signals that an exception of some sort
has occurred.public void set_rep_transport(int envid, DbRepTransport send) throws DbException
setReplicationTransport(int,DbRepTransport)
DbException
public void setReplicationTransport(int envid, DbRepTransport send) throws DbException
DbException
public static java.lang.String strerror(int error)
This function is a superset of the ANSI C X3.159-1989 (ANSI C) strerror (3) function. If the error number error is greater than or equal to 0, then the string returned by the system function strerror (3) is returned. If the error number is less than 0, an error string appropriate to the corresponding Berkeley DB library error is returned. See Error returns to applications for more information.
error
- the error number for which an error message
string is wanted.
public static int get_version_major()
getVersionMajor()
public static int getVersionMajor()
The DbEnv.getVersionMajor method may be called at any time during the life of the application.
public static int get_version_minor()
getVersionMinor()
public static int getVersionMinor()
The DbEnv.getVersionMinor method may be called at any time during the life of the application.
public static int get_version_patch()
getVersionPatch()
public static int getVersionPatch()
The DbEnv.getVersionPatch method may be called at any time during the life of the application.
public static java.lang.String get_version_string()
getVersionString()
public static java.lang.String getVersionString()
The DbEnv.getVersionString method may be called at any time during the life of the application.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |