|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.sleepycat.db.Db
public class Db
The Db handle is the handle for a Berkeley DB database, which may or may not be part of a database environment.
The handle should not be closed while any other handle that refers
to the database is in use; for example, database handles must not
be closed while cursor handles into the database remain open, or
transactions that include operations on the database have not yet
been committed or aborted. Once the Db.close
, Db.remove
, or Db.rename
methods are called, the
handle may not be accessed again, regardless of the method's
return.
Field Summary | |
---|---|
static int |
DB_AFTER
A constant used to configure the system. |
static int |
DB_AGGRESSIVE
A constant used to configure the system. |
static int |
DB_APPEND
A constant used to configure the system. |
static int |
DB_ARCH_ABS
A constant used to configure the system. |
static int |
DB_ARCH_DATA
A constant used to configure the system. |
static int |
DB_ARCH_LOG
A constant used to configure the system. |
static int |
DB_ARCH_REMOVE
A constant used to configure the system. |
static int |
DB_AUTO_COMMIT
A constant used to configure the system. |
static int |
DB_BEFORE
A constant used to configure the system. |
static int |
DB_BTREE
A constant used to configure the system. |
static int |
DB_CACHED_COUNTS
|
static int |
DB_CDB_ALLDB
A constant used to configure the system. |
static int |
DB_CHKSUM
A constant used to configure the system. |
static int |
DB_CONSUME
A constant used to configure the system. |
static int |
DB_CONSUME_WAIT
A constant used to configure the system. |
static int |
DB_CREATE
A constant used to configure the system. |
static int |
DB_CURRENT
A constant used to configure the system. |
static int |
DB_CXX_NO_EXCEPTIONS
|
static int |
DB_DBT_MALLOC
A constant used to configure the system. |
static int |
DB_DBT_PARTIAL
A constant used to configure the system. |
static int |
DB_DBT_REALLOC
A constant used to configure the system. |
static int |
DB_DBT_USERMEM
A constant used to configure the system. |
static int |
DB_DIRECT_DB
A constant used to configure the system. |
static int |
DB_DIRECT_LOG
A constant used to configure the system. |
static int |
DB_DIRTY_READ
A constant used to configure the system. |
static int |
DB_DONOTINDEX
A constant used to configure the system. |
static int |
DB_DUP
A constant used to configure the system. |
static int |
DB_DUPSORT
A constant used to configure the system. |
static int |
DB_EID_BROADCAST
A constant used to configure the system. |
static int |
DB_EID_INVALID
|
static int |
DB_ENCRYPT
A constant used to configure the system. |
static int |
DB_ENCRYPT_AES
A constant used to configure the system. |
static int |
DB_EXCL
A constant used to configure the system. |
static int |
DB_FAST_STAT
A constant used to configure the system. |
static int |
DB_FILEOPEN
|
static int |
DB_FIRST
A constant used to configure the system. |
static int |
DB_FLUSH
A constant used to configure the system. |
static int |
DB_FORCE
A constant used to configure the system. |
static int |
DB_GET_BOTH
A constant used to configure the system. |
static int |
DB_GET_BOTH_RANGE
A constant used to configure the system. |
static int |
DB_GET_RECNO
A constant used to configure the system. |
static int |
DB_HASH
A constant used to configure the system. |
static int |
DB_INIT_CDB
A constant used to configure the system. |
static int |
DB_INIT_LOCK
A constant used to configure the system. |
static int |
DB_INIT_LOG
A constant used to configure the system. |
static int |
DB_INIT_MPOOL
A constant used to configure the system. |
static int |
DB_INIT_REP
A constant used to configure the system. |
static int |
DB_INIT_TXN
A constant used to configure the system. |
static int |
DB_JOIN_ITEM
A constant used to configure the system. |
static int |
DB_JOIN_NOSORT
A constant used to configure the system. |
static int |
DB_JOINENV
A constant used to configure the system. |
static int |
DB_KEYEMPTY
A constant used to configure the system. |
static int |
DB_KEYEXIST
A constant used to configure the system. |
static int |
DB_KEYFIRST
A constant used to configure the system. |
static int |
DB_KEYLAST
A constant used to configure the system. |
static int |
DB_LAST
A constant used to configure the system. |
static int |
DB_LOCK_DEADLOCK
|
static int |
DB_LOCK_DEFAULT
A constant used to configure the system. |
static int |
DB_LOCK_EXPIRE
A constant used to configure the system. |
static int |
DB_LOCK_GET
A constant used to configure the system. |
static int |
DB_LOCK_GET_TIMEOUT
A constant used to configure the system. |
static int |
DB_LOCK_IREAD
A constant used to configure the system. |
static int |
DB_LOCK_IWR
A constant used to configure the system. |
static int |
DB_LOCK_IWRITE
A constant used to configure the system. |
static int |
DB_LOCK_MAXLOCKS
A constant used to configure the system. |
static int |
DB_LOCK_MINLOCKS
A constant used to configure the system. |
static int |
DB_LOCK_MINWRITE
A constant used to configure the system. |
static int |
DB_LOCK_NOTGRANTED
|
static int |
DB_LOCK_NOWAIT
A constant used to configure the system. |
static int |
DB_LOCK_OLDEST
A constant used to configure the system. |
static int |
DB_LOCK_PUT
A constant used to configure the system. |
static int |
DB_LOCK_PUT_ALL
A constant used to configure the system. |
static int |
DB_LOCK_PUT_OBJ
A constant used to configure the system. |
static int |
DB_LOCK_RANDOM
A constant used to configure the system. |
static int |
DB_LOCK_READ
A constant used to configure the system. |
static int |
DB_LOCK_TIMEOUT
A constant used to configure the system. |
static int |
DB_LOCK_WRITE
A constant used to configure the system. |
static int |
DB_LOCK_YOUNGEST
A constant used to configure the system. |
static int |
DB_LOCKDOWN
A constant used to configure the system. |
static int |
DB_LOG_AUTOREMOVE
A constant used to configure the system. |
static int |
DB_MPOOL_NOFILE
A constant used to configure the system. |
static int |
DB_MULTIPLE
A constant used to configure the system. |
static int |
DB_MULTIPLE_KEY
A constant used to configure the system. |
static int |
DB_NEXT
A constant used to configure the system. |
static int |
DB_NEXT_DUP
A constant used to configure the system. |
static int |
DB_NEXT_NODUP
A constant used to configure the system. |
static int |
DB_NODUPDATA
A constant used to configure the system. |
static int |
DB_NOLOCKING
A constant used to configure the system. |
static int |
DB_NOMMAP
A constant used to configure the system. |
static int |
DB_NOORDERCHK
A constant used to configure the system. |
static int |
DB_NOOVERWRITE
A constant used to configure the system. |
static int |
DB_NOPANIC
A constant used to configure the system. |
static int |
DB_NOSERVER
|
static int |
DB_NOSERVER_HOME
A constant used to configure the system. |
static int |
DB_NOSERVER_ID
A constant used to configure the system. |
static int |
DB_NOSYNC
A constant used to configure the system. |
static int |
DB_NOTFOUND
A constant used to configure the system. |
static int |
DB_OLD_VERSION
A constant used to configure the system. |
static int |
DB_ORDERCHKONLY
A constant used to configure the system. |
static int |
DB_OVERWRITE
A constant used to configure the system. |
static int |
DB_PAGE_NOTFOUND
|
static int |
DB_PANIC_ENVIRONMENT
A constant used to configure the system. |
static int |
DB_POSITION
A constant used to configure the system. |
static int |
DB_PREV
A constant used to configure the system. |
static int |
DB_PREV_NODUP
A constant used to configure the system. |
static int |
DB_PRINTABLE
A constant used to configure the system. |
static int |
DB_PRIORITY_DEFAULT
A constant used to configure the system. |
static int |
DB_PRIORITY_HIGH
A constant used to configure the system. |
static int |
DB_PRIORITY_LOW
A constant used to configure the system. |
static int |
DB_PRIORITY_VERY_HIGH
A constant used to configure the system. |
static int |
DB_PRIORITY_VERY_LOW
A constant used to configure the system. |
static int |
DB_PRIVATE
A constant used to configure the system. |
static int |
DB_QUEUE
A constant used to configure the system. |
static int |
DB_RDONLY
A constant used to configure the system. |
static int |
DB_RECNO
A constant used to configure the system. |
static int |
DB_RECNUM
A constant used to configure the system. |
static int |
DB_RECORDCOUNT
|
static int |
DB_RECOVER
A constant used to configure the system. |
static int |
DB_RECOVER_FATAL
A constant used to configure the system. |
static int |
DB_REGION_INIT
A constant used to configure the system. |
static int |
DB_RENUMBER
A constant used to configure the system. |
static int |
DB_REP_CLIENT
A constant used to configure the system. |
static int |
DB_REP_DUPMASTER
A constant used to configure the system. |
static int |
DB_REP_HANDLE_DEAD
A constant used to configure the system. |
static int |
DB_REP_HOLDELECTION
A constant used to configure the system. |
static int |
DB_REP_ISPERM
A constant used to configure the system. |
static int |
DB_REP_LOGSONLY
A constant used to configure the system. |
static int |
DB_REP_MASTER
A constant used to configure the system. |
static int |
DB_REP_NEWMASTER
A constant used to configure the system. |
static int |
DB_REP_NEWSITE
A constant used to configure the system. |
static int |
DB_REP_NOBUFFER
A constant used to configure the system. |
static int |
DB_REP_NOTPERM
A constant used to configure the system. |
static int |
DB_REP_OUTDATED
A constant used to configure the system. |
static int |
DB_REP_PERMANENT
A constant used to configure the system. |
static int |
DB_REP_UNAVAIL
A constant used to configure the system. |
static int |
DB_REVSPLITOFF
A constant used to configure the system. |
static int |
DB_RMW
A constant used to configure the system. |
static int |
DB_RPCCLIENT
A constant used to configure the system. |
static int |
DB_RUNRECOVERY
|
static int |
DB_SALVAGE
A constant used to configure the system. |
static int |
DB_SECONDARY_BAD
A constant used to configure the system. |
static int |
DB_SET
A constant used to configure the system. |
static int |
DB_SET_LOCK_TIMEOUT
A constant used to configure the system. |
static int |
DB_SET_RANGE
A constant used to configure the system. |
static int |
DB_SET_RECNO
A constant used to configure the system. |
static int |
DB_SET_TXN_TIMEOUT
A constant used to configure the system. |
static int |
DB_SNAPSHOT
A constant used to configure the system. |
static int |
DB_STAT_CLEAR
A constant used to configure the system. |
static int |
DB_SYSTEM_MEM
A constant used to configure the system. |
static int |
DB_THREAD
A constant used to configure the system. |
static int |
DB_TIME_NOTGRANTED
A constant used to configure the system. |
static int |
DB_TRUNCATE
A constant used to configure the system. |
static int |
DB_TXN_ABORT
A constant used to configure the system. |
static int |
DB_TXN_APPLY
A constant used to configure the system. |
static int |
DB_TXN_BACKWARD_ROLL
A constant used to configure the system. |
static int |
DB_TXN_FORWARD_ROLL
A constant used to configure the system. |
static int |
DB_TXN_NOSYNC
A constant used to configure the system. |
static int |
DB_TXN_NOT_DURABLE
A constant used to configure the system. |
static int |
DB_TXN_NOWAIT
A constant used to configure the system. |
static int |
DB_TXN_PRINT
A constant used to configure the system. |
static int |
DB_TXN_SYNC
A constant used to configure the system. |
static int |
DB_TXN_WRITE_NOSYNC
A constant used to configure the system. |
static int |
DB_UNKNOWN
A constant used to configure the system. |
static int |
DB_UPGRADE
A constant used to configure the system. |
static int |
DB_USE_ENVIRON
A constant used to configure the system. |
static int |
DB_USE_ENVIRON_ROOT
A constant used to configure the system. |
static int |
DB_VERB_CHKPOINT
A constant used to configure the system. |
static int |
DB_VERB_DEADLOCK
A constant used to configure the system. |
static int |
DB_VERB_RECOVERY
A constant used to configure the system. |
static int |
DB_VERB_REPLICATION
A constant used to configure the system. |
static int |
DB_VERB_WAITSFOR
A constant used to configure the system. |
static int |
DB_VERIFY
A constant used to configure the system. |
static int |
DB_VERIFY_BAD
A constant used to configure the system. |
static int |
DB_VERSION_MAJOR
|
static int |
DB_VERSION_MINOR
|
static int |
DB_VERSION_PATCH
|
static int |
DB_WRITECURSOR
A constant used to configure the system. |
static int |
DB_XA_CREATE
A constant used to configure the system. |
static int |
DB_XIDDATASIZE
A constant used to configure the system. |
static int |
DB_YIELDCPU
A constant used to configure the system. |
protected boolean |
swigCMemOwn
|
Constructor Summary | |
---|---|
protected |
Db()
|
|
Db(DbEnv dbenv,
int flags)
The constructor creates a Db object that is the handle for a Berkeley DB database. |
protected |
Db(long cPtr,
boolean cMemoryOwn)
|
Method Summary | |
---|---|
void |
associate(DbTxn txnid,
Db secondary,
DbSecondaryKeyCreate callback,
int flags)
|
void |
close(int flags)
The Db.close method flushes any cached database information to disk, closes any open cursors, frees any allocated resources, and closes any underlying files. |
Dbc |
cursor(DbTxn txnid,
int flags)
The Db.cursor method returns a created database cursor. |
int |
del(DbTxn txnid,
Dbt key,
int flags)
Deprecated. As of Berkeley DB 4.2, replaced by delete(DbTxn,Dbt,int) |
protected void |
delete()
|
int |
delete(DbTxn txnid,
Dbt key,
int flags)
The Db.delete method removes key/data pairs from the database. |
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_bt_minkey()
Deprecated. As of Berkeley DB 4.2, replaced by getBtreeMinKey() |
boolean |
get_byteswapped()
Deprecated. As of Berkeley DB 4.2, replaced by isByteSwapped() |
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_dbname()
Deprecated. As of Berkeley DB 4.2, replaced by getDatabaseName() |
int |
get_encrypt_flags()
Deprecated. As of Berkeley DB 4.2, replaced by getEncryptFlags() |
DbEnv |
get_env()
Deprecated. As of Berkeley DB 4.2, replaced by getDbEnv() |
java.lang.String |
get_errpfx()
Deprecated. As of Berkeley DB 4.2, replaced by getErrorPrefix() |
java.lang.String |
get_filename()
Deprecated. As of Berkeley DB 4.2, replaced by getFileName() |
int |
get_flags_raw()
|
int |
get_flags()
Deprecated. As of Berkeley DB 4.2, replaced by getFlags() |
int |
get_h_ffactor()
Deprecated. As of Berkeley DB 4.2, replaced by getHashFillFactor() |
int |
get_h_nelem()
Deprecated. As of Berkeley DB 4.2, replaced by getHashNumElements() |
int |
get_lorder()
Deprecated. As of Berkeley DB 4.2, replaced by getByteOrder() |
DbMpoolFile |
get_mpf()
The Db.get_mpf method returns the handle for the cache file underlying the database. |
int |
get_open_flags()
Deprecated. As of Berkeley DB 4.2, replaced by getOpenFlags() |
int |
get_pagesize()
Deprecated. As of Berkeley DB 4.2, replaced by getPageSize() |
int |
get_q_extentsize()
Deprecated. As of Berkeley DB 4.2, replaced by getQueueExtentSize() |
int |
get_re_delim()
Deprecated. As of Berkeley DB 4.2, replaced by getRecordDelimiter() |
int |
get_re_len()
Deprecated. As of Berkeley DB 4.2, replaced by getRecordLength() |
int |
get_re_pad()
Deprecated. As of Berkeley DB 4.2, replaced by getRecordPad() |
java.lang.String |
get_re_source()
Deprecated. As of Berkeley DB 4.2, replaced by getRecordSource() |
boolean |
get_transactional()
Deprecated. As of Berkeley DB 4.2, replaced by isTransactional() |
int |
get_type()
Deprecated. As of Berkeley DB 4.2, replaced by getDbType() |
int |
get(DbTxn txnid,
Dbt key,
Dbt pkey,
Dbt data,
int flags)
The Db.get method retrieves key/data pairs from the database. |
int |
get(DbTxn txnid,
Dbt key,
Dbt data,
int flags)
The Db.get method retrieves key/data pairs from the database. |
int |
getBtreeMinKey()
The Db.getBtreeMinKey method returns the minimum number of key/data pairs intended to be stored on any single Btree leaf page. |
int |
getByteOrder()
The Db.getByteOrder method returns the database byte order; a byte order of 4,321 indicates a big endian order, and a byte order of 1,234 indicates a little endian order. |
long |
getCacheSize()
The Db.getCacheSize method returns the size of the cache. |
int |
getCacheSizeNcache()
The DbEnv.getCacheSizeNcache method returns the number of caches. |
protected static long |
getCPtr(Db obj)
|
java.lang.String |
getDatabaseName()
The Db.getDatabaseName method returns the current database name. |
DbEnv |
getDbEnv()
The Db.getDbEnv method returns the handle for the database environment underlying the database. |
int |
getDbType()
The Db.getDbType method returns the type of the underlying access method (and file format). |
int |
getEncryptFlags()
The Db.getEncryptFlags method returns the encryption flags. |
java.lang.String |
getErrorPrefix()
The Db.getErrorPrefix method returns the error prefix. |
java.lang.String |
getFileName()
The Db.getFileName method returns the current filename. |
int |
getFlags()
The Db.getFlags method returns the current flags. |
int |
getHashFillFactor()
The Db.getHashFillFactor method returns the hash table density. |
int |
getHashNumElements()
The Db.getHashNumElements method returns the estimate of the final size of the hash table. |
int |
getOpenFlags()
The Db.getOpenFlags method returns the current open method flags. |
int |
getPageSize()
The Db.getPageSize method returns the page size. |
int |
getQueueExtentSize()
The Db.getQueueExtentSize method returns the number of pages in an extent. |
int |
getRecordDelimiter()
The Db.getRecordDelimiter method returns the delimiting byte. |
int |
getRecordLength()
The Db.getRecordLength method returns the record length. |
int |
getRecordPad()
The Db.getRecordPad method returns the pad character. |
java.lang.String |
getRecordSource()
The Db.getRecordSource method returns the source file. |
boolean |
isByteSwapped()
The Db.isByteSwapped method returns false if the underlying database files were created on an architecture of the same byte order as the current one, and true if they were not (that is, big-endian on a little-endian machine, or vice versa). |
boolean |
isEncrypted()
The Db.isEncrypted
method returns false if the underlying database files are
encrypted and true if they are not. |
boolean |
isTransactional()
The Db.isTransactional method returns true if the Db handle has been opened in a
transactional mode. |
Dbc |
join(Dbc[] curslist,
int flags)
The Db.join method creates a specialized join cursor for use in performing equality or natural joins on secondary indices. |
void |
key_range(DbTxn txnid,
Dbt key,
DbKeyRange key_range,
int flags)
Deprecated. As of Berkeley DB 4.2, replaced by keyRange(DbTxn,Dbt,DbKeyRange,int) |
void |
keyRange(DbTxn txnid,
Dbt key,
DbKeyRange key_range,
int flags)
The Db.keyRange method returns an estimate of the proportion of keys that are less than, equal to, and greater than the specified key. |
void |
open(DbTxn txnid,
java.lang.String file,
java.lang.String database,
int type,
int flags,
int mode)
The Db.open method opens the database represented by the file and database parameters for both reading and writing. |
int |
pget(DbTxn txnid,
Dbt key,
Dbt pkey,
Dbt data,
int flags)
Deprecated. Replaced in Berkeley DB 4.2 by get(DbTxn,Dbt,Dbt,Dbt,int) |
int |
put(DbTxn txnid,
Dbt key,
Dbt data,
int flags)
The Db.put method stores key/data pairs in the database. |
void |
remove(java.lang.String file,
java.lang.String database,
int flags)
The Db.remove method removes the database specified by the file and database parameters. |
void |
rename(java.lang.String file,
java.lang.String database,
java.lang.String newname,
int flags)
The Db.rename method renames the database specified by the file and database parameters to newname . |
void |
set_append_recno(DbAppendRecno db_append_recno_fcn)
Deprecated. As of Berkeley DB 4.2, replaced by setAppendRecno(DbAppendRecno) |
void |
set_bt_compare(DbBtreeCompare bt_compare_fcn)
Deprecated. As of Berkeley DB 4.2, replaced by setBtreeCompare(DbBtreeCompare) |
void |
set_bt_maxkey(int maxkey)
|
void |
set_bt_minkey(int bt_minkey)
Deprecated. As of Berkeley DB 4.2, replaced by setBtreeMinKey(int) |
void |
set_bt_prefix(DbBtreePrefix bt_prefix_fcn)
Deprecated. As of Berkeley DB 4.2, replaced by setBtreePrefix(DbBtreePrefix) |
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_dup_compare(DbDupCompare dup_compare_fcn)
Deprecated. As of Berkeley DB 4.2, replaced by setDuplicateCompare(DbDupCompare) |
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(DbFeedback feedback)
Deprecated. Replaced in Berkeley DB 4.2 by setFeedbackHandler(DbFeedbackHandler) |
void |
set_flags(int flags)
Deprecated. As of Berkeley DB 4.2, replaced by setFlags(int) |
void |
set_h_ffactor(int h_ffactor)
Deprecated. As of Berkeley DB 4.2, replaced by setHashFillFactor(int) |
void |
set_h_hash(DbHash h_hash_fcn)
Deprecated. As of Berkeley DB 4.2, replaced by setHash(DbHash) |
void |
set_h_nelem(int h_nelem)
Deprecated. As of Berkeley DB 4.2, replaced by setHashNumElements(int) |
void |
set_lorder(int lorder)
Deprecated. As of Berkeley DB 4.2, replaced by setByteOrder(int) |
void |
set_pagesize(long pagesize)
Deprecated. As of Berkeley DB 4.2, replaced by setPageSize(long) |
void |
set_q_extentsize(int extentsize)
Deprecated. As of Berkeley DB 4.2, replaced by setQueueExtentSize(int) |
void |
set_re_delim(int re_delim)
Deprecated. As of Berkeley DB 4.2, replaced by setRecordDelimiter(int) |
void |
set_re_len(int re_len)
Deprecated. As of Berkeley DB 4.2, replaced by setRecordLength(int) |
void |
set_re_pad(int re_pad)
Deprecated. As of Berkeley DB 4.2, replaced by setRecordPad(int) |
void |
set_re_source(java.lang.String source)
Deprecated. As of Berkeley DB 4.2, replaced by setRecordSource(String) |
void |
setAppendRecno(DbAppendRecno db_append_recno_fcn)
|
void |
setBtreeCompare(DbBtreeCompare bt_compare_fcn)
|
void |
setBtreeMinKey(int bt_minkey)
Set the minimum number of key/data pairs intended to be stored on any single Btree leaf page. |
void |
setBtreePrefix(DbBtreePrefix bt_prefix_fcn)
|
void |
setByteOrder(int lorder)
Set the byte order for integers in the stored database metadata. |
void |
setCacheSize(long bytes,
int ncache)
Set the size of the shared memory buffer pool -- that is, the cache. |
void |
setDuplicateCompare(DbDupCompare dup_compare_fcn)
|
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(DbFeedbackHandler db_feedback_fcn)
|
void |
setFlags(int flags)
Configure a database. |
void |
setHash(DbHash h_hash_fcn)
|
void |
setHashFillFactor(int h_ffactor)
Set the desired density within the hash table. |
void |
setHashNumElements(int h_nelem)
Set an estimate of the final size of the hash table. |
void |
setPageSize(long pagesize)
Set the size of the pages used to hold items in the database, in bytes. |
void |
setPanicHandler(DbPanicHandler db_panic_fcn)
Errors can occur in the Berkeley DB library where the only solution is to shut down the application and run recovery (for example, if Berkeley DB is unable to allocate heap memory). |
void |
setQueueExtentSize(int extentsize)
Set the size of the extents used to hold pages in a Queue database, specified as a number of pages. |
void |
setRecordDelimiter(int re_delim)
Set the delimiting byte used to mark the end of a record in the backing source file for the Recno access method. |
void |
setRecordLength(int re_len)
For the Queue access method, specify that the records are of length re_len . |
void |
setRecordPad(int re_pad)
Set the padding character for short, fixed-length records for the Queue and Recno access methods. |
void |
setRecordSource(java.lang.String source)
Set the underlying source file for the Recno access method. |
java.lang.Object |
stat(int flags)
The Db.stat method creates a statistical structure and fills it with statistics for the database. |
void |
sync(int flags)
The Db.sync method flushes any cached information to disk. |
int |
truncate(DbTxn txnid,
int flags)
The Db.truncate method empties the database, discarding all records it contains. |
void |
upgrade(java.lang.String file,
int flags)
The Db.upgrade method upgrades all of the databases included in the file file , if necessary. |
void |
verify(java.lang.String file,
java.lang.String database,
java.io.OutputStream outfile,
int flags)
The Db.verify method verifies the integrity of all databases in the file specified by the file parameter, and optionally outputs the databases' key/data pairs to the file stream specified by the outfile parameter. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
protected boolean swigCMemOwn
public static final int DB_BTREE
public static final int DB_DONOTINDEX
associate(DbTxn,Db,DbSecondaryKeyCreate,int)
DbSecondaryKeyCreate.secondaryKeyCreate(Db,Dbt,Dbt,Dbt)
public static final int DB_FILEOPEN
public static final int DB_HASH
public static final int DB_KEYEMPTY
delete(DbTxn,Dbt,int)
get(DbTxn,Dbt,Dbt,int)
get(DbTxn,Dbt,Dbt,Dbt,int)
Dbc.delete(int)
Dbc.get(Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,Dbt,int)
public static final int DB_KEYEXIST
public static final int DB_LOCK_DEADLOCK
public static final int DB_LOCK_NOTGRANTED
public static final int DB_NOSERVER
public static final int DB_NOSERVER_HOME
public static final int DB_NOSERVER_ID
public static final int DB_NOTFOUND
delete(DbTxn,Dbt,int)
get(DbTxn,Dbt,Dbt,int)
get(DbTxn,Dbt,Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,Dbt,int)
Dbc.put(Dbt,Dbt,int)
Dbc.put(Dbt,Dbt,int)
Dbc.put(Dbt,Dbt,int)
DbLogc.get(DbLsn,Dbt,int)
DbLogc.get(DbLsn,Dbt,int)
DbLogc.get(DbLsn,Dbt,int)
DbLogc.get(DbLsn,Dbt,int)
public static final int DB_OLD_VERSION
public static final int DB_PAGE_NOTFOUND
public static final int DB_QUEUE
public static final int DB_RECNO
public static final int DB_REP_DUPMASTER
DbEnv.replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn)
DbEnv.replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn)
public static final int DB_REP_HANDLE_DEAD
associate(DbTxn,Db,DbSecondaryKeyCreate,int)
cursor(DbTxn,int)
delete(DbTxn,Dbt,int)
get(DbTxn,Dbt,Dbt,int)
get(DbTxn,Dbt,Dbt,Dbt,int)
join(Dbc[],int)
keyRange(DbTxn,Dbt,DbKeyRange,int)
open(DbTxn,String,String,int,int,int)
put(DbTxn,Dbt,Dbt,int)
stat(int)
sync(int)
Dbc.count(int)
Dbc.delete(int)
Dbc.dup(int)
Dbc.get(Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,Dbt,int)
Dbc.put(Dbt,Dbt,int)
public static final int DB_REP_HOLDELECTION
DbEnv.replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn)
DbEnv.replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn)
public static final int DB_REP_NEWMASTER
DbEnv.replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn)
DbEnv.replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn)
public static final int DB_REP_NEWSITE
DbEnv.replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn)
DbEnv.replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn)
public static final int DB_REP_OUTDATED
DbEnv.replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn)
DbEnv.replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn)
public static final int DB_RUNRECOVERY
public static final int DB_SECONDARY_BAD
delete(DbTxn,Dbt,int)
get(DbTxn,Dbt,Dbt,int)
get(DbTxn,Dbt,Dbt,Dbt,int)
join(Dbc[],int)
Dbc.delete(int)
Dbc.get(Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,Dbt,int)
public static final int DB_TXN_ABORT
public static final int DB_TXN_APPLY
public static final int DB_TXN_BACKWARD_ROLL
public static final int DB_TXN_FORWARD_ROLL
public static final int DB_TXN_PRINT
public static final int DB_UNKNOWN
public static final int DB_VERIFY_BAD
public static final int DB_AFTER
public static final int DB_AGGRESSIVE
public static final int DB_APPEND
public static final int DB_ARCH_ABS
public static final int DB_ARCH_DATA
public static final int DB_ARCH_LOG
public static final int DB_ARCH_REMOVE
public static final int DB_AUTO_COMMIT
associate(DbTxn,Db,DbSecondaryKeyCreate,int)
delete(DbTxn,Dbt,int)
get(DbTxn,Dbt,Dbt,int)
get(DbTxn,Dbt,Dbt,Dbt,int)
open(DbTxn,String,String,int,int,int)
put(DbTxn,Dbt,Dbt,int)
truncate(DbTxn,int)
DbEnv.dbRemove(DbTxn,String,String,int)
DbEnv.dbRename(DbTxn,String,String,String,int)
DbEnv.setFlags(int,boolean)
public static final int DB_BEFORE
public static final int DB_CACHED_COUNTS
public static final int DB_CDB_ALLDB
public static final int DB_CHKSUM
public static final int DB_CONSUME
public static final int DB_CONSUME_WAIT
public static final int DB_CREATE
associate(DbTxn,Db,DbSecondaryKeyCreate,int)
open(DbTxn,String,String,int,int,int)
DbEnv.open(String,int,int)
public static final int DB_CURRENT
public static final int DB_CXX_NO_EXCEPTIONS
public static final int DB_DBT_MALLOC
public static final int DB_DBT_PARTIAL
public static final int DB_DBT_REALLOC
public static final int DB_DBT_USERMEM
public static final int DB_DIRECT_DB
public static final int DB_DIRECT_LOG
public static final int DB_DIRTY_READ
cursor(DbTxn,int)
get(DbTxn,Dbt,Dbt,int)
get(DbTxn,Dbt,Dbt,Dbt,int)
join(Dbc[],int)
open(DbTxn,String,String,int,int,int)
Dbc.get(Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,Dbt,int)
DbEnv.txnBegin(DbTxn,int)
public static final int DB_DUP
public static final int DB_DUPSORT
public static final int DB_EID_BROADCAST
public static final int DB_EID_INVALID
public static final int DB_ENCRYPT
public static final int DB_ENCRYPT_AES
public static final int DB_EXCL
public static final int DB_FAST_STAT
public static final int DB_FIRST
public static final int DB_FLUSH
public static final int DB_FORCE
public static final int DB_GET_BOTH
public static final int DB_GET_BOTH_RANGE
public static final int DB_GET_RECNO
public static final int DB_INIT_CDB
public static final int DB_INIT_LOCK
public static final int DB_INIT_LOG
public static final int DB_INIT_MPOOL
public static final int DB_INIT_REP
public static final int DB_INIT_TXN
public static final int DB_JOINENV
public static final int DB_JOIN_ITEM
public static final int DB_JOIN_NOSORT
public static final int DB_KEYFIRST
public static final int DB_KEYLAST
public static final int DB_LAST
public static final int DB_LOCKDOWN
public static final int DB_LOCK_DEFAULT
public static final int DB_LOCK_EXPIRE
public static final int DB_LOCK_GET
public static final int DB_LOCK_GET_TIMEOUT
public static final int DB_LOCK_IREAD
public static final int DB_LOCK_IWR
public static final int DB_LOCK_IWRITE
public static final int DB_LOCK_MAXLOCKS
public static final int DB_LOCK_MINLOCKS
public static final int DB_LOCK_MINWRITE
public static final int DB_LOCK_NOWAIT
public static final int DB_LOCK_OLDEST
public static final int DB_LOCK_PUT
public static final int DB_LOCK_PUT_ALL
public static final int DB_LOCK_PUT_OBJ
public static final int DB_LOCK_RANDOM
public static final int DB_LOCK_READ
public static final int DB_LOCK_TIMEOUT
public static final int DB_LOCK_WRITE
public static final int DB_LOCK_YOUNGEST
public static final int DB_LOG_AUTOREMOVE
public static final int DB_MPOOL_NOFILE
public static final int DB_MULTIPLE
public static final int DB_MULTIPLE_KEY
public static final int DB_NEXT
public static final int DB_NEXT_DUP
public static final int DB_NEXT_NODUP
public static final int DB_NODUPDATA
public static final int DB_NOLOCKING
public static final int DB_NOMMAP
public static final int DB_NOORDERCHK
public static final int DB_NOOVERWRITE
public static final int DB_NOPANIC
public static final int DB_NOSYNC
public static final int DB_ORDERCHKONLY
public static final int DB_OVERWRITE
public static final int DB_PANIC_ENVIRONMENT
public static final int DB_POSITION
public static final int DB_PREV
public static final int DB_PREV_NODUP
public static final int DB_PRINTABLE
public static final int DB_PRIORITY_DEFAULT
public static final int DB_PRIORITY_HIGH
public static final int DB_PRIORITY_LOW
public static final int DB_PRIORITY_VERY_HIGH
public static final int DB_PRIORITY_VERY_LOW
public static final int DB_PRIVATE
public static final int DB_RDONLY
public static final int DB_RECNUM
public static final int DB_RECORDCOUNT
public static final int DB_RECOVER
DbEnv.open(String,int,int)
DbEnv.setFeedbackHandler(DbEnvFeedbackHandler)
DbEnvFeedbackHandler.feedback(DbEnv,int,int)
public static final int DB_RECOVER_FATAL
public static final int DB_REGION_INIT
public static final int DB_RENUMBER
public static final int DB_REP_CLIENT
public static final int DB_REP_ISPERM
DbEnv.replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn)
DbEnv.replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn)
public static final int DB_REP_LOGSONLY
public static final int DB_REP_MASTER
public static final int DB_REP_NOBUFFER
public static final int DB_REP_NOTPERM
DbEnv.replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn)
DbEnv.replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn)
public static final int DB_REP_PERMANENT
public static final int DB_REP_UNAVAIL
public static final int DB_REVSPLITOFF
public static final int DB_RMW
get(DbTxn,Dbt,Dbt,int)
get(DbTxn,Dbt,Dbt,Dbt,int)
join(Dbc[],int)
Dbc.get(Dbt,Dbt,int)
Dbc.get(Dbt,Dbt,Dbt,int)
public static final int DB_RPCCLIENT
public static final int DB_SALVAGE
public static final int DB_SET
public static final int DB_SET_LOCK_TIMEOUT
public static final int DB_SET_RANGE
public static final int DB_SET_RECNO
public static final int DB_SET_TXN_TIMEOUT
public static final int DB_SNAPSHOT
public static final int DB_STAT_CLEAR
DbEnv.lockStat(int)
DbEnv.logStat(int)
DbEnv.memoryPoolStat(int)
DbEnv.memoryPoolFileStat(int)
DbEnv.replicationStat(int)
DbEnv.txnStat(int)
public static final int DB_SYSTEM_MEM
public static final int DB_THREAD
public static final int DB_TIME_NOTGRANTED
public static final int DB_TRUNCATE
public static final int DB_TXN_NOSYNC
public static final int DB_TXN_NOT_DURABLE
public static final int DB_TXN_NOWAIT
public static final int DB_TXN_SYNC
public static final int DB_TXN_WRITE_NOSYNC
public static final int DB_UPGRADE
public static final int DB_USE_ENVIRON
public static final int DB_USE_ENVIRON_ROOT
public static final int DB_VERB_CHKPOINT
public static final int DB_VERB_DEADLOCK
public static final int DB_VERB_RECOVERY
public static final int DB_VERB_REPLICATION
public static final int DB_VERB_WAITSFOR
public static final int DB_VERIFY
public static final int DB_VERSION_MAJOR
public static final int DB_VERSION_MINOR
public static final int DB_VERSION_PATCH
public static final int DB_WRITECURSOR
public static final int DB_XA_CREATE
public static final int DB_XIDDATASIZE
public static final int DB_YIELDCPU
Constructor Detail |
---|
protected Db(long cPtr, boolean cMemoryOwn)
protected Db()
public Db(DbEnv dbenv, int flags) throws DbException
Db.close
, Db.remove
or
Db.rename
methods will free
that memory.
dbenv
- If no dbenv value is specified,
the database is standalone; that is, it is not part of any
Berkeley DB environment. If a dbenv value is specified, the database is created within the specified Berkeley DB environment. The database access methods automatically make calls to the other subsystems in Berkeley DB based on the enclosing environment. For example, if the environment has been configured to use locking, the access methods will automatically acquire the correct locks when reading and writing pages of the database.
flags
- must be set to 0 or by bitwise
inclusively OR 'ing together one or more of the
following values:
Db.DB_XA_CREATE
Instead of creating a standalone database, create a database intended to be accessed via applications running under a X/Open conformant Transaction Manager. The database will be opened in the environment specified by the OPENINFO parameter of the GROUPS section of the ubbconfig file. See the XA Resource Manager chapter in the Reference Guide for more information.
DbException
- Signals that an exception of some sort
has occurred.Method Detail |
---|
protected void delete()
protected static long getCPtr(Db obj)
public void close(int flags) throws DbException
The Db
handle should not be closed
while any other handle that refers to it is not yet closed;
for example, database handles must not be closed while cursor
handles into the database remain open, or transactions that
include operations on the database have not yet been committed
or aborted. Specifically, this includes Dbc
and DbTxn
handles.
Because key/data pairs are cached in memory, failing to sync
the file with the Db.close or Db.sync
method may result in inconsistent or lost
information.
When called on a database that is the primary database for a secondary index, the primary database should be closed only after all secondary indices which reference it have been closed.
When multiple threads are using the Db
concurrently, only a single thread may call the Db.close
method.
The Db
handle may not be accessed
again after Db.close is called, regardless of its return.
flags
- must be set to 0 or by
bitwise inclusively OR 'ing together one or more of
the following values:
Db.DB_NOSYNC
Do not flush cached information to disk. The
flag is a dangerous option. It should be set only if the
application is doing logging (with transactions) so that
the database is recoverable after a system or
application crash, or if the database is always
generated from scratch after any system or application
crash. Db.DB_NOSYNC
It is important to understand that flushing cached information to disk only minimizes the window of opportunity for corrupted data. Although unlikely, it is possible for database corruption to happen if a system or application crash occurs while writing data to the database. To ensure that database corruption never occurs, applications must either: use transactions and logging with automatic recovery; use logging and application-specific recovery; or edit a copy of the database, and once all applications using the database have successfully called Db.close, atomically replace the original database with the updated copy.
java.lang.IllegalArgumentException
- The Db.close method will
fail and throw a IllegalArgumentException exception if an
invalid flag value or parameter was specified.
DbException
public DbEnv get_env() throws DbException
getDbEnv()
DbException
public DbEnv getDbEnv() throws DbException
The Db.getDbEnv 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 isEncrypted() throws DbException
Db.isEncrypted
method returns false if the underlying database files are
encrypted and true if they are not.
The Db.isEncrypted
method may not be called before the Db.open
method has been called.
Db.isEncrypted
method returns false if the underlying
database files are encrypted and true if they are not.
DbException
- Signals that an exception of some sort
has occurred.public void open(DbTxn txnid, java.lang.String file, java.lang.String database, int type, int flags, int mode) throws DbException, java.io.FileNotFoundException, DbDeadlockException, DbLockNotGrantedException
The currently supported Berkeley DB file formats (or access methods ) are Btree, Hash, Queue, and Recno. The Btree format is a representation of a sorted, balanced tree structure. The Hash format is an extensible, dynamic hashing scheme. The Queue format supports fast access to fixed-length records accessed sequentially or by logical record number. The Recno format supports fixed- or variable-length records, accessed sequentially or by logical record number, and optionally backed by a flat text file.
Storage and retrieval for the Berkeley DB access methods are
based on key/data pairs; see Dbt
for more information.
Calling Db.open is a relatively expensive operation, and maintaining a set of open databases will normally be preferable to repeatedly opening and closing the database for each new query.
If the database was opened within a database environment, the environment variable DB_HOME may be used as the path of the database environment home.
Db.open 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.
If the file and dbenv parameters to Db.open are null, the environment variable TMPDIR may be used as a directory in which to create temporary backing files
database
- optional, and allows
applications to have multiple databases in a single file.
Although no database parameter needs to be
specified, it is an error to attempt to open a second
database in a file that was not initially created
using a database name. Further, the database
parameter is not supported by the Queue format. Finally,
when opening multiple databases in the same physical file,
it is important to consider locking and memory cache
issues; see
Opening multiple databases in a single file for more
information. In-memory databases never intended to be preserved on disk may be created by setting both the file and database parameters to null. Note that in-memory databases can only ever be shared by sharing the single database handle that created them, in circumstances where doing so is safe.
file
- used as the name of an
underlying file that will be used to back the database.
In-memory databases never intended to be preserved on disk may be created by setting both the file and database parameters to null. Note that in-memory databases can only ever be shared by sharing the single database handle that created them, in circumstances where doing so is safe.
flags
- must be set to 0 or by
bitwise inclusively OR 'ing together one or more of
the following values:
Db.DB_AUTO_COMMIT
Enclose the Db.open call within a transaction. If the call succeeds, the open operation will be recoverable. If the call fails, no database will have been created.
Db.DB_CREATE
Create the database. If the database does not already
exist and the Db.DB_CREATE
flag is not
specified, the Db.open will fail.
Db.DB_DIRTY_READ
Support dirty reads; that is, read operations on the
database may request the return of modified but not yet
committed data. This flag must be specified on all
Db
handles used to perform
dirty reads or database updates, otherwise requests for
dirty reads may not be honored and the read may block.
Db.DB_EXCL
Return an error if the database already exists. The
Db.DB_EXCL
flag is only meaningful when
specified with the Db.DB_CREATE
flag.
Db.DB_NOMMAP
Do not map this database into process memory (see the
DbEnv.setMemoryPoolMapSize
method for further
information).
Db.DB_RDONLY
Open the database for reading only. Any attempt to modify items in the database will fail, regardless of the actual permissions of any underlying files.
Db.DB_THREAD
Cause the Db
handle returned
by Db.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
flag was specified.Db.DB_THREAD
Db.DB_TRUNCATE
Physically truncate the underlying file, discarding all previous databases it might have held. Underlying filesystem primitives are used to implement this flag. For this reason, it is applicable only to the file and cannot be used to discard databases within a file.
The Db.DB_TRUNCATE
flag cannot be lock or
transaction-protected, and it is an error to specify it
in a locking or transaction-protected environment.
mode
- On UNIX systems or in
IEEE/ANSI Std 1003.1 (POSIX) environments, all files
created by the database open 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, the database open
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.txnid
- If the operation is to be
transaction-protected, (other than by specifying the
Db.DB_AUTO_COMMIT flag), the txnid parameter is a
transaction handle returned from DbEnv.txnBegin
;
otherwise, null. Note that transactionally protected
operations on a Db
handle
requires the Db
handle itself
be transactionally protected during its open.type
- must be set to one of
Db.DB_BTREE, Db.DB_HASH, Db.DB_QUEUE, Db.DB_RECNO, or
Db.DB_UNKNOWN. If type is Db.DB_UNKNOWN, the
database must already exist and Db.open will automatically
determine its type. The Db.getDbType
method may be
used to determine the underlying type of databases opened
using Db.DB_UNKNOWN.
DbException
- The Db.open 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 Db.open 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 Db.open method will fail and throw a DbLockNotGrantedException
exception.
FileNotFoundException
- If the file or directory
does not exist, the Db.open method will fail and throw a
FileNotFoundException exception.
java.lang.IllegalArgumentException
- The Db.open method will
fail and throw a IllegalArgumentException exception if an
unknown database type, page size, hash function, pad byte,
byte order, or a flag value or parameter that is
incompatible with the specified database was specified;
the Db.DB_THREAD
flag was specified and fast mutexes are not available for
this architecture; the Db.DB_THREAD
flag was
specified to Db.open, but was not specified to the DbEnv.open
call for the
environment in which the Db
handle was created; a backing flat text file was specified
with either the Db.DB_THREAD
flag or the provided database environment
supports transaction processing; or if an invalid flag
value or parameter was specified.public int pget(DbTxn txnid, Dbt key, Dbt pkey, Dbt data, int flags) throws DbException
get(DbTxn,Dbt,Dbt,Dbt,int)
DbException
public void remove(java.lang.String file, java.lang.String database, int flags) throws DbException, 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 Db.remove method may not be called after calling the
Db.open
method on any Db
handle. If the Db.open
method has already been
called on a Db
handle, close the
existing handle and create a new one before calling Db.remove.
The Db
handle may not be accessed
again after Db.remove is called, regardless of its return.
If the database was opened within a database environment, the environment variable DB_HOME may be used as the path of the database environment home.
Db.remove 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
- currently unused, and must
be set to 0.
DbException
- The Db.remove method may
fail and throw DbException
, encapsulating one of the following non-zero
errors:
java.lang.IllegalArgumentException
- The Db.remove method will
fail and throw a IllegalArgumentException exception if
Db.remove called after Db.open
was called; or if an invalid flag value or
parameter was specified.
FileNotFoundException
- If the file or directory
does not exist, the Db.remove method will fail and throw a
FileNotFoundException exception.public void rename(java.lang.String file, java.lang.String database, java.lang.String newname, int flags) throws DbException, 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 Db.rename 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 Db.rename method may not be called after calling the
Db.open
method on any Db
handle. If the Db.open
method has already been
called on a Db
handle, close the
existing handle and create a new one before calling Db.rename.
The Db
handle may not be accessed
again after Db.rename is called, regardless of its return.
If the database was opened within a database environment, the environment variable DB_HOME may be used as the path of the database environment home.
Db.rename 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
- currently unused, and must
be set to 0.newname
- the new name of the database
or file.
DbException
- The Db.rename method may
fail and throw DbException
, encapsulating one of the following non-zero
errors:
java.lang.IllegalArgumentException
- The Db.rename method will
fail and throw a IllegalArgumentException exception if
Db.rename called after Db.open
was called; or if an invalid flag value or
parameter was specified.
FileNotFoundException
- If the file or directory
does not exist, the Db.rename method will fail and throw a
FileNotFoundException exception.public void verify(java.lang.String file, java.lang.String database, java.io.OutputStream outfile, int flags) throws DbException, java.io.FileNotFoundException
The Db.verify method does not perform any locking, even in Berkeley DB environments that are configured with a locking subsystem. As such, it should only be used on files that are not being modified by another thread of control.
The Db.verify method may not be called after the Db.open
method is called.
The Db
handle may not be accessed
again after Db.verify is called, regardless of its return.
If the database was opened within a database environment, the environment variable DB_HOME may be used as the path of the database environment home.
Db.verify 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 in file
on which the database checks for btree and duplicate sort
order and for hashing are to be performed. See the
Db.DB_ORDERCHKONLY flag for more information. The database parameter must be set to null except when the Db.DB_ORDERCHKONLY flag is set.
file
- the physical file in which
the databases to be verified are found.flags
- must be set to 0 or the
following value:
Db.DB_SALVAGE
Write the key/data pairs from all databases in the file to the file stream named in the outfile parameter. The output format is the same as that specified for the db_dump utility, and can be used as input for the db_load utility.
Because the key/data pairs are output in page order as opposed to the sort order used by db_dump , using Db.verify to dump key/data pairs normally produces less than optimal loads for Btree databases.
Db.DB_AGGRESSIVE
Output all the key/data pairs in the file that
can be found. By default, Db.verify does not assume
corruption. For example, if a key/data pair on a page is
marked as deleted, it is not then written to the output
file. When Db.DB_AGGRESSIVE
is specified,
corruption is assumed, and any key/data pair that can be
found is written. In this case, key/data pairs that are
corrupted or have been deleted may appear in the output
(even if the file being salvaged is in no way corrupt),
and the output will almost certainly require editing
before being loaded into a database.
Db.DB_PRINTABLE
When using the Db.DB_SALVAGE
flag, if
characters in either the key or data items are printing
characters (as defined by isprint (3)), use
printing characters to represent them. This flag permits
users to use standard text editors and tools to modify
the contents of databases or selectively remove data
from salvager output.
Note: different systems may have different notions about what characters are considered printing characters , and databases dumped in this manner may be less portable to external systems.
Db.DB_NOORDERCHK
Skip the database checks for btree and duplicate sort order and for hashing.
The Db.verify method normally verifies that btree keys
and duplicate items are correctly sorted, and hash keys
are correctly hashed. If the file being verified
contains multiple databases using differing sorting or
hashing algorithms, some of them must necessarily fail
database verification because only one sort order or
hash function can be specified before Db.verify is
called. To verify files with multiple databases having
differing sorting orders or hashing functions, first
perform verification of the file as a whole by using the
Db.DB_NOORDERCHK
flag, and then
individually verify the sort order and hashing function
for each database in the file using the Db.DB_ORDERCHKONLY
flag.
Db.DB_ORDERCHKONLY
Perform the database checks for btree and duplicate sort
order and for hashing, skipped by Db.DB_NOORDERCHK
.
When this flag is specified, a database parameter
should also be specified, indicating the database in the
physical file which is to be checked. This flag is only
safe to use on databases that have already successfully
been verified using Db.verify with the Db.DB_NOORDERCHK
flag set.
outfile
- an optional file stream to
which the databases' key/data pairs are written.
FileNotFoundException
- If the file or directory
does not exist, the Db.verify method will fail and throw a
FileNotFoundException exception.
java.lang.IllegalArgumentException
- The Db.verify method will
fail and throw a IllegalArgumentException exception if
Db.verify was called after Db.open
; or if an invalid flag value or parameter was
specified.
DbException
public void set_cachesize(int gbytes, int bytes, int ncache) throws DbException
setCacheSize(long,int)
DbException
public void set_errcall(DbErrcall db_errcall_fcn)
setErrorHandler(DbErrorHandler)
public void setErrorHandler(DbErrorHandler db_errcall_fcn) throws DbException
The DbEnv.setErrorHandler
and Db.setOnError methods are used to
enhance the mechanism for reporting error messages to the
application. The DbEnv.setErrorHandler
and Db.setOnError 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.
For Db
handles opened inside of
Berkeley DB environments, calling the Db.setOnError method
affects the entire environment and is equivalent to calling
the DbEnv.setErrorHandler
method.
The Db.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 java.lang.String get_errpfx()
getErrorPrefix()
public java.lang.String getErrorPrefix()
The Db.getErrorPrefix method may be called at any time during the life of the application.
public void set_errpfx(java.lang.String errpfx)
setErrorPrefix(String)
public void setErrorPrefix(java.lang.String errpfx)
For Db
handles opened inside of
Berkeley DB environments, calling the Db.setErrorPrefix method
affects the entire environment and is equivalent to calling
the DbEnv.setErrorPrefix
method.
The Db.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_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.
For Db
handles opened inside of
Berkeley DB environments, calling the Db.setErrorStream method
affects the entire environment and is equivalent to calling
the DbEnv.setErrorStream
method.
stream
- the application-specified output stream to be
used for additional error information.public void set_feedback(DbFeedback feedback) throws DbException
setFeedbackHandler(DbFeedbackHandler)
DbException
public void setPanicHandler(DbPanicHandler db_panic_fcn) throws DbException
DbRunRecoveryException
. It is often easier to simply exit the
application when such errors occur rather than gracefully
return up the stack. The Db.setPanic method specifies a
function to be called when DbRunRecoveryException
is about to be thrown from a Berkeley
DB method.
For Db
handles opened inside of
Berkeley DB environments, calling the Db.setPanic method
affects the entire environment and is equivalent to calling
the DbEnv.setPanicHandler
method.
The Db.setPanic method may be called at any time during the life of the application.
db_panic_fcn
- the application-specified function called
in the case of a database environment panic. The function
takes two arguments: The dbenv parameter is the enclosing database environment handle.
The e parameter is the DbException that would have been thrown to the calling method.
DbException
- Signals that an exception of some sort
has occurred.public void associate(DbTxn txnid, Db secondary, DbSecondaryKeyCreate callback, int flags) throws DbException
DbException
public Dbc cursor(DbTxn txnid, int flags) throws DbException
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 cursor may return
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_WRITECURSOR
Specify that the cursor will be used to update the
database. The underlying database environment must have
been opened using the
flag. Db.DB_INIT_CDB
txnid
- If the operation is to be
transaction-protected, the txnid parameter is a
transaction handle returned from DbEnv.txnBegin
;
otherwise, null. To transaction-protect cursor operations,
cursors must be opened and closed within the context of a
transaction, and the txnid parameter specifies the
transaction context in which the cursor may be used.
DbException
- The Db.cursor method may
fail and throw DbException
, encapsulating one of the following non-zero
errors:
java.lang.IllegalArgumentException
- The Db.cursor method will
fail and throw a IllegalArgumentException exception if an
invalid flag value or parameter was specified.public int del(DbTxn txnid, Dbt key, int flags) throws DbException
delete(DbTxn,Dbt,int)
DbException
public int delete(DbTxn txnid, Dbt key, int flags) throws DbException
When called on a database that has been made into a secondary
index using the Db.associate
method, the Db.delete method deletes the
key/data pair from the primary database and all secondary
indices.
key
- The key Dbt
operated on.flags
- must be set to 0 or the
following value:
Db.DB_AUTO_COMMIT
Enclose the Db.delete 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, (other than by specifying the
Db.DB_AUTO_COMMIT flag), the txnid parameter is a
transaction handle returned from DbEnv.txnBegin
;
otherwise, null.
DB_NOTFOUND
The Db.delete method will return
Db.DB_NOTFOUND
if the specified key is
not in the database.
DB_KEYEMPTY
The Db.delete method will return
Db.DB_KEYEMPTY
if the database is a
Queue or Recno database and the specified key exists,
but was never explicitly created by the application or
was later deleted.
DbException
- The Db.delete method may
fail and throw DbException
, encapsulating one of the following non-zero
errors: An attempt was made to modify a read-only
database.
DbDeadlockException
- If a transactional database
environment operation was selected to resolve a deadlock,
the Db.delete 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 Db.delete method will fail and throw a DbLockNotGrantedException
exception.
java.lang.IllegalArgumentException
- The Db.delete method will
fail and throw a IllegalArgumentException exception if an
invalid flag value or parameter was specified.public void err(int error, java.lang.String message)
DbEnv.err
, DbEnv.errx
, 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)
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.
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 int get(DbTxn txnid, Dbt key, Dbt data, int flags) throws DbException
In the presence of duplicate key values, Db.get will return
the first data item for the designated key. Duplicates are
sorted by insert order, except where this order has been
overridden by cursor operations. Retrieval of duplicates
requires the use of cursor operations. See Dbc.get
for details.
When called on a database that has been made into a secondary
index using the Db.associate
method, the Db.get method returns the key from
the secondary index and the data item from the primary
database. In addition, the second method signature returns the
key from the primary database. In databases that are not
secondary indices, the second method signature will always
fail.
data
- The data Dbt
operated on.flags
- must be set to 0 or one of
the following values:
Db.DB_CONSUME
Return the record number and data from the available
record closest to the head of the queue, and delete the
record. The cursor will be positioned on the deleted
record. The record number will be returned in key
, as described in Dbt
. The
data will be returned in the data parameter. A
record is available if it is not deleted and is not
currently locked. The underlying database must be of
type Queue for Db.DB_CONSUME
to be
specified.
Db.DB_CONSUME_WAIT
The Db.DB_CONSUME_WAIT
flag is the same as
the Db.DB_CONSUME
flag, except that if the
Queue database is empty, the thread of control will wait
until there is data in the queue before returning. The
underlying database must be of type Queue for Db.DB_CONSUME_WAIT
to be specified.
If lock or transaction timeouts have been specified, the
Db.get method with the Db.DB_CONSUME_WAIT
flag may return
Db.DB_LOCK_NOTGRANTED
. This failure,
by itself, does not require the enclosing transaction be
aborted.
Db.DB_GET_BOTH
Retrieve the key/data pair only if both the key and data match the arguments.
When used with the second method signature version of
this method on a secondary index handle, return the
secondary key/primary key/data tuple only if both the
primary and secondary keys match the arguments. It is an
error to use the Db.DB_GET_BOTH
flag with
the first method signature version of this method and a
secondary index handle.
Db.DB_SET_RECNO
Retrieve the specified numbered key/data pair from a database. Upon return, both the key and data items will have been filled in.
The data field of the specified key must be a byte array large enough to hold a logical record number (that is, an int). This record number determines the record to be retrieved.
For Db.DB_SET_RECNO
to be specified, the
underlying database must be of type Btree, and it must
have been created with the DB_RECNUM flag.
Db.DB_AUTO_COMMIT
Enclose the Db.get 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. This flag may only be specified with
the Db.DB_CONSUME
and Db.DB_CONSUME_WAIT
flags.
Db.DB_DIRTY_READ
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_MULTIPLE
Return multiple data items in the buffer to which the data parameter refers.
In the case of Btree or Hash databases, all of the data items associated with the specified key are entered into the buffer. In the case of Queue or Recno databases, all of the data items in the database, starting at, and subsequent to, the specified key, are entered into the buffer.
The buffer to which the data parameter refers
must be provided from user memory (see
). The buffer must be at least as large as the page
size of the underlying database, aligned for unsigned
integer access, and be a multiple of 1024 bytes in size.
If the buffer size is insufficient, then upon return
from the call the size field of the data
parameter will have been set to an estimated buffer
size, and a Db.DB_DBT_USERMEM
DbMemoryException
is thrown. (The size is an estimate
as the exact size needed may not be known until all
entries are read. It is best to initially provide a
relatively large buffer, but applications should be
prepared to resize the buffer as necessary and
repeatedly call the method.)
The Db.DB_MULTIPLE
flag may only be used
alone, or with the Db.DB_GET_BOTH
and
Db.DB_SET_RECNO
options. The Db.DB_MULTIPLE
flag may not be used when accessing databases made into
secondary indices using the Db.associate
method.
See DbMultipleDataIterator
for more information.
Db.DB_RMW
Acquire write locks instead of read locks when doing the retrieval. Setting this flag can eliminate deadlock during a read-modify-write cycle by acquiring the write lock during the read part of the cycle so that another thread of control acquiring a read lock for the same item, in its own read-modify-write cycle, will not result in deadlock.
Because the Db.get method will not hold locks across
Berkeley DB calls in non-transactional operations, the
flag to the Db.get call is meaningful only in the
presence of transactions.Db.DB_RMW
key
- The key Dbt
operated on.pkey
- the return key from the
primary database.txnid
- If the operation is to be
transaction-protected, the txnid parameter is a
transaction handle returned from DbEnv.txnBegin
;
otherwise, null.
DB_NOTFOUND
The Db.get method will return
Db.DB_NOTFOUND
if the specified key is
not in the database.
DB_KEYEMPTY
The Db.get method will return
Db.DB_KEYEMPTY
if the database is a
Queue or Recno database and the specified key exists,
but was never explicitly created by the application or
was later deleted.
DbException
- The Db.get 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 Db.get 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 Db.get method will fail and throw a DbLockNotGrantedException
exception.
DbLockNotGrantedException
- If the Db.DB_CONSUME_WAIT
flag was specified, lock or transaction timers were
configured and the lock could not be granted before the
wait-time expired, the Db.get method will fail and throw a
DbLockNotGrantedException
exception.
java.lang.IllegalArgumentException
- The Db.get method will fail
and throw a IllegalArgumentException exception if a record
number of 0 was specified; the Db.DB_THREAD
flag was
specified to the Db.open
method and none of the Db.DB_DBT_MALLOC
,
Db.DB_DBT_REALLOC
or Db.DB_DBT_USERMEM
flags were set in the Dbt
;
the second method signature was called with a Db
handle that does not refer to a
secondary index; or if an invalid flag value or parameter
was specified.
DbMemoryException
- If the requested item could
not be returned due to insufficient memory, the Db.get
method will fail and throw a DbMemoryException
exception.public boolean get_byteswapped() throws DbException
isByteSwapped()
DbException
public boolean isByteSwapped() throws DbException
The Db.isByteSwapped method may not be called before the
Db.open
method has been
called.
java.lang.IllegalArgumentException
- The Db.isByteSwapped method
will fail and throw a IllegalArgumentException exception
if the method was called before Db.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 Db.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 java.lang.String get_filename() throws DbException
getFileName()
DbException
public java.lang.String getFileName() throws DbException
The Db.getFileName 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_dbname() throws DbException
getDatabaseName()
DbException
public java.lang.String getDatabaseName() throws DbException
The Db.getDatabaseName 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 Db.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 Db.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 int get_lorder() throws DbException
getByteOrder()
DbException
public int getByteOrder() throws DbException
The Db.getByteOrder method may be called at any time during the life of the application.
DbException
- Signals that an exception of some sort
has occurred.public DbMpoolFile get_mpf() throws DbException
The Db.get_mpf 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 Db.getOpenFlags method may not be called before the Db.open method has been called.
DbException
- Signals that an exception of some sort
has occurred.public int get_pagesize() throws DbException
getPageSize()
DbException
public int getPageSize() throws DbException
The Db.getPageSize 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_bt_minkey() throws DbException
getBtreeMinKey()
DbException
public int getBtreeMinKey() throws DbException
The Db.getBtreeMinKey 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_h_ffactor() throws DbException
getHashFillFactor()
DbException
public int getHashFillFactor() throws DbException
The Db.getHashFillFactor 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_h_nelem() throws DbException
getHashNumElements()
DbException
public int getHashNumElements() throws DbException
The Db.getHashNumElements 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_re_delim() throws DbException
getRecordDelimiter()
DbException
public int getRecordDelimiter() throws DbException
The Db.getRecordDelimiter 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_re_len() throws DbException
getRecordLength()
DbException
public int getRecordLength() throws DbException
The Db.getRecordLength 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_re_pad() throws DbException
getRecordPad()
DbException
public int getRecordPad() throws DbException
The Db.getRecordPad 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_re_source() throws DbException
getRecordSource()
DbException
public java.lang.String getRecordSource() throws DbException
The Db.getRecordSource 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_q_extentsize() throws DbException
getQueueExtentSize()
DbException
public int getQueueExtentSize() throws DbException
The Db.getQueueExtentSize 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_raw() throws DbException
DbException
public boolean get_transactional() throws DbException
isTransactional()
DbException
public boolean isTransactional() throws DbException
Db
handle has been opened in a
transactional mode. The Db.isTransactional method may be called at any time during the life of the application.
Db
handle has been
opened in a transactional mode.
DbException
- Signals that an exception of some sort
has occurred.public int get_type() throws DbException
getDbType()
DbException
public int getDbType() throws DbException
Db.open
with
the type parameter set to Db.DB_UNKNOWN.
The Db.getDbType method may not be called before the Db.open
method has been called.
java.lang.IllegalArgumentException
- The Db.getDbType method will
fail and throw a IllegalArgumentException exception if the
method was called before Db.open
was called; or if an invalid flag value or
parameter was specified.
DbException
public Dbc join(Dbc[] curslist, int flags) throws DbException
The Db.join method method is called using the Db
handle of the primary database.
The join cursor supports only the Dbc.get
and dbc_close cursor
functions:
Iterates over the values associated with the keys to which each item in curslist was initialized. Any data value that appears in all items specified by the curslist parameter is then used as a key into the primary , and the key/data pair found in the primary is returned. The flags parameter must be set to 0 or the following value: In addition, the following flag may be set by bitwise inclusively OR 'ing it into the flags parameter: Close the returned cursor and release all resources. (Closing the cursors in curslist is the responsibility of the caller.)
curslist
- The curslist
parameter contains a null terminated array of cursors.
Each cursor must have been initialized to refer to the key
on which the underlying database should be joined.
Typically, this initialization is done by a Dbc.get
call with the Db.DB_SET
flag specified. Once
the cursors have been passed as part of a curslist
, they should not be accessed or modified until the newly
created join cursor has been closed, or else inconsistent
results may be returned. Joined values are retrieved by doing a sequential iteration over the first cursor in the curslist parameter, and a nested iteration over each secondary cursor in the order they are specified in the curslist parameter. This requires database traversals to search for the current datum in all the cursors after the first. For this reason, the best join performance normally results from sorting the cursors from the one that refers to the least number of data items to the one that refers to the most. By default, Db.join does this sort on behalf of its caller.
For the returned join cursor to be used in a transaction-protected manner, the cursors listed in curslist must have been created within the context of the same transaction.
flags
- must be set to 0 or the
following value:
Db.DB_JOIN_NOSORT
Do not sort the cursors based on the number of data
items to which they refer. If the data are structured so
that cursors with many data items also share many common
elements, higher performance will result from listing
those cursors before cursors with fewer data items; that
is, a sort order other than the default. The Db.DB_JOIN_NOSORT
flag permits applications to perform join optimization
prior to calling Db.join.
DbException
- The Db.join method may fail
and throw DbException
, encapsulating one of the following non-zero
errors:
java.lang.IllegalArgumentException
- The Db.join method will fail
and throw a IllegalArgumentException exception if cursor
methods other than Dbc.get
or Dbc.close
were called; or if an invalid flag value or parameter was
specified.public void key_range(DbTxn txnid, Dbt key, DbKeyRange key_range, int flags) throws DbException
keyRange(DbTxn,Dbt,DbKeyRange,int)
DbException
public void keyRange(DbTxn txnid, Dbt key, DbKeyRange key_range, int flags) throws DbException
The Db.keyRange method fills in a DbKeyRange object. The following data fields are available from the DbKeyRange object:
Values are in the range of 0 to 1; for example, if the field less is 0.05, 5% of the keys in the database are less than the key parameter. The value for equal will be zero if there is no matching key, and will be non-zero otherwise.
key
- The key Dbt
operated on.key_range
- The estimates are returned
in the key_range parameter, which contains three
elements of type double: less , equal , and
greater . Values are in the range of 0 to 1; for
example, if the field less is 0.05, 5% of the keys
in the database are less than the key parameter.
The value for equal will be zero if there is no
matching key, and will be non-zero otherwise.txnid
- If the operation is to be
transaction-protected, the txnid parameter is a
transaction handle returned from DbEnv.txnBegin
;
otherwise, null. The Db.keyRange method does not retain
the locks it acquires for the life of the transaction, so
estimates may not be repeatable.flags
- currently unused, and must
be set to 0.
DbException
- The Db.keyRange 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 Db.keyRange 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 Db.keyRange method will fail and throw a DbLockNotGrantedException
exception.
java.lang.IllegalArgumentException
- The Db.keyRange method will
fail and throw a IllegalArgumentException exception if the
underlying database was not of type Btree; or if an
invalid flag value or parameter was specified.public int get(DbTxn txnid, Dbt key, Dbt pkey, Dbt data, int flags) throws DbException
In the presence of duplicate key values, Db.get will return
the first data item for the designated key. Duplicates are
sorted by insert order, except where this order has been
overridden by cursor operations. Retrieval of duplicates
requires the use of cursor operations. See Dbc.get
for details.
When called on a database that has been made into a secondary
index using the Db.associate
method, the Db.get method returns the key from
the secondary index and the data item from the primary
database. In addition, the second method signature returns the
key from the primary database. In databases that are not
secondary indices, the second method signature will always
fail.
data
- The data Dbt
operated on.flags
- must be set to 0 or one of
the following values:
Db.DB_CONSUME
Return the record number and data from the available
record closest to the head of the queue, and delete the
record. The cursor will be positioned on the deleted
record. The record number will be returned in key
, as described in Dbt
. The
data will be returned in the data parameter. A
record is available if it is not deleted and is not
currently locked. The underlying database must be of
type Queue for Db.DB_CONSUME
to be
specified.
Db.DB_CONSUME_WAIT
The Db.DB_CONSUME_WAIT
flag is the same as
the Db.DB_CONSUME
flag, except that if the
Queue database is empty, the thread of control will wait
until there is data in the queue before returning. The
underlying database must be of type Queue for Db.DB_CONSUME_WAIT
to be specified.
If lock or transaction timeouts have been specified, the
Db.get method with the Db.DB_CONSUME_WAIT
flag may return
Db.DB_LOCK_NOTGRANTED
. This failure,
by itself, does not require the enclosing transaction be
aborted.
Db.DB_GET_BOTH
Retrieve the key/data pair only if both the key and data match the arguments.
When used with the second method signature version of
this method on a secondary index handle, return the
secondary key/primary key/data tuple only if both the
primary and secondary keys match the arguments. It is an
error to use the Db.DB_GET_BOTH
flag with
the first method signature version of this method and a
secondary index handle.
Db.DB_SET_RECNO
Retrieve the specified numbered key/data pair from a database. Upon return, both the key and data items will have been filled in.
The data field of the specified key must be a byte array large enough to hold a logical record number (that is, an int). This record number determines the record to be retrieved.
For Db.DB_SET_RECNO
to be specified, the
underlying database must be of type Btree, and it must
have been created with the DB_RECNUM flag.
Db.DB_AUTO_COMMIT
Enclose the Db.get 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. This flag may only be specified with
the Db.DB_CONSUME
and Db.DB_CONSUME_WAIT
flags.
Db.DB_DIRTY_READ
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_MULTIPLE
Return multiple data items in the buffer to which the data parameter refers.
In the case of Btree or Hash databases, all of the data items associated with the specified key are entered into the buffer. In the case of Queue or Recno databases, all of the data items in the database, starting at, and subsequent to, the specified key, are entered into the buffer.
The buffer to which the data parameter refers
must be provided from user memory (see
). The buffer must be at least as large as the page
size of the underlying database, aligned for unsigned
integer access, and be a multiple of 1024 bytes in size.
If the buffer size is insufficient, then upon return
from the call the size field of the data
parameter will have been set to an estimated buffer
size, and a Db.DB_DBT_USERMEM
DbMemoryException
is thrown. (The size is an estimate
as the exact size needed may not be known until all
entries are read. It is best to initially provide a
relatively large buffer, but applications should be
prepared to resize the buffer as necessary and
repeatedly call the method.)
The Db.DB_MULTIPLE
flag may only be used
alone, or with the Db.DB_GET_BOTH
and
Db.DB_SET_RECNO
options. The Db.DB_MULTIPLE
flag may not be used when accessing databases made into
secondary indices using the Db.associate
method.
See DbMultipleDataIterator
for more information.
Db.DB_RMW
Acquire write locks instead of read locks when doing the retrieval. Setting this flag can eliminate deadlock during a read-modify-write cycle by acquiring the write lock during the read part of the cycle so that another thread of control acquiring a read lock for the same item, in its own read-modify-write cycle, will not result in deadlock.
Because the Db.get method will not hold locks across
Berkeley DB calls in non-transactional operations, the
flag to the Db.get call is meaningful only in the
presence of transactions.Db.DB_RMW
key
- The key Dbt
operated on.pkey
- the return key from the
primary database.txnid
- If the operation is to be
transaction-protected, the txnid parameter is a
transaction handle returned from DbEnv.txnBegin
;
otherwise, null.
DB_NOTFOUND
The Db.get method will return
Db.DB_NOTFOUND
if the specified key is
not in the database.
DB_KEYEMPTY
The Db.get method will return
Db.DB_KEYEMPTY
if the database is a
Queue or Recno database and the specified key exists,
but was never explicitly created by the application or
was later deleted.
DbException
- The Db.get 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 Db.get 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 Db.get method will fail and throw a DbLockNotGrantedException
exception.
DbLockNotGrantedException
- If the Db.DB_CONSUME_WAIT
flag was specified, lock or transaction timers were
configured and the lock could not be granted before the
wait-time expired, the Db.get method will fail and throw a
DbLockNotGrantedException
exception.
java.lang.IllegalArgumentException
- The Db.get method will fail
and throw a IllegalArgumentException exception if a record
number of 0 was specified; the Db.DB_THREAD
flag was
specified to the Db.open
method and none of the Db.DB_DBT_MALLOC
,
Db.DB_DBT_REALLOC
or Db.DB_DBT_USERMEM
flags were set in the Dbt
;
the second method signature was called with a Db
handle that does not refer to a
secondary index; or if an invalid flag value or parameter
was specified.
DbMemoryException
- If the requested item could
not be returned due to insufficient memory, the Db.get
method will fail and throw a DbMemoryException
exception.public int put(DbTxn txnid, Dbt key, Dbt data, int flags) throws DbException
flags
- must be set to 0 or one of
the following values:
Db.DB_APPEND
Append the key/data pair to the end of the database. For
the Db.DB_APPEND
flag to be specified, the
underlying database must be a Queue or Recno database.
The record number allocated to the record is returned in
the specified key .
There is a minor behavioral difference between the Recno
and Queue access methods for the Db.DB_APPEND
flag. If a transaction enclosing a Db.put operation with
the Db.DB_APPEND
flag aborts, the record
number may be decremented (and later reallocated by a
subsequent Db.DB_APPEND
operation) by the
Recno access method, but will not be decremented or
reallocated by the Queue access method.
Db.DB_NODUPDATA
In the case of the Btree and Hash access methods, enter the new key/data pair only if it does not already appear in the database.
The Db.DB_NODUPDATA
flag may only be
specified if the underlying database has been configured
to support sorted duplicates. The Db.DB_NODUPDATA
flag may not be specified to the Queue or Recno access
methods.
Db.DB_NOOVERWRITE
Enter the new key/data pair only if the key does not
already appear in the database. The Db.put method call
with the Db.DB_NOOVERWRITE
flag set will
fail if the key already exists in the database, even if
the database supports duplicates.
Db.DB_AUTO_COMMIT
Enclose the Db.put 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.
data
- The data Dbt
operated on.key
- The key Dbt
operated on.txnid
- If the operation is to be
transaction-protected, (other than by specifying the
Db.DB_AUTO_COMMIT flag), the txnid parameter is a
transaction handle returned from DbEnv.txnBegin
;
otherwise, null.
DB_KEYEXIST
The Db.put method will return
if Db.DB_KEYEXIST
Db.DB_NODUPDATA
is set and the
key/data pair already appears in the database.
DB_KEYEXIST
The Db.put method will return
if Db.DB_KEYEXIST
Db.DB_NOOVERWRITE
is set and the key
already appears in the database.
DbException
- The Db.put 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 Db.put 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 Db.put method will fail and throw a DbLockNotGrantedException
exception.
java.lang.IllegalArgumentException
- The Db.put method will fail
and throw a IllegalArgumentException exception if a record
number of 0 was specified; an attempt was made to add a
record to a fixed-length database that was too large to
fit; an attempt was made to do a partial put; an attempt
was made to add a record to a secondary index; or if an
invalid flag value or parameter was specified.public void set_append_recno(DbAppendRecno db_append_recno_fcn) throws DbException
setAppendRecno(DbAppendRecno)
DbException
public void setAppendRecno(DbAppendRecno db_append_recno_fcn) throws DbException
DbException
public void set_bt_compare(DbBtreeCompare bt_compare_fcn) throws DbException
setBtreeCompare(DbBtreeCompare)
DbException
public void setBtreeCompare(DbBtreeCompare bt_compare_fcn) throws DbException
DbException
public void set_bt_maxkey(int maxkey) throws DbException
DbException
public void set_bt_minkey(int bt_minkey) throws DbException
setBtreeMinKey(int)
DbException
public void setBtreeMinKey(int bt_minkey) throws DbException
This value is used to determine if key or data items will be stored on overflow pages instead of Btree leaf pages. For more information on the specific algorithm used, see Minimum keys per page . The bt_minkey value specified must be at least 2; if bt_minkey is not explicitly set, a value of 2 is used.
The Db.setBtreeMinKey method configures a database, not only
operations performed using the specified Db
handle.
The Db.setBtreeMinKey method may not be called after the
Db.open
method is called. If
the database already exists when Db.open
is called, the information
specified to Db.setBtreeMinKey will be ignored.
bt_minkey
- the minimum number of
key/data pairs intended to be stored on any single Btree
leaf page.
java.lang.IllegalArgumentException
- The Db.setBtreeMinKey method
will fail and throw a IllegalArgumentException exception
if the method was called after Db.open
was called; or if an
invalid flag value or parameter was specified.
DbException
public void set_bt_prefix(DbBtreePrefix bt_prefix_fcn) throws DbException
setBtreePrefix(DbBtreePrefix)
DbException
public void setBtreePrefix(DbBtreePrefix bt_prefix_fcn) throws DbException
DbException
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.
Because databases opened within Berkeley DB environments use the cache specified to the environment, it is an error to attempt to set a cache in a database created within an environment.
The Db.setCacheSize method may not be called after the Db.open
method is called.
bytes
- The size of the cache in
bytes.ncache
- the number of caches to
create.
java.lang.IllegalArgumentException
- The Db.setCacheSize method
will fail and throw a IllegalArgumentException exception
if the specified cache size was impossibly small; called
in a database environment; the method was called after
Db.open
was called; or if
an invalid flag value or parameter was specified.
DbException
public void set_dup_compare(DbDupCompare dup_compare_fcn) throws DbException
setDuplicateCompare(DbDupCompare)
DbException
public void setDuplicateCompare(DbDupCompare dup_compare_fcn) throws DbException
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
Because databases opened within Berkeley DB environments use the password specified to the environment, it is an error to attempt to set a password in a database created within an environment.
The Db.setEncrypted method may not be called after the Db.open
method is called.
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 Db.setEncrypted method
may fail and throw DbException
, encapsulating one of the following non-zero
errors:
java.lang.IllegalArgumentException
- The Db.setEncrypted method
will fail and throw a IllegalArgumentException exception
if the method was called after Db.open
was called; or if an
invalid flag value or parameter was specified.public void setFeedbackHandler(DbFeedbackHandler db_feedback_fcn) throws DbException
DbException
public void set_flags(int flags) throws DbException
setFlags(int)
DbException
public void setFlags(int flags) throws DbException
The Db.setFlags method may not be called after the Db.open
method is called.
flags
- must be set to 0 or by
bitwise inclusively OR 'ing together one or more of
the following values: The following flags may be specified for any Berkeley DB access method:
Db.DB_CHKSUM
Do checksum verification of pages read into the cache from the backing filestore. Berkeley DB uses the SHA1 Secure Hash Algorithm if encryption is configured and a general hash algorithm if it is not.
Calling Db.setFlags with the Db.DB_CHKSUM
flag only affects the specified Db
handle (and any other Berkeley
DB handles opened within the scope of that handle).
If the database already exists when Db.open
is called, the
DB_CHKSUM flag will be ignored.
Db.DB_ENCRYPT
Encrypt the database using the cryptographic password
specified to the DbEnv.setEncrypted
or Db.setEncrypted
methods.
Calling Db.setFlags with the Db.DB_ENCRYPT
flag only affects the specified Db
handle (and any other Berkeley
DB handles opened within the scope of that handle).
If the database already exists when Db.open
is called, the
DB_ENCRYPT flag must be the same as the existing
database or an error will be returned.
Encrypted databases are not portable between machines of different byte orders, that is, encrypted databases created on big-endian machines cannot be read on little-endian machines, and vice versa.
Db.DB_TXN_NOT_DURABLE
If set, Berkeley DB will not write log records for this
database. This means that updates of this database
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. The database
file must be verified and/or restored from backup after
a failure. In order to ensure integrity after
application shut down, the 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. All database handles for a
single physical file must set Db.DB_TXN_NOT_DURABLE
, including database handles for different databases in
a physical file.
Calling Db.setFlags with the Db.DB_TXN_NOT_DURABLE
flag only affects the specified Db
handle (and any other Berkeley
DB handles opened within the scope of that handle).
The following flags may be specified for the Btree access method:
Db.DB_DUP
Permit duplicate data items in the database; that is, insertion when the key of the key/data pair being inserted already exists in the database will be successful. The ordering of duplicates in the database is determined by the order of insertion, unless the ordering is otherwise specified by use of a cursor operation.
The Db.DB_DUPSORT
flag is preferred to
Db.DB_DUP
for performance reasons. The
Db.DB_DUP
flag should only be used by
applications wanting to order duplicate data items
manually.
Calling Db.setFlags with the Db.DB_DUP
flag
affects the database, including all threads of control
accessing the database.
If the database already exists when Db.open
is called, the DB_DUP
flag must be the same as the existing database or an
error will be returned.
It is an error to specify both Db.DB_DUP
and Db.DB_RECNUM
.
Db.DB_DUPSORT
Permit duplicate data items in the database; that is,
insertion when the key of the key/data pair being
inserted already exists in the database will be
successful. The ordering of duplicates in the database
is determined by the duplicate comparison function. A
default lexical comparison will be used. It is an error
to specify both Db.DB_DUPSORT
and Db.DB_RECNUM
.
Calling Db.setFlags with the Db.DB_DUPSORT
flag affects the database, including all threads of
control accessing the database.
If the database already exists when Db.open
is called, the
DB_DUPSORT flag must be the same as the existing
database or an error will be returned.
Db.DB_RECNUM
Support retrieval from the Btree using record numbers.
For more information, see the
flag to the Db.DB_SET_RECNO
Db.get
and
Dbc.get
methods.
Logical record numbers in Btree databases are mutable in
the face of record insertion or deletion. See the Db.DB_RENUMBER
flag in the Recno access method information for further
discussion.
Maintaining record counts within a Btree introduces a
serious point of contention, namely the page locations
where the record counts are stored. In addition, the
entire database must be locked during both insertions
and deletions, effectively single-threading the database
for those operations. Specifying Db.DB_RECNUM
can result in serious performance degradation for some
applications and data sets.
It is an error to specify both Db.DB_DUP
and Db.DB_RECNUM
.
Calling Db.setFlags with the Db.DB_RECNUM
flag affects the database, including all threads of
control accessing the database.
If the database already exists when Db.open
is called, the
DB_RECNUM flag must be the same as the existing database
or an error will be returned.
Db.DB_REVSPLITOFF
Turn off reverse splitting in the Btree. As pages are emptied in a database, the Berkeley DB Btree implementation attempts to coalesce empty pages into higher-level pages in order to keep the database as small as possible and minimize search time. This can hurt performance in applications with cyclical data demands; that is, applications where the database grows and shrinks repeatedly. For example, because Berkeley DB does page-level locking, the maximum level of concurrency in a database of two pages is far smaller than that in a database of 100 pages, so a database that has shrunk to a minimal size can cause severe deadlocking when a new cycle of data insertion begins.
Calling Db.setFlags with the Db.DB_REVSPLITOFF
flag only affects the specified Db
handle (and any other Berkeley
DB handles opened within the scope of that handle).
The following flags may be specified for the Hash access method:
Db.DB_DUP
Permit duplicate data items in the database; that is, insertion when the key of the key/data pair being inserted already exists in the database will be successful. The ordering of duplicates in the database is determined by the order of insertion, unless the ordering is otherwise specified by use of a cursor operation.
The Db.DB_DUPSORT
flag is preferred to
Db.DB_DUP
for performance reasons. The
Db.DB_DUP
flag should only be used by
applications wanting to order duplicate data items
manually.
Calling Db.setFlags with the Db.DB_DUP
flag
affects the database, including all threads of control
accessing the database.
If the database already exists when Db.open
is called, the DB_DUP
flag must be the same as the existing database or an
error will be returned.
Db.DB_DUPSORT
Permit duplicate data items in the database; that is,
insertion when the key of the key/data pair being
inserted already exists in the database will be
successful. The ordering of duplicates in the database
is determined by the duplicate comparison function. A
default lexical comparison will be used. It is an error
to specify both Db.DB_DUPSORT
and Db.DB_RECNUM
.
Calling Db.setFlags with the Db.DB_DUPSORT
flag affects the database, including all threads of
control accessing the database.
If the database already exists when Db.open
is called, the
DB_DUPSORT flag must be the same as the existing
database or an error will be returned.
There are no additional flags that may be specified for the Queue access method.
The following flags may be specified for the Recno access method:
Db.DB_RENUMBER
Specifying the Db.DB_RENUMBER
flag causes
the logical record numbers to be mutable, and change as
records are added to and deleted from the database. For
example, the deletion of record number 4 causes records
numbered 5 and greater to be renumbered downward by one.
If a cursor was positioned to record number 4 before the
deletion, it will refer to the new record number 4, if
any such record exists, after the deletion. If a cursor
was positioned after record number 4 before the
deletion, it will be shifted downward one logical
record, continuing to refer to the same record as it did
before.
Using the Db.put
or
Dbc.put
interfaces to
create new records will cause the creation of multiple
records if the record number is more than one greater
than the largest record currently in the database. For
example, creating record 28, when record 25 was
previously the last record in the database, will create
records 26 and 27 as well as 28. Attempts to retrieve
records that were created in this manner will result in
an error return of
Db.DB_KEYEMPTY
.
If a created record is not at the end of the database, all records following the new record will be automatically renumbered upward by one. For example, the creation of a new record numbered 8 causes records numbered 8 and greater to be renumbered upward by one. If a cursor was positioned to record number 8 or greater before the insertion, it will be shifted upward one logical record, continuing to refer to the same record as it did before.
For these reasons, concurrent access to a Recno database
with the Db.DB_RENUMBER
flag specified may
be largely meaningless, although it is supported.
Calling Db.setFlags with the Db.DB_RENUMBER
flag affects the database, including all threads of
control accessing the database.
If the database already exists when Db.open
is called, the
DB_RENUMBER flag must be the same as the existing
database or an error will be returned.
Db.DB_SNAPSHOT
This flag specifies that any specified re_source
file be read in its entirety when Db.open
is called. If this
flag is not specified, the re_source file may be
read lazily.
Calling Db.setFlags with the Db.DB_SNAPSHOT
flag only affects the specified Db
handle (and any other Berkeley
DB handles opened within the scope of that handle).
java.lang.IllegalArgumentException
- The Db.setFlags method will
fail and throw a IllegalArgumentException exception if an
invalid flag value or parameter was specified.
DbException
public void set_h_ffactor(int h_ffactor) throws DbException
setHashFillFactor(int)
DbException
public void setHashFillFactor(int h_ffactor) throws DbException
The Db.setHashFillFactor method configures a database, not
only operations performed using the specified Db
handle.
The Db.setHashFillFactor method may not be called after the
Db.open
method is called. If
the database already exists when Db.open
is called, the information
specified to Db.setHashFillFactor will be ignored.
(pagesize - 32) / (average_key_size + average_data_size + 8)
h_ffactor
- the desired density within
the hash table.
java.lang.IllegalArgumentException
- The Db.setHashFillFactor
method will fail and throw a IllegalArgumentException
exception if the method was called after Db.open
was called; or if an
invalid flag value or parameter was specified.
DbException
public void set_h_hash(DbHash h_hash_fcn) throws DbException
setHash(DbHash)
DbException
public void setHash(DbHash h_hash_fcn) throws DbException
DbException
public void set_h_nelem(int h_nelem) throws DbException
setHashNumElements(int)
DbException
public void setHashNumElements(int h_nelem) throws DbException
In order for the estimate to be used when creating the
database, the Db.setHashFillFactor
method must also be called. If the
estimate or fill factor are not set or are set too low, hash
tables will still expand gracefully as keys are entered,
although a slight performance degradation may be noticed.
The Db.setHashNumElements method configures a database, not
only operations performed using the specified Db
handle.
The Db.setHashNumElements method may not be called after the
Db.open
method is called. If
the database already exists when Db.open
is called, the information
specified to Db.setHashNumElements will be ignored.
h_nelem
- an estimate of the final
size of the hash table.
java.lang.IllegalArgumentException
- The Db.setHashNumElements
method will fail and throw a IllegalArgumentException
exception if the method was called after Db.open
was called; or if an
invalid flag value or parameter was specified.
DbException
public void set_lorder(int lorder) throws DbException
setByteOrder(int)
DbException
public void setByteOrder(int lorder) throws DbException
The access methods provide no guarantees about the byte ordering of the application data stored in the database, and applications are responsible for maintaining any necessary ordering.
The Db.setByteOrder method configures a database, not only
operations performed using the specified Db
handle.
The Db.setByteOrder method may not be called after the Db.open
method is called. If the
database already exists when Db.open
is called, the information specified to
Db.setByteOrder will be ignored.
lorder
- The lorder parameter
should represent the byte order as an integer; for
example, big endian order is the number 4,321, and little
endian order is the number 1,234.
java.lang.IllegalArgumentException
- The Db.setByteOrder method
will fail and throw a IllegalArgumentException exception
if the method was called after Db.open
was called; or if an
invalid flag value or parameter was specified.
DbException
public void set_pagesize(long pagesize) throws DbException
setPageSize(long)
DbException
public void setPageSize(long pagesize) throws DbException
For information on tuning the Berkeley DB page size, see Selecting a page size .
The Db.setPageSize method configures a database, not only
operations performed using the specified Db
handle.
The Db.setPageSize method may not be called after the Db.open
method is called. If the
database already exists when Db.open
is called, the information specified to
Db.setPageSize will be ignored.
pagesize
- The pagesize
parameter sets the database page size.
java.lang.IllegalArgumentException
- The Db.setPageSize method
will fail and throw a IllegalArgumentException exception
if the method was called after Db.open
was called; or if an
invalid flag value or parameter was specified.
DbException
public void set_re_delim(int re_delim) throws DbException
setRecordDelimiter(int)
DbException
public void setRecordDelimiter(int re_delim) throws DbException
This byte is used for variable length records if the re_source file is specified. If the re_source file is specified and no delimiting byte was specified, <newline> characters (that is, ASCII 0x0a) are interpreted as end-of-record markers.
The Db.setRecordDelimiter method configures a database, not
only operations performed using the specified Db
handle.
The Db.setRecordDelimiter method may not be called after the
Db.open
method is called. If
the database already exists when Db.open
is called, the information
specified to Db.setRecordDelimiter will be ignored.
re_delim
- the delimiting byte used to
mark the end of a record.
java.lang.IllegalArgumentException
- The Db.setRecordDelimiter
method will fail and throw a IllegalArgumentException
exception if the method was called after Db.open
was called; or if an
invalid flag value or parameter was specified.
DbException
public void set_re_len(int re_len) throws DbException
setRecordLength(int)
DbException
public void setRecordLength(int re_len) throws DbException
For the Recno access method, specify that the records are fixed-length, not byte-delimited, and are of length re_len .
Any records added to the database that are less than re_len
bytes long are automatically padded (see Db.setRecordPad
for more
information).
Any attempt to insert records into the database that are greater than re_len bytes long will cause the call to fail immediately and return an error.
The Db.setRecordLength method configures a database, not only
operations performed using the specified Db
handle.
The Db.setRecordLength method may not be called after the
Db.open
method is called. If
the database already exists when Db.open
is called, the information
specified to Db.setRecordLength will be ignored.
re_len
- the length of a Queue or
Recno database record, in bytes.
java.lang.IllegalArgumentException
- The Db.setRecordLength
method will fail and throw a IllegalArgumentException
exception if the method was called after Db.open
was called; or if an
invalid flag value or parameter was specified.
DbException
public void set_re_pad(int re_pad) throws DbException
setRecordPad(int)
DbException
public void setRecordPad(int re_pad) throws DbException
If no pad character is specified, <space> characters (that is, ASCII 0x20) are used for padding.
The Db.setRecordPad method configures a database, not only
operations performed using the specified Db
handle.
The Db.setRecordPad method may not be called after the Db.open
method is called. If the
database already exists when Db.open
is called, the information specified to
Db.setRecordPad will be ignored.
re_pad
- the pad character for
fixed-length records for the Queue and Recno access
methods.
java.lang.IllegalArgumentException
- The Db.setRecordPad method
will fail and throw a IllegalArgumentException exception
if the method was called after Db.open
was called; or if an
invalid flag value or parameter was specified.
DbException
public void set_re_source(java.lang.String source) throws DbException
setRecordSource(String)
DbException
public void setRecordSource(java.lang.String source) throws DbException
The source parameter specifies an underlying flat text
database file that is read to initialize a transient record
number index. In the case of variable length records, the
records are separated, as specified by Db.setRecordDelimiter
.
For example, standard UNIX byte stream files can be
interpreted as a sequence of variable length records separated
by <newline> characters.
In addition, when cached data would normally be written back
to the underlying database file (for example, the Db.close
or Db.sync
methods are called), the
in-memory copy of the database will be written back to the
source file.
By default, the backing source file is read lazily; that is,
records are not read from the file until they are requested by
the application. If multiple processes (not threads) are
accessing a Recno database concurrently, and are either
inserting or deleting records, the backing source file must be
read in its entirety before more than a single process
accesses the database, and only that process should specify
the backing source file as part of the Db.open
call. See the Db.DB_SNAPSHOT
flag for more
information.
Reading and writing the backing source file specified by source cannot be transaction-protected because it involves filesystem operations that are not part of the Db transaction methodology. For this reason, if a temporary database is used to hold the records, it is possible to lose the contents of the source file, for example, if the system crashes at the right instant. If a file is used to hold the database, normal database recovery on that file can be used to prevent information loss, although it is still possible that the contents of source will be lost if the system crashes.
The source file must already exist (but may be
zero-length) when Db.open
is
called.
It is not an error to specify a read-only source file
when creating a database, nor is it an error to modify the
resulting database. However, any attempt to write the changes
to the backing source file using either the Db.sync
or Db.close
methods will fail, of
course. Specify the Db.DB_NOSYNC
flag to the Db.close
method to stop it from attempting to write the
changes to the backing file; instead, they will be silently
discarded.
For all of the previous reasons, the source field is generally used to specify databases that are read-only for Berkeley DB applications; and that are either generated on the fly by software tools or modified using a different mechanism -- for example, a text editor.
The Db.setRecordSource method configures operations performed
using the specified Db
handle, not
all operations performed on the underlying database.
The Db.setRecordSource method may not be called after the
Db.open
method is called. If
the database already exists when Db.open
is called, the information
specified to Db.setRecordSource must be the same as that
historically used to create the database or corruption can
occur.
source
- The backing flat text
database file for a Recno database.
java.lang.IllegalArgumentException
- The Db.setRecordSource
method will fail and throw a IllegalArgumentException
exception if the method was called after Db.open
was called; or if an
invalid flag value or parameter was specified.
DbException
public void set_q_extentsize(int extentsize) throws DbException
setQueueExtentSize(int)
DbException
public void setQueueExtentSize(int extentsize) throws DbException
For information on tuning the extent size, see Selecting a extent size .
The Db.setQueueExtentSize method configures a database, not
only operations performed using the specified Db
handle.
The Db.setQueueExtentSize method may not be called after the
Db.open
method is called. If
the database already exists when Db.open
is called, the information
specified to Db.setQueueExtentSize will be ignored.
extentsize
- the number of pages in a
Queue database extent.
java.lang.IllegalArgumentException
- The Db.setQueueExtentSize
method will fail and throw a IllegalArgumentException
exception if the method was called after Db.open
was called; or if an
invalid flag value or parameter was specified.
DbException
public java.lang.Object stat(int flags) throws DbException
If the Db.DB_FAST_STAT flag has not been specified, the Db.stat method will access some of or all the pages in the database, incurring a severe performance penalty as well as possibly flushing the underlying buffer pool.
In the presence of multiple threads or processes accessing an active database, the information returned by Db.stat may be out-of-date.
If the database was not opened read-only and the Db.DB_FAST_STAT flag was not specified, the cached key and record numbers will be updated after the statistical information has been gathered.
The Db.stat method cannot be transaction-protected. For this reason, it should be called in a thread of control that has no open cursors or active transactions.
In the case of a Hash database, the statistics are returned in an instance of DbHashStat. The data fields are available from DbHashStat:
In the case of a Btree or Recno database, the statistics are returned in an instance of DbBtreeStat. The data fields are available from DbBtreeStat:
In the case of a Queue database, the statistics are returned in an instance of DbQueueStat. The data fields are available from DbQueueStat:
For convenience, the DbBtreeStat, DbHashStat and DbQueueStat classes have a toString method that lists all their data fields.
flags
- must be set to 0 or one of
the following values:
Db.DB_FAST_STAT
Return only the values which do not require traversal of the database.
Among other things, this flag makes it possible for
applications to request key and record counts without
incurring the performance penalty of traversing the
entire database. If the underlying database is of type
Recno, or of type Btree and the database was created
with the
flag, the count of keys will be exact. Otherwise, the
count of keys will be the value saved the last time the
database was traversed, or 0 if no count of keys has
ever been made. If the underlying database is of type
Recno, the count of data items will be exact, otherwise,
the count of data items will be the value saved the last
time the database was traversed, or 0 if no count of
data items has ever been done.Db.DB_RECNUM
DbException
- The Db.stat method may fail
and throw DbException
, encapsulating one of the following non-zero
errors:
java.lang.IllegalArgumentException
- The Db.stat method will fail
and throw a IllegalArgumentException exception if an
invalid flag value or parameter was specified.public void sync(int flags) throws DbException
If the database is in memory only, the Db.sync method has no effect and will always succeed.
It is important to understand that flushing cached
information to disk only minimizes the window of opportunity
for corrupted data. Although unlikely, it is possible for
database corruption to happen if a system or application crash
occurs while writing data to the database. To ensure that
database corruption never occurs, applications must either:
use transactions and logging with automatic recovery; use
logging and application-specific recovery; or edit a copy of
the database, and once all applications using the database
have successfully called Db.close
, atomically replace the original database with the
updated copy.
flags
- currently unused, and must
be set to 0.
DbException
- The Db.sync method may fail
and throw DbException
, encapsulating one of the following non-zero
errors:
java.lang.IllegalArgumentException
- The Db.sync method will fail
and throw a IllegalArgumentException exception if an
invalid flag value or parameter was specified.public int truncate(DbTxn txnid, int flags) throws DbException
It is an error to call the Db.truncate method on a database with open cursors.
flags
- must be set to 0 or the
following value:
Db.DB_AUTO_COMMIT
Enclose the Db.truncate 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, (other than by specifying the
Db.DB_AUTO_COMMIT flag), the txnid parameter is a
transaction handle returned from DbEnv.txnBegin
;
otherwise, null.
DbDeadlockException
- If a transactional database
environment operation was selected to resolve a deadlock,
the Db.truncate 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 Db.truncate method will fail and throw a DbLockNotGrantedException
exception.
java.lang.IllegalArgumentException
- The Db.truncate method will
fail and throw a IllegalArgumentException exception if
there are open cursors in the database; or if an invalid
flag value or parameter was specified.
DbException
public void upgrade(java.lang.String file, int flags) throws DbException
Database upgrades are done in place and are destructive. For example, if pages need to be allocated and no disk space is available, the database may be left corrupted. Backups should be made before databases are upgraded. See Upgrading databases for more information.
Unlike all other database operations, Db.upgrade may only be done on a system with the same byte-order as the database.
If the database was opened within a database environment, the environment variable DB_HOME may be used as the path of the database environment home.
Db.upgrade 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.
file
- the physical file containing
the databases to be upgraded.flags
- must be set to 0 or the
following value:
Db.DB_DUPSORT
This flag is only meaningful when upgrading databases from releases before the Berkeley DB 3.1 release.
As part of the upgrade from the Berkeley DB 3.0 release
to the 3.1 release, the on-disk format of duplicate data
items changed. To correctly upgrade the format requires
applications to specify whether duplicate data items in
the database are sorted or not. Specifying the Db.DB_DUPSORT
flag informs Db.upgrade that the duplicates are sorted;
otherwise they are assumed to be unsorted. Incorrectly
specifying the value of this flag may lead to database
corruption.
Further, because the Db.upgrade method upgrades a
physical file (including all the databases it contains),
it is not possible to use Db.upgrade to upgrade files in
which some of the databases it includes have sorted
duplicate data items, and some of the databases it
includes have unsorted duplicate data items. If the file
does not have more than a single database, if the
databases do not support duplicate data items, or if all
of the databases that support duplicate data items
support the same style of duplicates (either sorted or
unsorted), Db.upgrade will work correctly as long as the
Db.DB_DUPSORT
flag is correctly specified.
Otherwise, the file cannot be upgraded using Db.upgrade;
it must be upgraded manually by dumping and reloading
the databases.
DbException
- The Db.upgrade method may
fail and throw DbException
, encapsulating one of the following non-zero
errors:
java.lang.IllegalArgumentException
- The Db.upgrade method will
fail and throw a IllegalArgumentException exception if the
database is not in the same byte-order as the system; or
if an invalid flag value or parameter was specified.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |