* * 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 {@link * com.sleepycat.db.Db#close Db.close}, {@link * com.sleepycat.db.Db#remove Db.remove}, or {@link * com.sleepycat.db.Db#rename Db.rename} methods are called, the * handle may not be accessed again, regardless of the method's * return.
*/ public class Db { private long swigCPtr; protected boolean swigCMemOwn; protected Db(long cPtr, boolean cMemoryOwn) { swigCMemOwn = cMemoryOwn; swigCPtr = cPtr; } protected Db() { this(0, false); } protected void delete() { if (swigCPtr != 0 && swigCMemOwn) { swigCMemOwn = false; } swigCPtr = 0; } protected static long getCPtr(Db obj) { return (obj == null) ? 0 : obj.swigCPtr; } final static int GIGABYTE = 1 << 30; // Internally, the JNI layer creates a global reference to each Db, // which can potentially be different to this. We keep a copy here so // we can clean up after destructors. private Object db_ref; private DbEnv dbenv; private boolean private_dbenv; private DbAppendRecno append_recno_handler; private DbBtreeCompare bt_compare_handler; private DbBtreePrefix bt_prefix_handler; private DbDupCompare dup_compare_handler; private DbFeedbackHandler db_feedback_handler; private DbHash h_hash_handler; private DbSecondaryKeyCreate seckey_create_handler; // Called by the Db constructor private void initialize(DbEnv dbenv) { if (dbenv == null) { private_dbenv = true; dbenv = db_java.getDbEnv0(this); dbenv.initialize(); } this.dbenv = dbenv; db_ref = db_java.initDbRef0(this, this); } private void cleanup() { swigCPtr = 0; db_java.deleteRef0(db_ref); db_ref = null; if (private_dbenv) { dbenv.cleanup(); } dbenv = null; } /** * The Db.close method flushes any cached database information to * disk, closes any open cursors, frees any allocated resources, * and closes any underlying files.* * The {@link com.sleepycat.db.Db 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 {@link * com.sleepycat.db.Dbc Dbc} and {@link com.sleepycat.db.DbTxn * DbTxn} handles.
* * Because key/data pairs are cached in memory, failing to sync * the file with the Db.close or {@link com.sleepycat.db.Db#sync * 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 {@link com.sleepycat.db.Db * Db} concurrently, only a single thread may call the Db.close * method.
* * The {@link com.sleepycat.db.Db Db} handle may not be accessed * again after Db.close is called, regardless of its return.
* * @param flags must be set to 0 or by * bitwise inclusively OR 'ing together one or more of * the following values: *
*
* Do not flush cached information to disk. The {@link
* com.sleepycat.db.Db#DB_NOSYNC Db.DB_NOSYNC}
* 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.
* * 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.
* * The Db.getDbEnv method may be called at any time during the * life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.getDbEnv method returns the handle * for the database environment underlying the database. */ public DbEnv getDbEnv() throws DbException { return dbenv; } private final void handle_append_recno(Dbt data, int recno) throws DbException { append_recno_handler.dbAppendRecno(this, data, recno); } private final int handle_bt_compare(Dbt dbt1, Dbt dbt2) { return bt_compare_handler.compare(this, dbt1, dbt2); } private final int handle_bt_prefix(Dbt dbt1, Dbt dbt2) { return bt_prefix_handler.prefix(this, dbt1, dbt2); } private final void handle_db_feedback(int opcode, int percent) { db_feedback_handler.feedback(this, opcode, percent); } private final int handle_dup_compare(Dbt dbt1, Dbt dbt2) { return dup_compare_handler.compareDuplicates(this, dbt1, dbt2); } private final int handle_h_hash(byte[] data, int len) { return h_hash_handler.hash(this, data, len); } private final int handle_seckey_create(Dbt key, Dbt data, Dbt result) throws DbException { return seckey_create_handler.secondaryKeyCreate( this, key, data, result); } /** * The {@link com.sleepycat.db.Db#isEncrypted Db.isEncrypted} * method returns false if the underlying database files are * encrypted and true if they are not.* * The {@link com.sleepycat.db.Db#isEncrypted Db.isEncrypted} * method may not be called before the {@link * com.sleepycat.db.Db#open Db.open} method has been called.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The {@link com.sleepycat.db.Db#isEncrypted * Db.isEncrypted} method returns false if the underlying * database files are encrypted and true if they are not. */ public boolean isEncrypted() throws DbException { return (get_encrypt_flags() != 0); } /** * The Db.open method opens the database represented by the * file and database parameters for both reading and * writing.* * 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 {@link com.sleepycat.db.Dbt 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 {@link com.sleepycat.db.DbEnv#setDataDir 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 * * @param 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.
* @param 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.
* @param flags must be set to 0 or by * bitwise inclusively OR 'ing together one or more of * the following values: ** * 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. *
*
* Create the database. If the database does not already
* exist and the Db.DB_CREATE flag is not
* specified, the Db.open will fail.
* * 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 * {@link com.sleepycat.db.Db Db} handles used to perform * dirty reads or database updates, otherwise requests for * dirty reads may not be honored and the read may block. *
*
* Return an error if the database already exists. The
* Db.DB_EXCL flag is only meaningful when
* specified with the Db.DB_CREATE flag.
* * Do not map this database into process memory (see the * {@link com.sleepycat.db.DbEnv#setMemoryPoolMapSize * DbEnv.setMemoryPoolMapSize} method for further * information).
* * 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.
* * Cause the {@link com.sleepycat.db.Db 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 {@link
* com.sleepycat.db.Db#DB_THREAD Db.DB_THREAD}
* flag was specified.
* * 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.
* * Applications should never remove databases with open {@link * com.sleepycat.db.Db 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 * {@link com.sleepycat.db.Db#open Db.open} method on any {@link * com.sleepycat.db.Db Db} handle. If the {@link * com.sleepycat.db.Db#open Db.open} method has already been * called on a {@link com.sleepycat.db.Db Db} handle, close the * existing handle and create a new one before calling Db.remove. *
* * The {@link com.sleepycat.db.Db 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 {@link com.sleepycat.db.DbEnv#setDataDir * DbEnv.setDataDir} method, or by setting the "set_data_dir" * string in the environment's DB_CONFIG file.
* * @param database the database to be removed. * @param file the physical file which * contains the database(s) to be removed. * @param flags currently unused, and must * be set to 0. * @throws DbException The Db.remove method may * fail and throw {@link com.sleepycat.db.DbException * DbException}, encapsulating one of the following non-zero * errors: ** * 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 * {@link com.sleepycat.db.Db#open Db.open} method on any {@link * com.sleepycat.db.Db Db} handle. If the {@link * com.sleepycat.db.Db#open Db.open} method has already been * called on a {@link com.sleepycat.db.Db Db} handle, close the * existing handle and create a new one before calling Db.rename. *
* * The {@link com.sleepycat.db.Db 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 {@link com.sleepycat.db.DbEnv#setDataDir * DbEnv.setDataDir} method, or by setting the "set_data_dir" * string in the environment's DB_CONFIG file.
* * @param database the database to be removed. * @param file the physical file which * contains the database(s) to be removed. * @param flags currently unused, and must * be set to 0. * @param newname the new name of the database * or file. * @throws DbException The Db.rename method may * fail and throw {@link com.sleepycat.db.DbException * DbException}, encapsulating one of the following non-zero * errors: ** * 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 {@link * com.sleepycat.db.Db#open Db.open} method is called.
* * The {@link com.sleepycat.db.Db 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 {@link com.sleepycat.db.DbEnv#setDataDir * DbEnv.setDataDir} method, or by setting the "set_data_dir" * string in the environment's DB_CONFIG file.
* * @param 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.
* @param file the physical file in which * the databases to be verified are found. * @param flags must be set to 0 or the * following value: ** * 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.
*
* 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.
*
* 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.
* * 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.
*
* 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.
* * The {@link com.sleepycat.db.DbEnv#setErrorHandler * DbEnv.setErrorHandler} and Db.setOnError methods are used to * enhance the mechanism for reporting error messages to the * application. The {@link com.sleepycat.db.DbEnv#setErrorHandler * 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 {@link * com.sleepycat.db.Db#setErrorPrefix Db.setErrorPrefix} or * {@link com.sleepycat.db.DbEnv#setErrorPrefix * 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 {@link * com.sleepycat.db.DbEnv#setErrorStream DbEnv.setErrorStream} * and {@link com.sleepycat.db.Db#setErrorStream * 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 {@link com.sleepycat.db.Db Db} handles opened inside of * Berkeley DB environments, calling the Db.setOnError method * affects the entire environment and is equivalent to calling * the {@link com.sleepycat.db.DbEnv#setErrorHandler * DbEnv.setErrorHandler} method.
* * The Db.setOnError method may be called at any time during the * life of the application.
* * @param 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 {@link com.sleepycat.db.Db#setErrorPrefix * Db.setErrorPrefix} or {@link * com.sleepycat.db.DbEnv#setErrorPrefix * DbEnv.setErrorPrefix}).
* * The msg parameter is the error message string. * @throws DbException Signals that an exception of some sort * has occurred. */ public void setErrorHandler(DbErrorHandler db_errcall_fcn) throws DbException { dbenv.setErrorHandler(db_errcall_fcn); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getErrorPrefix()} */ public String get_errpfx() { return getErrorPrefix(); } /** * The Db.getErrorPrefix method returns the error prefix.
* * The Db.getErrorPrefix method may be called at any time during * the life of the application.
* * @return The Db.getErrorPrefix method returns the error * prefix. */ public String getErrorPrefix() { return dbenv.get_errpfx(); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #setErrorPrefix(String)} */ public void set_errpfx(String errpfx) { setErrorPrefix(errpfx); } /** * Set the prefix string that appears before error messages * issued by Berkeley DB.* * For {@link com.sleepycat.db.Db Db} handles opened inside of * Berkeley DB environments, calling the Db.setErrorPrefix method * affects the entire environment and is equivalent to calling * the {@link com.sleepycat.db.DbEnv#setErrorPrefix * DbEnv.setErrorPrefix} method.
* * The Db.setErrorPrefix method may be called at any time during * the life of the application.
* * @param errpfx the application-specified error prefix for * additional error messages. */ public void setErrorPrefix(String errpfx) { dbenv.set_errpfx(errpfx); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #setErrorStream(java.io.OutputStream)} */ public void set_error_stream(java.io.OutputStream stream) { setErrorStream(stream); } /** * When an error occurs in the Berkeley DB library, an exception * is thrown. In some cases, however, the error information known * to the Java layer may be insufficient to completely describe * the cause of the error, especially during initial application * debugging.* * The {@link com.sleepycat.db.DbEnv#setErrorStream * 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 {@link com.sleepycat.db.DbEnv#setErrorPrefix * DbEnv.setErrorPrefix}), an error string, and a trailing * <newline> character.
* * Alternatively, you can use the {@link * com.sleepycat.db.DbEnv#setErrorHandler 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 {@link com.sleepycat.db.Db Db} handles opened inside of * Berkeley DB environments, calling the Db.setErrorStream method * affects the entire environment and is equivalent to calling * the {@link com.sleepycat.db.DbEnv#setErrorStream * DbEnv.setErrorStream} method.
* * @param stream the application-specified output stream to be * used for additional error information. */ public void setErrorStream(java.io.OutputStream stream) { dbenv.set_error_stream(stream); } /** * @deprecated Replaced in Berkeley DB 4.2 by {@link * #setFeedbackHandler(DbFeedbackHandler)} */ public void set_feedback(DbFeedback feedback) throws DbException { final DbFeedback ffeedback = feedback; setFeedbackHandler( new DbFeedbackHandler() { public void feedback(Db db, int opcode, int percent) { ffeedback.feedback(db, opcode, percent); } }); } /** * 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). In * such cases, the Berkeley DB methods will throw a {@link * com.sleepycat.db.DbRunRecoveryException * 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 {@link * com.sleepycat.db.DbRunRecoveryException * DbRunRecoveryException} is about to be thrown from a Berkeley * DB method.* * For {@link com.sleepycat.db.Db Db} handles opened inside of * Berkeley DB environments, calling the Db.setPanic method * affects the entire environment and is equivalent to calling * the {@link com.sleepycat.db.DbEnv#setPanicHandler * DbEnv.setPanicHandler} method.
* * The Db.setPanic method may be called at any time during the * life of the application.
* * @param 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. * @throws DbException Signals that an exception of some sort * has occurred. */ public void setPanicHandler(DbPanicHandler db_panic_fcn) throws DbException { dbenv.setPanicHandler(db_panic_fcn); } // Don't remove these - special comments used by s_java to add constants // BEGIN-JAVA-SPECIAL-CONSTANTS /* * DO NOT EDIT: automatically built by dist/s_java_const. */ /** * A constant used to configure the system. It is used in the * following locations: *
* * 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.
* @param flags must be set to 0 or by bitwise * inclusively OR 'ing together one or more of the * following values: ** * 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.
*
* All read operations performed by the cursor may return
* modified but not yet committed data. Silently ignored if
* the {@link com.sleepycat.db.Db#DB_DIRTY_READ Db.DB_DIRTY_READ
* } flag was not specified when the underlying database
* was opened.
*
* Specify that the cursor will be used to update the
* database. The underlying database environment must have
* been opened using the {@link
* com.sleepycat.db.Db#DB_INIT_CDB Db.DB_INIT_CDB
* } flag.
* * When called on a database that has been made into a secondary * index using the {@link com.sleepycat.db.Db#associate * Db.associate} method, the Db.delete method deletes the * key/data pair from the primary database and all secondary * indices.
* * @param key The key {@link * com.sleepycat.db.Dbt Dbt} operated on. * @param flags must be set to 0 or the * following value: ** * 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.
*
* The Db.delete method will return
* Db.DB_NOTFOUND if the specified key is
* not in the database.
*
* 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.
* * The {@link com.sleepycat.db.DbEnv#err DbEnv.err} method * constructs an error message consisting of the following * elements:
* * If no error callback function has been set using the {@link * com.sleepycat.db.DbEnv#setErrorHandler DbEnv.setErrorHandler} * method, any prefix string specified using the {@link * com.sleepycat.db.DbEnv#setErrorPrefix DbEnv.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 * {@link com.sleepycat.db.DbEnv#strerror DbEnv.strerror} method. *
* * This constructed error message is then handled as follows:
** * @param error the error value for which the {@link * com.sleepycat.db.DbEnv#err DbEnv.err} and Db.err methods * will display a explanatory string. * @param message an error message to display. */ public void err(int error, String message) { db_javaJNI.Db_err(swigCPtr, error, message); } /** * The {@link com.sleepycat.db.DbEnv#errx DbEnv.errx} and Db.errx * methods perform identically to the {@link * com.sleepycat.db.DbEnv#err DbEnv.err} and Db.err methods, * except that they do not append the final separator characters * and standard error string to the error message. * * @param error the error value for which the {@link * com.sleepycat.db.DbEnv#err DbEnv.err} and Db.err methods * will display a explanatory string. * @param message an error message to display. */ public void errx(String message) { db_javaJNI.Db_errx(swigCPtr, message); } /** * The Db.get method retrieves key/data pairs from the database. * The byte array and length of the data associated with the * specified key are returned in the structure to which * data refers.* * If an error callback function has been set (see {@link * com.sleepycat.db.Db#setErrorHandler Db.setErrorHandler} and * {@link com.sleepycat.db.DbEnv#setErrorHandler * DbEnv.setErrorHandler}), that function is called with two * parameters: any prefix string specified (see {@link * com.sleepycat.db.Db#setErrorPrefix Db.setErrorPrefix} and * {@link com.sleepycat.db.DbEnv#setErrorPrefix * DbEnv.setErrorPrefix}) and the error message.
* * If an OutputStream has been set (see {@link * com.sleepycat.db.DbEnv#setErrorStream DbEnv.setErrorStream} * and {@link com.sleepycat.db.Db#setErrorStream * Db.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.
* * 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 {@link * com.sleepycat.db.Dbc#get Dbc.get} for details.
* * When called on a database that has been made into a secondary * index using the {@link com.sleepycat.db.Db#associate * 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.
* * @param data The data {@link * com.sleepycat.db.Dbt Dbt} operated on. * @param flags must be set to 0 or one of * the following values: *
*
* 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 {@link com.sleepycat.db.Dbt 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.
*
* 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.
* * 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.
* * 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.
*
* 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.
*
* Read modified but not yet committed data. Silently
* ignored if the {@link com.sleepycat.db.Db#DB_DIRTY_READ
* Db.DB_DIRTY_READ} flag was not specified
* when the underlying database was opened.
* * 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 {@link
* com.sleepycat.db.Db#DB_DBT_USERMEM Db.DB_DBT_USERMEM
* }). 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 {@link com.sleepycat.db.DbMemoryException
* 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 {@link
* com.sleepycat.db.Db#associate Db.associate} method.
* * See {@link com.sleepycat.db.DbMultipleDataIterator * DbMultipleDataIterator} for more information.
* * 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
* {@link com.sleepycat.db.Db#DB_RMW Db.DB_RMW
* } flag to the Db.get call is meaningful only in the
* presence of transactions.
*
* The Db.get method will return
* Db.DB_NOTFOUND if the specified key is
* not in the database.
*
* 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.
* * The Db.isByteSwapped method may not be called before the * {@link com.sleepycat.db.Db#open Db.open} method has been * called.
* * @throws IllegalArgumentException The Db.isByteSwapped method * will fail and throw a IllegalArgumentException exception * if the method was called before {@link * com.sleepycat.db.Db#open Db.open} was called; or if an * invalid flag value or parameter was specified. * @return 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. */ public boolean isByteSwapped() throws DbException { return db_javaJNI.Db_get_byteswapped(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getCacheSize()} */ public long get_cachesize() throws DbException { return getCacheSize(); } /** * The Db.getCacheSize method returns the size of the cache. ** * The Db.getCacheSize method may be called at any time during * the life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.getCacheSize method returns the * size of the cache. */ public long getCacheSize() throws DbException { return db_javaJNI.Db_get_cachesize(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getCacheSizeNcache()} */ public int get_cachesize_ncache() throws DbException { return getCacheSizeNcache(); } /** * The DbEnv.getCacheSizeNcache method returns the number of * caches.* * The DbEnv.getCacheSizeNcache method may be called at any time * during the life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The DbEnv.getCacheSizeNcache method * returns the number of caches. */ public int getCacheSizeNcache() throws DbException { return db_javaJNI.Db_get_cachesize_ncache(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getFileName()} */ public String get_filename() throws DbException { return getFileName(); } /** * The Db.getFileName method returns the current filename. ** * The Db.getFileName method may be called at any time during the * life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.getFileName method returns the * current filename. */ public String getFileName() throws DbException { return db_javaJNI.Db_get_filename(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getDatabaseName()} */ public String get_dbname() throws DbException { return getDatabaseName(); } /** * The Db.getDatabaseName method returns the current database * name.* * The Db.getDatabaseName method may be called at any time during * the life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.getDatabaseName method returns the * current database name. */ public String getDatabaseName() throws DbException { return db_javaJNI.Db_get_dbname(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getEncryptFlags()} */ public int get_encrypt_flags() throws DbException { return getEncryptFlags(); } /** * The Db.getEncryptFlags method returns the encryption flags. ** * The Db.getEncryptFlags method may be called at any time during * the life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.getEncryptFlags method returns the * encryption flags. */ public int getEncryptFlags() throws DbException { return db_javaJNI.Db_get_encrypt_flags(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getFlags()} */ public int get_flags() throws DbException { return getFlags(); } /** * The Db.getFlags method returns the current flags.* * The Db.getFlags method may be called at any time during the * life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.getFlags method returns the * current flags. */ public int getFlags() throws DbException { return db_javaJNI.Db_get_flags(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getByteOrder()} */ public int get_lorder() throws DbException { return 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.* * The Db.getByteOrder method may be called at any time during * the life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return 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. */ public int getByteOrder() throws DbException { return db_javaJNI.Db_get_lorder(swigCPtr); } /** * The Db.get_mpf method returns the handle for the cache file * underlying the database.* * The Db.get_mpf method may be called at any time during the * life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.get_mpf method returns the handle * for the cache file underlying the database. */ public DbMpoolFile get_mpf() throws DbException { long cPtr = db_javaJNI.Db_get_mpf(swigCPtr); return (cPtr == 0) ? null : new DbMpoolFile(cPtr, false); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getOpenFlags()} */ public int get_open_flags() throws DbException { return getOpenFlags(); } /** * The Db.getOpenFlags method returns the current open method * flags.* * The Db.getOpenFlags method may not be called before the * Db.open method has been called.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.getOpenFlags method returns the * current open method flags. */ public int getOpenFlags() throws DbException { return db_javaJNI.Db_get_open_flags(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getPageSize()} */ public int get_pagesize() throws DbException { return getPageSize(); } /** * The Db.getPageSize method returns the page size.* * The Db.getPageSize method may be called at any time during the * life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.getPageSize method returns the * page size. */ public int getPageSize() throws DbException { return db_javaJNI.Db_get_pagesize(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getBtreeMinKey()} */ public int get_bt_minkey() throws DbException { return getBtreeMinKey(); } /** * The Db.getBtreeMinKey method returns the minimum number of * key/data pairs intended to be stored on any single Btree leaf * page.* * The Db.getBtreeMinKey method may be called at any time during * the life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.getBtreeMinKey method returns the * minimum number of key/data pairs intended to be stored on * any single Btree leaf page. */ public int getBtreeMinKey() throws DbException { return db_javaJNI.Db_get_bt_minkey(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getHashFillFactor()} */ public int get_h_ffactor() throws DbException { return getHashFillFactor(); } /** * The Db.getHashFillFactor method returns the hash table * density.* * The Db.getHashFillFactor method may be called at any time * during the life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.getHashFillFactor method returns * the hash table density. */ public int getHashFillFactor() throws DbException { return db_javaJNI.Db_get_h_ffactor(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getHashNumElements()} */ public int get_h_nelem() throws DbException { return getHashNumElements(); } /** * The Db.getHashNumElements method returns the estimate of the * final size of the hash table.* * The Db.getHashNumElements method may be called at any time * during the life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.getHashNumElements method returns * the estimate of the final size of the hash table. */ public int getHashNumElements() throws DbException { return db_javaJNI.Db_get_h_nelem(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getRecordDelimiter()} */ public int get_re_delim() throws DbException { return getRecordDelimiter(); } /** * The Db.getRecordDelimiter method returns the delimiting byte. ** * The Db.getRecordDelimiter method may be called at any time * during the life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.getRecordDelimiter method returns * the delimiting byte. */ public int getRecordDelimiter() throws DbException { return db_javaJNI.Db_get_re_delim(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getRecordLength()} */ public int get_re_len() throws DbException { return getRecordLength(); } /** * The Db.getRecordLength method returns the record length. ** * The Db.getRecordLength method may be called at any time during * the life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.getRecordLength method returns the * record length. */ public int getRecordLength() throws DbException { return db_javaJNI.Db_get_re_len(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getRecordPad()} */ public int get_re_pad() throws DbException { return getRecordPad(); } /** * The Db.getRecordPad method returns the pad character.* * The Db.getRecordPad method may be called at any time during * the life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.getRecordPad method returns the * pad character. */ public int getRecordPad() throws DbException { return db_javaJNI.Db_get_re_pad(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getRecordSource()} */ public String get_re_source() throws DbException { return getRecordSource(); } /** * The Db.getRecordSource method returns the source file.* * The Db.getRecordSource method may be called at any time during * the life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.getRecordSource method returns the * source file. */ public String getRecordSource() throws DbException { return db_javaJNI.Db_get_re_source(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getQueueExtentSize()} */ public int get_q_extentsize() throws DbException { return getQueueExtentSize(); } /** * The Db.getQueueExtentSize method returns the number of pages * in an extent.* * The Db.getQueueExtentSize method may be called at any time * during the life of the application.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.getQueueExtentSize method returns * the number of pages in an extent. */ public int getQueueExtentSize() throws DbException { return db_javaJNI.Db_get_q_extentsize(swigCPtr); } public int get_flags_raw() throws DbException { return db_javaJNI.Db_get_flags_raw(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #isTransactional()} */ public boolean get_transactional() throws DbException { return isTransactional(); } /** * The Db.isTransactional method returns true if the {@link * com.sleepycat.db.Db 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.
* * @throws DbException Signals that an exception of some sort * has occurred. * @return The Db.isTransactional method returns * true if the {@link com.sleepycat.db.Db Db} handle has been * opened in a transactional mode. */ public boolean isTransactional() throws DbException { return db_javaJNI.Db_get_transactional(swigCPtr); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #getDbType()} */ public int get_type() throws DbException { return getDbType(); } /** * The Db.getDbType method returns the type of the underlying * access method (and file format). The type value is one of * Db.DB_BTREE, Db.DB_HASH, Db.DB_RECNO, or Db.DB_QUEUE. This * value may be used to determine the type of the database after * a return from {@link com.sleepycat.db.Db#open Db.open} with * the type parameter set to Db.DB_UNKNOWN.* * The Db.getDbType method may not be called before the {@link * com.sleepycat.db.Db#open Db.open} method has been called.
* * @throws IllegalArgumentException The Db.getDbType method will * fail and throw a IllegalArgumentException exception if the * method was called before {@link com.sleepycat.db.Db#open * Db.open} was called; or if an invalid flag value or * parameter was specified. * @return The Db.getDbType method * returns the type of the underlying access method (and file * format). */ public int getDbType() throws DbException { return db_javaJNI.Db_get_type(swigCPtr); } /** * The Db.join method creates a specialized join cursor for use * in performing equality or natural joins on secondary indices. * For information on how to organize your data to use this * functionality, see * Equality join .* * The Db.join method method is called using the {@link * com.sleepycat.db.Db Db} handle of the primary database.
** * The join cursor supports only the {@link * com.sleepycat.db.Dbc#get 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.) * * @param 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 {@link * com.sleepycat.db.Dbc#get Dbc.get} call with the {@link * com.sleepycat.db.Db#DB_SET 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.
* @param flags must be set to 0 or the * following value: *
*
* 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.
* * 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. * * @param key The key {@link * com.sleepycat.db.Dbt Dbt} operated on. * @param 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. * @param txnid If the operation is to be * transaction-protected, the txnid parameter is a * transaction handle returned from {@link * com.sleepycat.db.DbEnv#txnBegin 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. * @param flags currently unused, and must * be set to 0. * @throws DbException The Db.keyRange method may * fail and throw {@link com.sleepycat.db.DbException * DbException}, encapsulating one of the following non-zero * errors: * @throws DbDeadlockException If a transactional database * environment operation was selected to resolve a deadlock, * the Db.keyRange method will fail and throw a {@link * com.sleepycat.db.DbDeadlockException DbDeadlockException} * exception. * @throws 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 {@link * com.sleepycat.db.DbLockNotGrantedException * DbLockNotGrantedException} exception. * @throws 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 void keyRange(DbTxn txnid, Dbt key, DbKeyRange key_range, int flags) throws DbException { db_javaJNI.Db_key_range(swigCPtr, DbTxn.getCPtr(txnid), key, key_range, flags); } void open0(DbTxn txnid, String file, String database, int type, int flags, int mode) { db_javaJNI.Db_open0(swigCPtr, DbTxn.getCPtr(txnid), file, database, type, flags, mode); } /** * The Db.get method retrieves key/data pairs from the database. * The byte array and length of the data associated with the * specified key are returned in the structure to which * data refers.* * 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 {@link * com.sleepycat.db.Dbc#get Dbc.get} for details.
* * When called on a database that has been made into a secondary * index using the {@link com.sleepycat.db.Db#associate * 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.
* * @param data The data {@link * com.sleepycat.db.Dbt Dbt} operated on. * @param flags must be set to 0 or one of * the following values: *
*
* 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 {@link com.sleepycat.db.Dbt 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.
*
* 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.
* * 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.
* * 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.
*
* 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.
*
* Read modified but not yet committed data. Silently
* ignored if the {@link com.sleepycat.db.Db#DB_DIRTY_READ
* Db.DB_DIRTY_READ} flag was not specified
* when the underlying database was opened.
* * 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 {@link
* com.sleepycat.db.Db#DB_DBT_USERMEM Db.DB_DBT_USERMEM
* }). 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 {@link com.sleepycat.db.DbMemoryException
* 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 {@link
* com.sleepycat.db.Db#associate Db.associate} method.
* * See {@link com.sleepycat.db.DbMultipleDataIterator * DbMultipleDataIterator} for more information.
* * 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
* {@link com.sleepycat.db.Db#DB_RMW Db.DB_RMW
* } flag to the Db.get call is meaningful only in the
* presence of transactions.
*
* The Db.get method will return
* Db.DB_NOTFOUND if the specified key is
* not in the database.
*
* 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.
*
* 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.
* * 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.
*
* 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.
* * 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.
*
* The Db.put method will return {@link
* com.sleepycat.db.Db#DB_KEYEXIST Db.DB_KEYEXIST
* } if Db.DB_NODUPDATA is set and the
* key/data pair already appears in the database.
*
* The Db.put method will return {@link
* com.sleepycat.db.Db#DB_KEYEXIST Db.DB_KEYEXIST
* } if Db.DB_NOOVERWRITE is set and the key
* already appears in the database.
* * 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 {@link * com.sleepycat.db.Db Db} handle.
* * The Db.setBtreeMinKey method may not be called after the * {@link com.sleepycat.db.Db#open Db.open} method is called. If * the database already exists when {@link * com.sleepycat.db.Db#open Db.open} is called, the information * specified to Db.setBtreeMinKey will be ignored.
* * 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 {@link * com.sleepycat.db.Db#open Db.open} method is called.
* * @param bytes The size of the cache in * bytes. * @param ncache the number of caches to * create. * @throws 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 * {@link com.sleepycat.db.Db#open Db.open} was called; or if * an invalid flag value or parameter was specified. */ public void setCacheSize(long bytes, int ncache) throws DbException { db_javaJNI.Db_set_cachesize(swigCPtr, bytes, ncache); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #setDuplicateCompare(DbDupCompare)} */ public void set_dup_compare(DbDupCompare dup_compare_fcn) throws DbException { setDuplicateCompare(dup_compare_fcn); } public void setDuplicateCompare(DbDupCompare dup_compare_fcn) throws DbException { db_javaJNI.Db_set_dup_compare(swigCPtr, (dup_compare_handler = dup_compare_fcn)); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #setEncrypted(String,int)} */ public void set_encrypt(String passwd, int flags) throws DbException { setEncrypted(passwd, flags); } /** * Set the password used by the Berkeley DB library to perform * encryption and decryption.* * 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 {@link * com.sleepycat.db.Db#open Db.open} method is called.
* * @param flags must be set to 0 or the * following value: ** * Use the Rijndael/AES (also known as the Advanced * Encryption Standard and Federal Information Processing * Standard (FIPS) 197) algorithm for encryption or * decryption.
* * The Db.setFlags method may not be called after the {@link * com.sleepycat.db.Db#open Db.open} method is called.
* * @param 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:
** * 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 {@link
* com.sleepycat.db.Db Db} handle (and any other Berkeley
* DB handles opened within the scope of that handle).
* * If the database already exists when {@link * com.sleepycat.db.Db#open Db.open} is called, the * DB_CHKSUM flag will be ignored.
If creating * additional databases in a file, the checksum behavior * specified must be consistent with the existing databases * in the file or an error will be returned.* * Encrypt the database using the cryptographic password * specified to the {@link com.sleepycat.db.DbEnv#setEncrypted * DbEnv.setEncrypted} or {@link * com.sleepycat.db.Db#setEncrypted Db.setEncrypted} * methods.
*
* Calling Db.setFlags with the Db.DB_ENCRYPT
* flag only affects the specified {@link
* com.sleepycat.db.Db Db} handle (and any other Berkeley
* DB handles opened within the scope of that handle).
* * If the database already exists when {@link * com.sleepycat.db.Db#open Db.open} is called, the * DB_ENCRYPT flag must be the same as the existing * database or an error will be returned.
If creating * additional databases in a file, the encryption behavior * specified must be consistent with the existing databases * in the file 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.
*
* 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 {@link
* com.sleepycat.db.Db#DB_NOSYNC Db.DB_NOSYNC
* }, or all database changes must be flushed from the
* database environment cache using the {@link
* com.sleepycat.db.DbEnv#txnCheckpoint
* 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 {@link
* com.sleepycat.db.Db 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:
** * 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 {@link * com.sleepycat.db.Db#open 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.
*
* 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 {@link * com.sleepycat.db.Db#open Db.open} is called, the * DB_DUPSORT flag must be the same as the existing * database or an error will be returned.
*
* Support retrieval from the Btree using record numbers.
* For more information, see the {@link
* com.sleepycat.db.Db#DB_SET_RECNO Db.DB_SET_RECNO
* } flag to the {@link com.sleepycat.db.Db#get Db.get} and
* {@link com.sleepycat.db.Dbc#get 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 {@link * com.sleepycat.db.Db#open Db.open} is called, the * DB_RECNUM flag must be the same as the existing database * or an error will be returned.
* * 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 {@link
* com.sleepycat.db.Db 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:
** * 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 {@link * com.sleepycat.db.Db#open Db.open} is called, the DB_DUP * flag must be the same as the existing database or an * error will be returned.
*
* 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 {@link * com.sleepycat.db.Db#open 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:
*
*
* 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 {@link com.sleepycat.db.Db#put Db.put} or
* {@link com.sleepycat.db.Dbc#put 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 {@link * com.sleepycat.db.Db#open Db.open} is called, the * DB_RENUMBER flag must be the same as the existing * database or an error will be returned.
* * This flag specifies that any specified re_source * file be read in its entirety when {@link * com.sleepycat.db.Db#open 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 {@link
* com.sleepycat.db.Db Db} handle (and any other Berkeley
* DB handles opened within the scope of that handle).
* * The Db.setHashFillFactor method configures a database, not * only operations performed using the specified {@link * com.sleepycat.db.Db Db} handle.
* * The Db.setHashFillFactor method may not be called after the * {@link com.sleepycat.db.Db#open Db.open} method is called. If * the database already exists when {@link * com.sleepycat.db.Db#open Db.open} is called, the information * specified to Db.setHashFillFactor will be ignored.
The * density is an approximation of the number of keys allowed to * accumulate in any one bucket, determining when the hash table * grows or shrinks. If you know the average sizes of the keys * and data in your data set, setting the fill factor can enhance * performance. A reasonable rule computing fill factor is to set * it to the following:* * @param h_ffactor the desired density within * the hash table. * @throws IllegalArgumentException The Db.setHashFillFactor * method will fail and throw a IllegalArgumentException * exception if the method was called after {@link * com.sleepycat.db.Db#open Db.open} was called; or if an * invalid flag value or parameter was specified. */ public void setHashFillFactor(int h_ffactor) throws DbException { db_javaJNI.Db_set_h_ffactor(swigCPtr, h_ffactor); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #setHash(DbHash)} */ public void set_h_hash(DbHash h_hash_fcn) throws DbException { setHash(h_hash_fcn); } public void setHash(DbHash h_hash_fcn) throws DbException { db_javaJNI.Db_set_h_hash(swigCPtr, (h_hash_handler = h_hash_fcn)); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #setHashNumElements(int)} */ public void set_h_nelem(int h_nelem) throws DbException { setHashNumElements(h_nelem); } /** * Set an estimate of the final size of the hash table.(pagesize - 32) / (average_key_size + average_data_size + 8)*
* * In order for the estimate to be used when creating the * database, the {@link com.sleepycat.db.Db#setHashFillFactor * 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 {@link * com.sleepycat.db.Db Db} handle.
* * The Db.setHashNumElements method may not be called after the * {@link com.sleepycat.db.Db#open Db.open} method is called. If * the database already exists when {@link * com.sleepycat.db.Db#open Db.open} is called, the information * specified to Db.setHashNumElements will be ignored.
* * @param h_nelem an estimate of the final * size of the hash table. * @throws IllegalArgumentException The Db.setHashNumElements * method will fail and throw a IllegalArgumentException * exception if the method was called after {@link * com.sleepycat.db.Db#open Db.open} was called; or if an * invalid flag value or parameter was specified. */ public void setHashNumElements(int h_nelem) throws DbException { db_javaJNI.Db_set_h_nelem(swigCPtr, h_nelem); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #setByteOrder(int)} */ public void set_lorder(int lorder) throws DbException { setByteOrder(lorder); } /** * Set the byte order for integers in the stored database * metadata. The host byte order of the machine where the * Berkeley DB library was compiled will be used if no byte order * is set.* * 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 {@link * com.sleepycat.db.Db Db} handle.
* * The Db.setByteOrder method may not be called after the {@link * com.sleepycat.db.Db#open Db.open} method is called. If the * database already exists when {@link com.sleepycat.db.Db#open * Db.open} is called, the information specified to * Db.setByteOrder will be ignored.
If creating additional * databases in a single physical file, information specified to * Db.setByteOrder will be ignored and the byte order of the * existing databases will be used. * * @param 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. * @throws IllegalArgumentException The Db.setByteOrder method * will fail and throw a IllegalArgumentException exception * if the method was called after {@link * com.sleepycat.db.Db#open Db.open} was called; or if an * invalid flag value or parameter was specified. */ public void setByteOrder(int lorder) throws DbException { db_javaJNI.Db_set_lorder(swigCPtr, lorder); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #setPageSize(long)} */ public void set_pagesize(long pagesize) throws DbException { setPageSize(pagesize); } /** * Set the size of the pages used to hold items in the database, * in bytes. The minimum page size is 512 bytes, the maximum page * size is 64K bytes, and the page size must be a power-of-two. * If the page size is not explicitly set, one is selected based * on the underlying filesystem I/O block size. The automatically * selected size has a lower limit of 512 bytes and an upper * limit of 16K bytes.* * 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 {@link * com.sleepycat.db.Db Db} handle.
* * The Db.setPageSize method may not be called after the {@link * com.sleepycat.db.Db#open Db.open} method is called. If the * database already exists when {@link com.sleepycat.db.Db#open * Db.open} is called, the information specified to * Db.setPageSize will be ignored.
If creating additional * databases in a file, the page size specified must be * consistent with the existing databases in the file or an error * will be returned. * * @param pagesize The pagesize * parameter sets the database page size. * @throws IllegalArgumentException The Db.setPageSize method * will fail and throw a IllegalArgumentException exception * if the method was called after {@link * com.sleepycat.db.Db#open Db.open} was called; or if an * invalid flag value or parameter was specified. */ public void setPageSize(long pagesize) throws DbException { db_javaJNI.Db_set_pagesize(swigCPtr, pagesize); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #setRecordDelimiter(int)} */ public void set_re_delim(int re_delim) throws DbException { setRecordDelimiter(re_delim); } /** * Set the delimiting byte used to mark the end of a record in * the backing source file for the Recno access method.* * 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 {@link * com.sleepycat.db.Db Db} handle.
* * The Db.setRecordDelimiter method may not be called after the * {@link com.sleepycat.db.Db#open Db.open} method is called. If * the database already exists when {@link * com.sleepycat.db.Db#open Db.open} is called, the information * specified to Db.setRecordDelimiter will be ignored.
* * @param re_delim the delimiting byte used to * mark the end of a record. * @throws IllegalArgumentException The Db.setRecordDelimiter * method will fail and throw a IllegalArgumentException * exception if the method was called after {@link * com.sleepycat.db.Db#open Db.open} was called; or if an * invalid flag value or parameter was specified. */ public void setRecordDelimiter(int re_delim) throws DbException { db_javaJNI.Db_set_re_delim(swigCPtr, re_delim); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #setRecordLength(int)} */ public void set_re_len(int re_len) throws DbException { setRecordLength(re_len); } /** * For the Queue access method, specify that the records are of * length re_len . For the Queue access method, the record * length must be enough smaller than the database's page size * that at least one record plus the database page's metadata * information can fit on each database page.* * 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 {@link * com.sleepycat.db.Db#setRecordPad 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 {@link * com.sleepycat.db.Db Db} handle.
* * The Db.setRecordLength method may not be called after the * {@link com.sleepycat.db.Db#open Db.open} method is called. If * the database already exists when {@link * com.sleepycat.db.Db#open Db.open} is called, the information * specified to Db.setRecordLength will be ignored.
* * @param re_len the length of a Queue or * Recno database record, in bytes. * @throws IllegalArgumentException The Db.setRecordLength * method will fail and throw a IllegalArgumentException * exception if the method was called after {@link * com.sleepycat.db.Db#open Db.open} was called; or if an * invalid flag value or parameter was specified. */ public void setRecordLength(int re_len) throws DbException { db_javaJNI.Db_set_re_len(swigCPtr, re_len); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #setRecordPad(int)} */ public void set_re_pad(int re_pad) throws DbException { setRecordPad(re_pad); } /** * Set the padding character for short, fixed-length records for * the Queue and Recno access methods.* * 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 {@link * com.sleepycat.db.Db Db} handle.
* * The Db.setRecordPad method may not be called after the {@link * com.sleepycat.db.Db#open Db.open} method is called. If the * database already exists when {@link com.sleepycat.db.Db#open * Db.open} is called, the information specified to * Db.setRecordPad will be ignored.
* * @param re_pad the pad character for * fixed-length records for the Queue and Recno access * methods. * @throws IllegalArgumentException The Db.setRecordPad method * will fail and throw a IllegalArgumentException exception * if the method was called after {@link * com.sleepycat.db.Db#open Db.open} was called; or if an * invalid flag value or parameter was specified. */ public void setRecordPad(int re_pad) throws DbException { db_javaJNI.Db_set_re_pad(swigCPtr, re_pad); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #setRecordSource(String)} */ public void set_re_source(String source) throws DbException { setRecordSource(source); } /** * Set the underlying source file for the Recno access method. * The purpose of the source value is to provide fast * access and modification to databases that are normally stored * as flat text files.* * 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 {@link * com.sleepycat.db.Db#setRecordDelimiter 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 {@link * com.sleepycat.db.Db#close Db.close} or {@link * com.sleepycat.db.Db#sync 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 {@link * com.sleepycat.db.Db#open Db.open} call. See the {@link * com.sleepycat.db.Db#DB_SNAPSHOT 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 {@link com.sleepycat.db.Db#open 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 {@link * com.sleepycat.db.Db#sync Db.sync} or {@link * com.sleepycat.db.Db#close Db.close} methods will fail, of * course. Specify the {@link com.sleepycat.db.Db#DB_NOSYNC * Db.DB_NOSYNC} flag to the {@link com.sleepycat.db.Db#close * 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 {@link com.sleepycat.db.Db Db} handle, not * all operations performed on the underlying database.
* * The Db.setRecordSource method may not be called after the * {@link com.sleepycat.db.Db#open Db.open} method is called. If * the database already exists when {@link * com.sleepycat.db.Db#open 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.
* * @param source The backing flat text * database file for a Recno database. * @throws IllegalArgumentException The Db.setRecordSource * method will fail and throw a IllegalArgumentException * exception if the method was called after {@link * com.sleepycat.db.Db#open Db.open} was called; or if an * invalid flag value or parameter was specified. */ public void setRecordSource(String source) throws DbException { db_javaJNI.Db_set_re_source(swigCPtr, source); } /** * @deprecated As of Berkeley DB 4.2, replaced by {@link * #setQueueExtentSize(int)} */ public void set_q_extentsize(int extentsize) throws DbException { setQueueExtentSize(extentsize); } /** * Set the size of the extents used to hold pages in a Queue * database, specified as a number of pages. Each extent is * created as a separate physical file. If no extent size is set, * the default behavior is to create only a single underlying * database file.* * 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 {@link * com.sleepycat.db.Db Db} handle.
* * The Db.setQueueExtentSize method may not be called after the * {@link com.sleepycat.db.Db#open Db.open} method is called. If * the database already exists when {@link * com.sleepycat.db.Db#open Db.open} is called, the information * specified to Db.setQueueExtentSize will be ignored.
* * @param extentsize the number of pages in a * Queue database extent. * @throws IllegalArgumentException The Db.setQueueExtentSize * method will fail and throw a IllegalArgumentException * exception if the method was called after {@link * com.sleepycat.db.Db#open Db.open} was called; or if an * invalid flag value or parameter was specified. */ public void setQueueExtentSize(int extentsize) throws DbException { db_javaJNI.Db_set_q_extentsize(swigCPtr, extentsize); } /** * The Db.stat method creates a statistical structure and fills * it with statistics for the database.* * 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. * * @param flags must be set to 0 or one of * the following values: ** * 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 {@link com.sleepycat.db.Db#DB_RECNUM Db.DB_RECNUM
* } 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.
* * 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 {@link com.sleepycat.db.Db#close * Db.close}, atomically replace the original database with the * updated copy.
* * @param flags currently unused, and must * be set to 0. * @throws DbException The Db.sync method may fail * and throw {@link com.sleepycat.db.DbException * DbException}, encapsulating one of the following non-zero * errors: * @throws IllegalArgumentException The Db.sync method will fail * and throw a IllegalArgumentException exception if an * invalid flag value or parameter was specified. */ public void sync(int flags) throws DbException { db_javaJNI.Db_sync(swigCPtr, flags); } /** * The Db.truncate method empties the database, discarding all * records it contains. The number of records discarded from the * database is returned.* * It is an error to call the Db.truncate method on a database * with open cursors.
* * @param flags must be set to 0 or the * following value: ** * 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.
* * 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 {@link com.sleepycat.db.DbEnv#setDataDir * DbEnv.setDataDir} method, or by setting the "set_data_dir" * string in the environment's DB_CONFIG file.
* * @param file the physical file containing * the databases to be upgraded. * @param flags must be set to 0 or the * following value: ** * 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.