com.sleepycat.je
Class Database

java.lang.Object
  |
  +--com.sleepycat.je.Database

Direct Known Subclasses:

SecondaryDatabase

public class Database

extends Object

A database handle. Multiple database handles may access a single data store.

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, "foo", 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, "foo", dbConfig);
 

Method Summary

void	close() Flush any cached database information to disk and discard the database handle.
OperationStatus	delete(Transaction txn, DatabaseEntry key) Remove key/data pairs from the database.
OperationStatus	get(Transaction txn, DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Retrieves the key/data pair with the given key.
DatabaseConfig	getConfig() Return this object's configuration.
String	getDatabaseName() Return the database name.
Environment	getEnvironment() Return the Environment object used to create this Database.
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.
List	getSecondaryDatabases() Returns a list of all SecondaryDatabase objects associated with this primary database.
DatabaseStats	getStats(StatsConfig statsConfig) 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 cursorConfig) Return a cursor into the database.
void	preload(long maxBytes) Preload the cache.
OperationStatus	put(Transaction txn, DatabaseEntry key, DatabaseEntry data) Store key/data pairs into the database.
OperationStatus	putNoDupData(Transaction txn, DatabaseEntry key, DatabaseEntry data) Store key/data pairs into the database.
OperationStatus	putNoOverwrite(Transaction txn, DatabaseEntry key, DatabaseEntry data) Store key/data pairs into the database.
int	truncate(Transaction txn, boolean returnCount) Empty the database, discarding all records it contains.
boolean	verify(VerifyConfig config, PrintStream out) Verify the integrity of the database.

Methods inherited from class java.lang.Object

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

Method Detail

close

public void close()
           throws DatabaseException

Flush any cached database information to disk and discard the database handle.

The database handle should not be closed while any other handle that refers to it is not yet closed; for example, database handles should 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 Cursor and Transaction handles.

Because key/data pairs are cached in memory, failing to sync the system with Database.close or Environment.sync method may result in inconsistent or lost information.

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

The database handle may not be accessed again after Database.close is called.

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.

Throws:

DatabaseException - if a failure occurs.

openCursor

public Cursor openCursor(Transaction txn,
                         CursorConfig cursorConfig)
                  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.

cursorConfig - The cursorConfig parameter specifies the cursor attributes; if null, default attributes are used.

Returns:

A database cursor.

Throws:

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.

The key/data pair is also deleted from any associated secondary databases.

In the presence of duplicate key values, all records associated with the designated key will be discarded.

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.

Returns:

The method will return NOTFOUND if the specified key is not found in the database; otherwise the method will return SUCCESS.

Throws:

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

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. If the matching key has duplicate values, the first data item in the set of duplicates is returned. Retrieval of duplicates requires the use of Cursor operations.

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 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:

NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.

Throws:

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

IllegalArgumentException - if an invalid parameter was specified.

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:

NOTFOUND if no matching key/data pair is found; otherwise, SUCCESS.

Throws:

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 key/data pairs into the database.

If the key already appears in the database and duplicates are supported, the new data value is inserted at the correct sorted location. If the key already appears in the database and duplicates are not supported, the existing key/data pair will be replaced.

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.

putNoOverwrite

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

Store key/data pairs into the database.

If the key already appears in the database, Database.putNoOverwrite will return KEYEXIST.

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.

Returns:

If the key already appears in the database, Database.putNoOverwrite will return 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 key/data pairs into the database.

If the key/data pair already appears in the database, Database.putNoDupData will return KEYEXIST.

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.

Returns:

If the key/data pair already appears in the database, Database.putNoDupData will return 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 config parameter specifies 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 returnCount)
             throws DatabaseException

Empty the database, discarding all records it contains.

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.

returnCount - whether to 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(StatsConfig statsConfig)
                       throws DatabaseException

Return database statistics.

Parameters:

statsConfig - The statsConfig parameter specifies 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.

preload

public void preload(long maxBytes)
             throws DatabaseException

Preload the cache.

Parameters:

maxBytes - The maximum number of bytes to load. If maxBytes is 0, je.evictor.maxMemory is used.

Throws:

DatabaseException - if a failure occurs.

verify

public boolean verify(VerifyConfig config,
                      PrintStream out)
               throws DatabaseException

Verify the integrity of the database.

This method does not perform any locking, even in database environments configured with a locking subsystem. As such, it should only be used on files that are not being modified by another thread of control.

Parameters:

config - The config parameter specifies the verify operation; if null, the default operation is performed.

out - Verification output goes into this stream.

Returns:

true if no error was found.

Throws:

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

getDatabaseName

public String getDatabaseName()
                       throws DatabaseException

Return the database name.

Returns:

The database name.

Throws:

DatabaseException - if a failure occurs.

getConfig

public DatabaseConfig getConfig()
                         throws DatabaseException

Return this object's configuration.

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

Returns:

This object's configuration.

Throws:

DatabaseException - if a failure occurs.

getEnvironment

public Environment getEnvironment()
                           throws DatabaseException

Return the Environment object used to create this Database.

Returns:

Return the Environment object used to create this Database.

Throws:

DatabaseException - if a failure occurs.

getSecondaryDatabases

public List getSecondaryDatabases()
                           throws DatabaseException

Returns a list of all SecondaryDatabase objects associated with this primary database. If no secondaries are associated or this is itself a secondary database, an empty list is returned.

Returns:

a list of associated SecondaryDatabase objects.

DatabaseException