com.sleepycat.je
Class SecondaryDatabase

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

public class SecondaryDatabase

extends Database

A secondary database handle.

Secondary databases are opened with Environment.openSecondaryDatabase and are always associated with a single primary database. The distinguishing characteristics of a secondary database are:

• Records are automatically added to a secondary database when records are added, modified and deleted in the primary database. Direct calls to put() methods on a secondary database are prohibited.
• The delete method of a secondary database will delete the primary record and as well as all its associated secondary records.
• Calls to all get() methods will return the data from the associated primary database.
• Additional get() method signatures are provided to return the primary key in an additional pKey parameter.
• Calls to openCursor will return a SecondaryCursor, which itself has get() methods that return the data of the primary database and additional get() method signatures for returning the primary key.
• The openSecondaryCursor method is provided to return a SecondaryCursor that doesn't require casting.

Before opening or creating a secondary database you must implement the SecondaryKeyCreator interface. For example:

   class MyKeyCreator implements SecondaryKeyCreator {
       public boolean createSecondaryKey(SecondaryDatabase secondary,
                                    DatabaseEntry key,
                                    DatabaseEntry data,
                                    DatabaseEntry result)
           throws DatabaseException {
           //
           // DO HERE: Extract the secondary key from the primary key and data,
           // and set the secondary key into the result parameter.
           //
           return true;
       }
   }
   

To create a secondary database that supports duplicates:

   Database primaryDb; // The primary database must already be open.
   SecondaryConfig secConfig = new SecondaryConfig();
   secConfig.setAllowCreate(true);
   secConfig.setSortedDuplicates(true);
   secConfig.setKeyCreator(new MyKeyCreator());
   SecondaryDatabase newDb = env.openSecondaryDatabase(txn, "foo",
                                                       primaryDb, secConfig)
   

Method Summary

void	close() Closes a secondary database and disassociates it from its primary database.
OperationStatus	delete(Transaction txn, DatabaseEntry key) Deletes the key/data pair from the associated primary database and all secondary indices.
OperationStatus	get(Transaction txn, DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode) Retrieves the key/data pair with the given key.
OperationStatus	get(Transaction txn, DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Retrieves the key/data pair with the given key.
Database	getPrimaryDatabase() Returns the primary database associated with this secondary database.
OperationStatus	getSearchBoth(Transaction txn, DatabaseEntry key, DatabaseEntry pKey, DatabaseEntry data, LockMode lockMode) Retrieves the key/data pair with the specified secondary and primary key, that is, both the primary and secondary key items must match.
OperationStatus	getSearchBoth(Transaction txn, DatabaseEntry key, DatabaseEntry data, LockMode lockMode) This operation is not allowed with this method signature.
SecondaryConfig	getSecondaryConfig() Returns a copy of the secondary configuration of this database.
JoinCursor	join(Cursor[] cursors, JoinConfig config) This operation is not allowed on a secondary database.
SecondaryCursor	openSecondaryCursor(Transaction txn, CursorConfig cursorConfig) Obtain a cursor on a database, returning a SecondaryCursor.
OperationStatus	put(Transaction txn, DatabaseEntry key, DatabaseEntry data) This operation is not allowed on a secondary database.
OperationStatus	putNoDupData(Transaction txn, DatabaseEntry key, DatabaseEntry data) This operation is not allowed on a secondary database.
OperationStatus	putNoOverwrite(Transaction txn, DatabaseEntry key, DatabaseEntry data) This operation is not allowed on a secondary database.
int	truncate(Transaction txn, boolean countRecords) This operation is not allowed on a secondary database.

Methods inherited from class com.sleepycat.je.Database

getConfig, getDatabaseName, getEnvironment, getSecondaryDatabases, getStats, openCursor, preload, verify

Methods inherited from class java.lang.Object

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

Method Detail

close

public void close()
           throws DatabaseException

Closes a secondary database and disassociates it from its primary database. A secondary database should be closed before closing its associated primary database.

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.

Overrides:

close in class Database

Throws:

DatabaseException - if a failure occurs.

getPrimaryDatabase

public Database getPrimaryDatabase()
                            throws DatabaseException

Returns the primary database associated with this secondary database.

Returns:

the primary database associated with this secondary database.

Throws:

DatabaseException - if a failure occurs.

getSecondaryConfig

public SecondaryConfig getSecondaryConfig()
                                   throws DatabaseException

Returns a copy of the secondary configuration of this database.

Returns:

a copy of the secondary configuration of this database.

Throws:

DatabaseException - if a failure occurs.

openSecondaryCursor

public SecondaryCursor openSecondaryCursor(Transaction txn,
                                           CursorConfig cursorConfig)
                                    throws DatabaseException

Obtain a cursor on a database, returning a SecondaryCursor. Calling this method is the equivalent of calling Database.openCursor(com.sleepycat.je.Transaction, com.sleepycat.je.CursorConfig) and casting the result to SecondaryCursor.

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 secondary database cursor.

Throws:

DatabaseException - if a failure occurs.

delete

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

Deletes the key/data pair from the associated primary database and all secondary indices.

This method behaves as if Database.delete(com.sleepycat.je.Transaction, com.sleepycat.je.DatabaseEntry) were called for the primary database, using the primary key obtained via the secondary key parameter.

Overrides:

delete in class 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.

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:

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.

Overrides:

get in class Database

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 secondary key used as input. It must be initialized with a non-null byte array by the caller.

data - the primary 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.

get

public OperationStatus get(Transaction txn,
                           DatabaseEntry key,
                           DatabaseEntry pKey,
                           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 secondary key used as input. It must be initialized with a non-null byte array by the caller.

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

data - the primary 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

This operation is not allowed with this method signature. UnsupportedOperationException will always be thrown by this method. The corresponding method with the pKey parameter should be used instead.

Overrides:

getSearchBoth in class Database

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:

DatabaseException - if a failure occurs.

getSearchBoth

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

Retrieves the key/data pair with the specified secondary and primary key, that is, both the primary and secondary key 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 secondary key used as input. It must be initialized with a non-null byte array by the caller.

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

data - the primary 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.

put

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

This operation is not allowed on a secondary database. UnsupportedOperationException will always be thrown by this method. The corresponding method on the primary database should be used instead.

Overrides:

put in class 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.

key - the key DatabaseEntry operated on.

data - the data DatabaseEntry stored.

Throws:

DatabaseException - if a failure occurs.

putNoOverwrite

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

This operation is not allowed on a secondary database. UnsupportedOperationException will always be thrown by this method. The corresponding method on the primary database should be used instead.

Overrides:

putNoOverwrite in class 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.

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:

DatabaseException - if a failure occurs.

putNoDupData

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

This operation is not allowed on a secondary database. UnsupportedOperationException will always be thrown by this method. The corresponding method on the primary database should be used instead.

Overrides:

putNoDupData in class 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.

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:

DatabaseException - if a failure occurs.

join

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

This operation is not allowed on a secondary database. UnsupportedOperationException will always be thrown by this method. The corresponding method on the primary database should be used instead.

Overrides:

join in class Database

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 countRecords)
             throws DatabaseException

This operation is not allowed on a secondary database. UnsupportedOperationException will always be thrown by this method. The corresponding method on the primary database should be used instead.

Overrides:

truncate in class 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.

countRecords - whether to count and return the number of records discarded.

Returns:

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

Throws:

DatabaseException - if a failure occurs.