com.sleepycat.db
Class Database

java.lang.Object
  com.sleepycat.db.Database

Direct Known Subclasses:

SecondaryDatabase

public class Database
extends Object

Creates a database handle for a single Berkeley DB database. A Berkeley DB database provides a mechanism for organizing key-data pairs of information. From the perspective of some database systems, a Berkeley DB database could be thought of as a single table within a larger database.

For most database activities, you must open the handle using the open method. When you are done with them, handles must be closed using the close method.

It is possible to create databases such that they are organized within a database environment. Environments are optional for simple Berkeley DB applications that do not use transactions, recovery, replication or any other advanced features. For simple Berkeley DB applications, environments still offer some advantages. For example, they provide some organizational benefits on-disk (all databases are located on disk relative to the environment). Also, if you are using multiple databases, then environments allow your databases to share a common in-memory cache, which makes for more efficient usage of your hardware's resources. See Environment for information on using database environments.

Database handles are free-threaded unless opened in an environment that is not free-threaded.

Database attributes are specified in the DatabaseConfig class.

To open an existing database with default attributes:

    Environment env = new Environment(home, null);
    Database myDatabase = env.openDatabase(null, "mydatabase", null);

To create a transactional database that supports duplicates:

    DatabaseConfig dbConfig = new DatabaseConfig();
    dbConfig.setTransactional(true);
    dbConfig.setAllowCreate(true);
    dbConfig.setSortedDuplicates(true);
    Database newlyCreateDb = env.openDatabase(txn, "mydatabase", dbConfig);

Constructor Summary

Database(String filename, String databaseName, DatabaseConfig config)
Open a database.

Method Summary

OperationStatus	append(Transaction txn, DatabaseEntry key, DatabaseEntry data) Append the key/data pair to the end of the database.
void	close() Flush any cached database information to disk, close any open cursors, free allocated resources, close underlying files, and discard the database handle.
void	close(boolean noSync) Flush any cached database information to disk, close any open cursors, free allocated resources, close underlying files, and discard the database handle.
CompactStats	compact(Transaction txn, DatabaseEntry start, DatabaseEntry stop, DatabaseEntry end, CompactConfig config) Compact a Btree or Recno database or returns unused Btree, Hash or Recno database pages to the underlying filesystem.
OperationStatus	consume(Transaction txn, DatabaseEntry key, DatabaseEntry data, boolean wait) Return the record number and data from the available record closest to the head of the queue, and delete the record.
OperationStatus	delete(Transaction txn, DatabaseEntry key) Remove key/data pairs from the database.
OperationStatus	deleteMultiple(Transaction txn, MultipleEntry keys) Remove key/data pairs from the database.
OperationStatus	exists(Transaction txn, DatabaseEntry key) Checks if the specified key appears in the database.
OperationStatus	get(Transaction txn, DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Retrieves the key/data pair with the given key from the database.
CacheFile	getCacheFile() Return the handle for the cache file underlying the database.
DatabaseConfig	getConfig() Return this Database object's configuration.
String	getDatabaseFile() Return the database's underlying file name.
String	getDatabaseName() Return the database name.
Environment	getEnvironment() Return the Environment handle for the database environment underlying the Database.
KeyRange	getKeyRange(Transaction txn, DatabaseEntry key) Return an estimate of the proportion of keys in the database less than, equal to, and greater than the specified key.
OperationStatus	getSearchBoth(Transaction txn, DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Retrieves the key/data pair with the given key and data value, that is, both the key and data items must match.
OperationStatus	getSearchRecordNumber(Transaction txn, DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Retrieves the key/data pair associated with the specific numbered record of the database.
DatabaseStats	getStats(Transaction txn, StatsConfig config) Return database statistics.
JoinCursor	join(Cursor[] cursors, JoinConfig config) Creates a specialized join cursor for use in performing equality or natural joins on secondary indices.
Cursor	openCursor(Transaction txn, CursorConfig config) Return a cursor into the database.
Sequence	openSequence(Transaction txn, DatabaseEntry key, SequenceConfig config) Open a sequence represented by the key in the database.
OperationStatus	put(Transaction txn, DatabaseEntry key, DatabaseEntry data) Store the key/data pair into the database.
OperationStatus	putMultiple(Transaction txn, MultipleEntry key, MultipleEntry data, boolean overwrite) Store a set of key/data pairs into the database.
OperationStatus	putMultipleKey(Transaction txn, MultipleEntry key, boolean overwrite) Store a set of key/data pairs into the database.
OperationStatus	putNoDupData(Transaction txn, DatabaseEntry key, DatabaseEntry data) Store the key/data pair into the database if it does not already appear in the database.
OperationStatus	putNoOverwrite(Transaction txn, DatabaseEntry key, DatabaseEntry data) Store the key/data pair into the database if the key does not already appear in the database.
static void	remove(String fileName, String databaseName, DatabaseConfig config) Remove the database specified by the file and database parameters.
void	removeSequence(Transaction txn, DatabaseEntry key, SequenceConfig config) Remove the sequence from the database.
static void	rename(String fileName, String oldDatabaseName, String newDatabaseName, DatabaseConfig config) Rename a database specified by the file and database parameters.
void	setConfig(DatabaseConfig config) Change the settings in an existing database handle.
static void	sortMultipleKeyAndData(MultipleDataEntry keys, MultipleDataEntry datas) Sorts two DatabaseEntry objects with multiple key and data pairs.
static void	sortMultipleKeyData(MultipleKeyDataEntry entries) Sorts a DatabaseEntry with multiple matching key/data pairs.
static void	sortMultipleKeyOrData(MultipleDataEntry entries) Sorts a DatabaseEntry with multiple key or data pairs.
void	sync() Flush any cached information to disk.
int	truncate(Transaction txn, boolean countRecords) Empty the database, discarding all records it contains.
static void	upgrade(String fileName, DatabaseConfig config) Upgrade all of the databases included in the specified file.
static boolean	verify(String fileName, String databaseName, PrintStream dumpStream, VerifyConfig verifyConfig, DatabaseConfig dbConfig) Return if all of the databases in a file are uncorrupted.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Database

public Database(String filename,
                String databaseName,
                DatabaseConfig config)
         throws DatabaseException,
                FileNotFoundException

Open a database.

The database is represented by the file and database parameters.

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

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

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

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

Parameters:

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

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

config - The database open attributes. If null, default attributes are used.

Throws:

DatabaseException

FileNotFoundException

Method Detail

close

public void close(boolean noSync)
           throws DatabaseException

Flush any cached database information to disk, close any open cursors, free allocated resources, close underlying files, and discard the database handle.

Although closing a database handle will close any open cursors, it is recommended that applications explicitly close all their Cursor handles before closing the database. The reason why is that when the cursor is explicitly closed, the memory allocated for it is reclaimed; however, this will not happen if you close a database while cursors are still open. The same rule, for the same reasons, hold true for Transaction handles. Make sure you close all your transaction handles before closing your database handle.

Because key/data pairs are cached in memory, failing to sync the file with the Database.close or Database.sync methods may result in inconsistent or lost information. So, to ensure that any data cached in main memory are reflected in the underlying file system, applications should make a point to always either close database handles or sync their data to disk.

When multiple threads are using the Database handle concurrently, only a single thread may call this method.

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

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. If you do not close the database handle explicitly, it will be closed when the environment handle that owns the database handle is closed.

Parameters:

noSync - Do not flush cached information to disk. The noSync parameter 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 this method, atomically replace the original database with the updated copy.

Note that this flag only works when the database has been opened using an environment.

Throws:

DatabaseException - if a failure occurs.

close

public void close()
           throws DatabaseException

Flush any cached database information to disk, close any open cursors, free allocated resources, close underlying files, and discard the database handle.

Although closing a database handle will close any open cursors, it is recommended that applications explicitly close all their Cursor handles before closing the database. The reason why is that when the cursor is explicitly closed, the memory allocated for it is reclaimed; however, this will not happen if you close a database while cursors are still open. The same rule, for the same reasons, hold true for Transaction handles. Make sure you close all your transaction handles before closing your database handle.

Because key/data pairs are cached in memory, failing to sync the file with the Database.close or Database.sync methods may result in inconsistent or lost information. So, to ensure that any data cached in main memory are reflected in the underlying file system, applications should make a point to always either close database handles or sync their data to disk.

When multiple threads are using the Database handle concurrently, only a single thread may call this method.

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

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. If you do not close the database handle explicitly, it will be closed when the environment handle that owns the database handle is closed.

Throws:

DatabaseException - if a failure occurs.

compact

public CompactStats compact(Transaction txn,
                            DatabaseEntry start,
                            DatabaseEntry stop,
                            DatabaseEntry end,
                            CompactConfig config)
                     throws DatabaseException

Compact a Btree or Recno database or returns unused Btree, Hash or Recno database pages to the underlying filesystem.

Parameters:

txn - If the operation is part of an application-specified transaction, the txnid parameter is a transaction handle returned from Environment.beginTransaction(com.sleepycat.db.Transaction, com.sleepycat.db.TransactionConfig), otherwise NULL.

If a transaction handle is supplied to this method, then the operation is performed using that transaction. In this event, large sections of the tree may be locked during the course of the transaction.

If no transaction handle is specified, but the operation occurs in a transactional database, the operation will be implicitly transaction protected using multiple transactions. These transactions will be periodically committed to avoid locking large sections of the tree. Any deadlocks encountered cause the compaction operation to be retried from the point of the last transaction commit.

start - If not null, the start parameter is the starting point for compaction in a Btree or Recno database. Compaction will start at the smallest key greater than or equal to the specified key. If null, compaction will start at the beginning of the database.

stop - If not null, the stop parameter is the stopping point for compaction in a Btree or Recno database. Compaction will stop at the page with the smallest key greater than the specified key. If null, compaction will stop at the end of the database.

end - If not null, the end parameter will be filled in with the key marking the end of the compaction operation in a Btree or Recno database. It is generally the first key of the page where processing stopped.

config - The compaction operation attributes. If null, default attributes are used.

Throws:

DatabaseException

openCursor

public Cursor openCursor(Transaction txn,
                         CursorConfig config)
                  throws DatabaseException

Return a cursor into the database.

Parameters:

txn - To use a cursor for writing to a transactional database, an explicit transaction must be specified. For read-only access to a transactional database, the transaction may be null. For a non-transactional database, the transaction must be null.

To transaction-protect cursor operations, cursors must be opened and closed within the context of a transaction, and the txn parameter specifies the transaction context in which the cursor will be used.

config - The cursor attributes. If null, default attributes are used.

Returns:

A database cursor.

Throws:

DatabaseException - if a failure occurs.

openSequence

public Sequence openSequence(Transaction txn,
                             DatabaseEntry key,
                             SequenceConfig config)
                      throws DatabaseException

Open a sequence represented by the key in the database.

Parameters:

txn - For a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit. For a non-transactional database, null must be specified. If no transaction handle is specified, but the operation occurs in a transactional database, the operation will be implicitly transaction protected.

key - The key DatabaseEntry of the sequence. It specifies which record in the database stores the persistent sequence data.

config - The sequence attributes. If null, default attributes are used.

Returns:

A sequence handle.

Throws:

DatabaseException - if a failure occurs.

removeSequence

public void removeSequence(Transaction txn,
                           DatabaseEntry key,
                           SequenceConfig config)
                    throws DatabaseException

Remove the sequence from the database. This method should not be called if there are open handles on this sequence.

Parameters:

txn - For a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit. For a non-transactional database, null must be specified. If no transaction handle is specified, but the operation occurs in a transactional database, the operation will be implicitly transaction protected.

key - The key DatabaseEntry of the sequence. It specifies which record in the database stores the persistent sequence data.

config - The sequence attributes. If null, default attributes are used.

Throws:

DatabaseException

getDatabaseFile

public String getDatabaseFile()
                       throws DatabaseException

Return the database's underlying file name.

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

Returns:

The database's underlying file name.

Throws:

DatabaseException

getDatabaseName

public String getDatabaseName()
                       throws DatabaseException

Return the database name.

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

Returns:

The database name.

Throws:

DatabaseException

getConfig

public DatabaseConfig getConfig()
                         throws DatabaseException

Return this Database object's configuration.

This may differ from the configuration used to open this object if the database existed previously.

Returns:

This Database object's configuration.

Throws:

DatabaseException - if a failure occurs.

setConfig

public void setConfig(DatabaseConfig config)
               throws DatabaseException

Change the settings in an existing database handle.

Parameters:

config - The environment attributes. If null, default attributes are used.

Throws:

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

getEnvironment

public Environment getEnvironment()
                           throws DatabaseException

Return the Environment handle for the database environment underlying the Database.

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

Returns:

The Environment handle for the database environment underlying the Database.

Throws:

DatabaseException - if a failure occurs.

getCacheFile

public CacheFile getCacheFile()
                       throws DatabaseException

Return the handle for the cache file underlying the database.

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

Returns:

The handle for the cache file underlying the database.

Throws:

DatabaseException - if a failure occurs.

append

public OperationStatus append(Transaction txn,
                              DatabaseEntry key,
                              DatabaseEntry data)
                       throws DatabaseException

Append the key/data pair to the end of the database.

The underlying database must be a Queue or Recno database. The record number allocated to the record is returned in the key parameter.

There is a minor behavioral difference between the Recno and Queue access methods this method. If a transaction enclosing this method aborts, the record number may be decremented (and later reallocated by a subsequent operation) in the Recno access method, but will not be decremented or reallocated in the Queue access method.

It may be useful to modify the stored data based on the generated key. If a callback function is specified using DatabaseConfig.setRecordNumberAppender, it will be called after the record number has been selected, but before the data has been stored.

Parameters:

txn - For a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit. For a non-transactional database, null must be specified.

key - the key DatabaseEntry operated on.

data - the data DatabaseEntry stored.

Throws:

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

DatabaseException - if a failure occurs.

consume

public OperationStatus consume(Transaction txn,
                               DatabaseEntry key,
                               DatabaseEntry data,
                               boolean wait)
                        throws DatabaseException

Return the record number and data from the available record closest to the head of the queue, and delete the record. The record number will be returned in the key parameter, and 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 this method to be called.

Parameters:

txn - For a transactional database, an explicit transaction may be specified to transaction-protect the operation, or null may be specified to perform the operation without transaction protection. For a non-transactional database, null must be specified.

key - the key returned as output. Its byte array does not need to be initialized by the caller.

data - the data returned as output. Its byte array does not need to be initialized by the caller.

wait - if there is no record available, this parameter determines whether the method waits for one to become available, or returns immediately with status NOTFOUND.

Returns:

OperationStatus.NOTFOUND if no matching key/data pair is found; OperationStatus.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; otherwise, OperationStatus.SUCCESS.

Throws:

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

delete

public OperationStatus delete(Transaction txn,
                              DatabaseEntry key)
                       throws DatabaseException

Remove key/data pairs from the database.

The key/data pair associated with the specified key is discarded from the database. In the presence of duplicate key values, all records associated with the designated key will be discarded.

The key/data pair is also deleted from any associated secondary databases. When called on a database that has been made into a secondary index, this method deletes the key/data pair from the primary database and all secondary indices.

Parameters:

txn - If the operation is part of an application-specified transaction, the txn parameter is a Transaction object returned from the Environment.beginTransaction method; if the operation is part of a Berkeley DB Concurrent Data Store group, the txn parameter is a Transaction object returned from the Environment.beginCDSGroup method; otherwise null. For a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit. For a non-transactional database, null must be specified. If no transaction handle is specified, but the operation occurs in a transactional database, the operation will be implicitly transaction protected.

key - the key DatabaseEntry operated on.

Returns:

The method will return OperationStatus.NOTFOUND if the specified key is not found in the database; The method will return OperationStatus.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; otherwise the method will return OperationStatus.SUCCESS.

Throws:

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

DatabaseException - if a failure occurs.

deleteMultiple

public OperationStatus deleteMultiple(Transaction txn,
                                      MultipleEntry keys)
                               throws DatabaseException

Remove key/data pairs from the database.

The key/data pair associated with the specified key is discarded from the database. In the presence of duplicate key values, all records associated with the designated key will be discarded.

The key/data pair is also deleted from any associated secondary databases. When called on a database that has been made into a secondary index, this method deletes the key/data pair from the primary database and all secondary indices.

Parameters:

txn - If the operation is part of an application-specified transaction, the txn parameter is a Transaction object returned from the Environment.beginTransaction method; if the operation is part of a Berkeley DB Concurrent Data Store group, the txn parameter is a Transaction object returned from the Environment.beginCDSGroup method; otherwise null. For a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit. For a non-transactional database, null must be specified. If no transaction handle is specified, but the operation occurs in a transactional database, the operation will be implicitly transaction protected.

keys - the set of keys DatabaseEntry operated on.

Returns:

The method will return OperationStatus.NOTFOUND if the specified key is not found in the database; The method will return OperationStatus.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; otherwise the method will return OperationStatus.SUCCESS.

Throws:

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

DatabaseException - if a failure occurs.

exists

public OperationStatus exists(Transaction txn,
                              DatabaseEntry key)
                       throws DatabaseException

Checks if the specified key appears in the database.

Parameters:

txn - If the operation is part of an application-specified transaction, the txn parameter is a Transaction object returned from the Environment.beginTransaction method; if the operation is part of a Berkeley DB Concurrent Data Store group, the txn parameter is a Transaction object returned from the Environment.beginCDSGroup method; otherwise null. For a transactional database, an explicit transaction may be specified to transaction-protect the operation, or null may be specified to perform the operation without transaction protection. For a non-transactional database, null must be specified. If no transaction handle is specified, but the operation occurs in a transactional database, the operation will be implicitly transaction protected.

key - the key used as input. It must be initialized with a non-null byte array by the caller.

Returns:

OperationStatus.NOTFOUND if no matching key/data pair is found; OperationStatus.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; otherwise, OperationStatus.SUCCESS.

Throws:

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

get

public OperationStatus get(Transaction txn,
                           DatabaseEntry key,
                           DatabaseEntry data,
                           LockMode lockMode)
                    throws DatabaseException

Retrieves the key/data pair with the given key from the database. If the matching key has duplicate values, the first data item in the set of duplicates is returned.

Duplicates are sorted by:

• their sort order, if a duplicate sort function was specified.
• any explicit cursor designated insertion.
• by insert order. This is the default behavior.

Retrieval of duplicates requires the use of Cursor operations. When called on a database that has been made into a secondary index, this method returns the key from the secondary index and the data item from the primary database.

Parameters:

txn - If the operation is part of an application-specified transaction, the txn parameter is a Transaction object returned from the Environment.beginTransaction method; if the operation is part of a Berkeley DB Concurrent Data Store group, the txn parameter is a Transaction object returned from the Environment.beginCDSGroup method; otherwise null. For a transactional database, an explicit transaction may be specified to transaction-protect the operation, or null may be specified to perform the operation without transaction protection. For a non-transactional database, null must be specified. If no transaction handle is specified, but the operation occurs in a transactional database, the operation will be implicitly transaction protected.

key - the key used as input. It must be initialized with a non-null byte array by the caller.

data - the data returned as output. Its byte array does not need to be initialized by the caller.

lockMode - the locking attributes; if null, default attributes are used.

Returns:

OperationStatus.NOTFOUND if no matching key/data pair is found; OperationStatus.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; otherwise, OperationStatus.SUCCESS.

Throws:

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

getKeyRange

public KeyRange getKeyRange(Transaction txn,
                            DatabaseEntry key)
                     throws DatabaseException

Return an estimate of the proportion of keys in the database less than, equal to, and greater than the specified key.

The underlying database must be of type Btree.

This method does not retain the locks it acquires for the life of the transaction, so estimates are not repeatable.

Parameters:

key - The key DatabaseEntry being compared.

txn - If the operation is part of an application-specified transaction, the txn parameter is a Transaction object returned from the Environment.beginTransaction method; if the operation is part of a Berkeley DB Concurrent Data Store group, the txn parameter is a Transaction object returned from the Environment.beginCDSGroup method; otherwise null. For a transactional database, an explicit transaction may be specified to transaction-protect the operation, or null may be specified to perform the operation without transaction protection. For a non-transactional database, null must be specified. If no transaction handle is specified, but the operation occurs in a transactional database, the operation will be implicitly transaction protected.

Returns:

An estimate of the proportion of keys in the database less than, equal to, and greater than the specified key.

Throws:

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

DatabaseException - if a failure occurs.

getSearchBoth

public OperationStatus getSearchBoth(Transaction txn,
                                     DatabaseEntry key,
                                     DatabaseEntry data,
                                     LockMode lockMode)
                              throws DatabaseException

Retrieves the key/data pair with the given key and data value, that is, both the key and data items must match.

Parameters:

txn - For a transactional database, an explicit transaction may be specified to transaction-protect the operation, or null may be specified to perform the operation without transaction protection. For a non-transactional database, null must be specified.

key - the key used as input. It must be initialized with a non-null byte array by the caller.

data - the data used as input. It must be initialized with a non-null byte array by the caller.

lockMode - the locking attributes; if null, default attributes are used.

Returns:

OperationStatus.NOTFOUND if no matching key/data pair is found; OperationStatus.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; otherwise, OperationStatus.SUCCESS.

Throws:

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

getSearchRecordNumber

public OperationStatus getSearchRecordNumber(Transaction txn,
                                             DatabaseEntry key,
                                             DatabaseEntry data,
                                             LockMode lockMode)
                                      throws DatabaseException

Retrieves the key/data pair associated with the specific numbered record of the database.

The data field of the specified key must be a byte array containing a record number, as described in DatabaseEntry. This determines the record to be retrieved.

For this method to be called, the underlying database must be of type Btree, and it must have been configured to support record numbers.

If this method fails for any reason, the position of the cursor will be unchanged.

Parameters:

key - the key returned as output. Its byte array does not need to be initialized by the caller.

data - the data returned as output. Multiple results can be retrieved by passing an object that is a subclass of MultipleEntry, otherwise its byte array does not need to be initialized by the caller.

lockMode - the locking attributes; if null, default attributes are used.

Returns:

OperationStatus.NOTFOUND if no matching key/data pair is found; OperationStatus.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; otherwise, OperationStatus.SUCCESS.

Throws:

NullPointerException - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

put

public OperationStatus put(Transaction txn,
                           DatabaseEntry key,
                           DatabaseEntry data)
                    throws DatabaseException

Store the key/data pair into the database.

If the key already appears in the database and duplicates are not configured, the existing key/data pair will be replaced. If the key already appears in the database and sorted duplicates are configured, the new data value is inserted at the correct sorted location. If the key already appears in the database and unsorted duplicates are configured, the new data value is appended at the end of the duplicate set.

Parameters:

txn - If the operation is part of an application-specified transaction, the txn parameter is a Transaction object returned from the Environment.beginTransaction method; if the operation is part of a Berkeley DB Concurrent Data Store group, the txn parameter is a Transaction object returned from the Environment.beginCDSGroup method; otherwise null. For a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit. For a non-transactional database, null must be specified. If no transaction handle is specified, but the operation occurs in a transactional database, the operation will be implicitly transaction protected.

key - the key DatabaseEntry operated on.

data - the data DatabaseEntry stored.

Throws:

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

DatabaseException - if a failure occurs.

putMultiple

public OperationStatus putMultiple(Transaction txn,
                                   MultipleEntry key,
                                   MultipleEntry data,
                                   boolean overwrite)
                            throws DatabaseException

Store a set of key/data pairs into the database.

The key and data parameters must contain corresponding key/data pairs. That is the first entry in the multiple key is inserted with the first entry from the data parameter. Similarly for all remaining keys in the set.

This method may not be called on databases configured with unsorted duplicates.

Parameters:

txn - If the operation is part of an application-specified transaction, the txn parameter is a Transaction object returned from the Environment.beginTransaction method; if the operation is part of a Berkeley DB Concurrent Data Store group, the txn parameter is a Transaction object returned from the Environment.beginCDSGroup method; otherwise null. For a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit. For a non-transactional database, null must be specified. If no transaction handle is specified, but the operation occurs in a transactional database, the operation will be implicitly transaction protected.

key - the set of keys MultipleEntry operated on.

data - the set of data MultipleEntry stored.

overwrite - if this flag is true and any of the keys already exist in the database, they will be replaced. Otherwise a KEYEXIST error will be returned.

Returns:

If any of the key/data pairs already appear in the database, this method will return OperationStatus.KEYEXIST.

Throws:

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

DatabaseException - if a failure occurs.

putMultipleKey

public OperationStatus putMultipleKey(Transaction txn,
                                      MultipleEntry key,
                                      boolean overwrite)
                               throws DatabaseException

Store a set of key/data pairs into the database.

This method may not be called on databases configured with unsorted duplicates.

Parameters:

txn - If the operation is part of an application-specified transaction, the txn parameter is a Transaction object returned from the Environment.beginTransaction method; if the operation is part of a Berkeley DB Concurrent Data Store group, the txn parameter is a Transaction object returned from the Environment.beginCDSGroup method; otherwise null. For a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit. For a non-transactional database, null must be specified. If no transaction handle is specified, but the operation occurs in a transactional database, the operation will be implicitly transaction protected.

key - the key and data sets MultipleEntry operated on.

overwrite - if this flag is true and any of the keys already exist in the database, they will be replaced. Otherwise a KEYEXIST error will be returned.

Returns:

If any of the key/data pairs already appear in the database, this method will return OperationStatus.KEYEXIST.

Throws:

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

DatabaseException - if a failure occurs.

putNoDupData

public OperationStatus putNoDupData(Transaction txn,
                                    DatabaseEntry key,
                                    DatabaseEntry data)
                             throws DatabaseException

Store the key/data pair into the database if it does not already appear in the database.

This method may only be called if the underlying database has been configured to support sorted duplicates. (This method may not be specified to the Queue or Recno access methods.)

Parameters:

txn - If the operation is part of an application-specified transaction, the txn parameter is a Transaction object returned from the Environment.beginTransaction method; if the operation is part of a Berkeley DB Concurrent Data Store group, the txn parameter is a Transaction object returned from the Environment.beginCDSGroup method; otherwise null. For a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit. For a non-transactional database, null must be specified. If no transaction handle is specified, but the operation occurs in a transactional database, the operation will be implicitly transaction protected.

key - the key DatabaseEntry operated on.

data - the data DatabaseEntry stored.

Returns:

If the key/data pair already appears in the database, this method will return OperationStatus.KEYEXIST.

Throws:

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

DatabaseException - if a failure occurs.

putNoOverwrite

public OperationStatus putNoOverwrite(Transaction txn,
                                      DatabaseEntry key,
                                      DatabaseEntry data)
                               throws DatabaseException

Store the key/data pair into the database if the key does not already appear in the database.

This method will fail if the key already exists in the database, even if the database supports duplicates.

Parameters:

txn - If the operation is part of an application-specified transaction, the txn parameter is a Transaction object returned from the Environment.beginTransaction method; if the operation is part of a Berkeley DB Concurrent Data Store group, the txn parameter is a Transaction object returned from the Environment.beginCDSGroup method; otherwise null. For a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit. For a non-transactional database, null must be specified. If no transaction handle is specified, but the operation occurs in a transactional database, the operation will be implicitly transaction protected.

key - the key DatabaseEntry operated on.

data - the data DatabaseEntry stored.

Returns:

If the key already appears in the database, this method will return OperationStatus.KEYEXIST.

Throws:

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

DatabaseException - if a failure occurs.

join

public JoinCursor join(Cursor[] cursors,
                       JoinConfig config)
                throws DatabaseException

Creates a specialized join cursor for use in performing equality or natural joins on secondary indices.

Each cursor in the cursors array must have been initialized to refer to the key on which the underlying database should be joined. Typically, this initialization is done by calling Cursor.getSearchKey.

Once the cursors have been passed to this method, they should not be accessed or modified until the newly created join cursor has been closed, or else inconsistent results may be returned. However, the position of the cursors will not be changed by this method or by the methods of the join cursor.

Parameters:

cursors - an array of cursors associated with this primary database.

config - The join attributes. If null, default attributes are used.

Returns:

a specialized cursor that returns the results of the equality join operation.

Throws:

DatabaseException - if a failure occurs.

See Also:

JoinCursor

truncate

public int truncate(Transaction txn,
                    boolean countRecords)
             throws DatabaseException

Empty the database, discarding all records it contains.

When called on a database configured with secondary indices, this method truncates the primary database and all secondary indices. If configured to return a count of the records discarded, the returned count is the count of records discarded from the primary database.

It is an error to call this method on a database with open cursors.

Parameters:

txn - For a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit. For a non-transactional database, null must be specified. If no transaction handle is specified, but the operation occurs in a transactional database, the operation will be implicitly transaction protected.

countRecords - If true, count and return the number of records discarded.

Returns:

The number of records discarded, or -1 if returnCount is false.

Throws:

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

DatabaseException - if a failure occurs.

getStats

public DatabaseStats getStats(Transaction txn,
                              StatsConfig config)
                       throws DatabaseException

Return database statistics.

If this method has not been configured to avoid expensive operations (using the StatsConfig.setFast method), it 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 this method may be out-of-date.

If the database was not opened read-only and this method was not configured using the StatsConfig.setFast method, cached key and record numbers will be updated after the statistical information has been gathered.

Parameters:

txn - If the operation is part of an application-specified transaction, the txn parameter is a Transaction object returned from the Environment.beginTransaction method; if the operation is part of a Berkeley DB Concurrent Data Store group, the txn parameter is a Transaction object returned from the Environment.beginCDSGroup method; otherwise null. For a transactional database, an explicit transaction may be specified to transaction-protect the operation, or null may be specified to perform the operation without transaction protection. For a non-transactional database, null must be specified. If no transaction handle is specified, but the operation occurs in a transactional database, the operation will be implicitly transaction protected.

config - The statistics returned; if null, default statistics are returned.

Returns:

Database statistics.

Throws:

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

DatabaseException - if a failure occurs.

remove

public static void remove(String fileName,
                          String databaseName,
                          DatabaseConfig config)
                   throws DatabaseException,
                          FileNotFoundException

Remove the database specified by the file and database parameters.

If no database is specified, the underlying file specified is removed, incidentally removing all of the databases it contained..

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

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. This method may not be called after calling the open method on any database handle. If the open method has already been called on a database handle, close the existing handle and create a new one before calling the remove method. This method should not be called if the remove is intended to be transactionally safe; the Environment.removeDatabase method should be used instead.

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

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

Parameters:

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

databaseName - The database to be removed.

config - The database remove attributes. If null, default attributes are used.

Throws:

DatabaseException - if a failure occurs.

FileNotFoundException

rename

public static void rename(String fileName,
                          String oldDatabaseName,
                          String newDatabaseName,
                          DatabaseConfig config)
                   throws DatabaseException,
                          FileNotFoundException

Rename a database specified by the file and database parameters.

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

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

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. This method should not be called if the rename is intended to be transactionally safe; the Environment.renameDatabase method should be used instead.

This method is affected by any database directory specified with EnvironmentConfig.addDataDir, or by setting the "set_data_dir" string in the database environment's DB_CONFIG file. This method may not be called after calling the open method on any database handle. If the open method has already been called on a database handle, close the existing handle and create a new one before calling the rename method.

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

Parameters:

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

oldDatabaseName - The database to be renamed.

newDatabaseName - The new name of the database or file.

config - The database rename attributes. If null, default attributes are used.

Throws:

DatabaseException - if a failure occurs.

FileNotFoundException

sortMultipleKeyData

public static void sortMultipleKeyData(MultipleKeyDataEntry entries)
                                throws DatabaseException

Sorts a DatabaseEntry with multiple matching key/data pairs.

If specified, the application specific btree comparison and duplicate comparison functions will be used.

Parameters:

entries - A MultipleKeyDataEntry that contains matching pairs of key/data items, the sorted entries will be returned in the original entries object.

Throws:

DatabaseException

sortMultipleKeyOrData

public static void sortMultipleKeyOrData(MultipleDataEntry entries)
                                  throws DatabaseException

Sorts a DatabaseEntry with multiple key or data pairs.

If specified, the application specific btree comparison function will be used.

Parameters:

entries - A MultipleDataEntry that contains multiple key or data items, the sorted entries will be returned in the original entries object.

Throws:

DatabaseException

sortMultipleKeyAndData

public static void sortMultipleKeyAndData(MultipleDataEntry keys,
                                          MultipleDataEntry datas)
                                   throws DatabaseException

Sorts two DatabaseEntry objects with multiple key and data pairs.

If specified, the application specific btree comparison and duplicate comparison functions will be used.

The key and data parameters must contain "pairs" of items. That is the n-th entry in keys corresponds to the n-th entry in datas.

Parameters:

keys - A MultipleDataEntry that contains multiple key items, the sorted entries will be returned in the original entries object.

datas - A MultipleDataEntry that contains multiple data items, the sorted entries will be returned in the original entries object.

Throws:

DatabaseException

sync

public void sync()
          throws DatabaseException

Flush any cached information to disk.

If the database is in memory only, this 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 closed the copy of the database, atomically replace the original database with the updated copy.

Throws:

DatabaseException - if a failure occurs.

upgrade

public static void upgrade(String fileName,
                           DatabaseConfig config)
                    throws DatabaseException,
                           FileNotFoundException

Upgrade all of the databases included in the specified file.

If no upgrade is necessary, always returns success.

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.

The following information 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. Configuring the database object to support sorted duplicates by the DatabaseConfig.setSortedDuplicates method informs this method that the duplicates are sorted; otherwise they are assumed to be unsorted. Incorrectly specifying this configuration information may lead to database corruption.

Further, because this method upgrades a physical file (including all the databases it contains), it is not possible to use this method 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), this method will work correctly as long as the duplicate configuration is correctly specified. Otherwise, the file cannot be upgraded using this method; it must be upgraded manually by dumping and reloading the databases.

Unlike all other database operations, upgrades 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.

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

Parameters:

fileName - The physical file containing the databases to be upgraded.

Throws:

DatabaseException - if a failure occurs.

FileNotFoundException

verify

public static boolean verify(String fileName,
                             String databaseName,
                             PrintStream dumpStream,
                             VerifyConfig verifyConfig,
                             DatabaseConfig dbConfig)
                      throws DatabaseException,
                             FileNotFoundException

Return if all of the databases in a file are uncorrupted.

This method optionally outputs the databases' key/data pairs to a file stream.

This method does not perform any locking, even in database environments 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.

This method may not be called after the database is opened.

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.

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

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

Parameters:

fileName - The physical file in which the databases to be verified are found.

databaseName - The database in the file on which the database checks for btree and duplicate sort order and for hashing are to be performed. This parameter should be set to null except when the operation has been been configured by VerifyConfig.setOrderCheckOnly.

dumpStream - An optional file stream to which the databases' key/data pairs are written. This parameter should be set to null except when the operation has been been configured by VerifyConfig.setSalvage.

verifyConfig - The verify operation attributes. If null, default attributes are used.

dbConfig - The database attributes. If null, default attributes are used.

Returns:

True, if all of the databases in the file are uncorrupted. If this method returns false, and the operation was configured by VerifyConfig.setSalvage, all of the key/data pairs in the file may not have been successfully output.

Throws:

DatabaseException - if a failure occurs.

FileNotFoundException