com.sleepycat.client

Class SSecondaryDatabase

java.lang.Object

com.sleepycat.client.SDatabase

com.sleepycat.client.SSecondaryDatabase

All Implemented Interfaces:

GetHelper, PutHelper, TxnHelper, java.lang.AutoCloseable

public class SSecondaryDatabase
extends SDatabase

A secondary database handle.

Secondary databases are opened with SEnvironment.openSecondaryDatabase(com.sleepycat.client.STransaction, java.lang.String, java.lang.String, com.sleepycat.client.SDatabase, com.sleepycat.client.SSecondaryConfig) 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 SDatabase.delete(com.sleepycat.client.STransaction, com.sleepycat.client.SDatabaseEntry) 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(com.sleepycat.client.STransaction, com.sleepycat.client.SCursorConfig) will return a SSecondaryCursor, which itself has get() methods that return the data of the primary database and additional get() method signatures for returning the primary key.

Before opening or creating a secondary database you must implement the SSecondaryKeyCreator or SSecondaryMultiKeyCreator interface.

For example, to create a secondary database that supports duplicates:

  SDatabase primaryDb; // The primary database must already be open.
  SSecondaryKeyCreator keyCreator; // Your key creator implementation.
  SSecondaryConfig secConfig = new SSecondaryConfig();
  secConfig.setAllowCreate(true);
  secConfig.setSortedDuplicates(true);
  secConfig.setKeyCreator(keyCreator);
  SSecondaryDatabase newDb = env.openSecondaryDatabase(transaction,
                                                       "myDatabaseName",
                                                       primaryDb,
                                                       secConfig);
 

If a primary database is to be associated with one or more secondary databases, it may not be configured for duplicates.

Note that the associations between primary and secondary databases are not stored persistently. Whenever a primary database is opened for write access by the application, the appropriate associated secondary databases should also be opened by the application. This is necessary to ensure data integrity when changes are made to the primary database.

Nested Class Summary

Nested classes/interfaces inherited from interface com.sleepycat.client.GetHelper

GetHelper.RemoteGetFunction, GetHelper.RemotePGetFunction

Nested classes/interfaces inherited from interface com.sleepycat.client.PutHelper

PutHelper.RemotePutFunction

Nested classes/interfaces inherited from interface com.sleepycat.client.TxnHelper

TxnHelper.TransactionOperations<V>

Field Summary

Fields inherited from class com.sleepycat.client.SDatabase

client, tDb

Method Summary

Modifier and Type	Method and Description
void	close() Flush any cached database information to disk, close any open cursors, free allocated resources, close underlying files, and discard the database handle.
SOperationStatus	get(STransaction txn, SDatabaseEntry sKey, SDatabaseEntry pKey, SDatabaseEntry pData, SLockMode lockMode) Retrieves the secondary key / primary key / primary data tuple with the given secondary key.
SDatabase	getPrimaryDatabase() Returns the primary database associated with this secondary database.
SOperationStatus	getSearchBoth(STransaction txn, SDatabaseEntry sKey, SDatabaseEntry pKey, SDatabaseEntry pData, SLockMode lockMode) Retrieves the key/data pair with the specified secondary and primary key, that is, both the primary and secondary key items must match.
SOperationStatus	getSearchRecordNumber(STransaction txn, SDatabaseEntry sKey, SDatabaseEntry pKey, SDatabaseEntry pData, SLockMode lockMode) Retrieves the key/data pair associated with the specific numbered record of the database.
SSecondaryConfig	getSecondaryConfig() Returns a copy of the secondary configuration of this database.
default <V> V	handleRuntimeExceptions(com.sleepycat.client.RemoteServiceCallable<V> remote)
SSecondaryCursor	openCursor(STransaction txn, SCursorConfig config) Return a SSecondaryCursor into this secondary database.
default <V> V	remoteCall(com.sleepycat.client.RemoteServiceCallable<V> remote)
default <V> V	remoteCallWithIOException(com.sleepycat.client.RemoteServiceCallable<V> remote)

Methods inherited from class com.sleepycat.client.SDatabase

compact, createConfig, delete, deleteMultiple, deleteMultipleKey, exists, get, getConfig, getDatabaseFile, getDatabaseName, getEnvironment, getKeyRange, getSearchBoth, getSearchRecordNumber, getSecondaryDatabases, getServerByteOrder, getStats, join, openSequence, put, putMultipleKey, putNoDupData, putNoOverwrite, removeSequence, setConfig, truncate

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.sleepycat.client.GetHelper

createGetSearchTerm, createPGetSearchTerm, remoteGet, remotePGet, updateKeyData, updateTuple

Methods inherited from interface com.sleepycat.client.PutHelper

calculateSKey, remotePut

Methods inherited from interface com.sleepycat.client.TxnHelper

runInSingleTxn, runInSingleTxnWithIOException

Method Detail

close

public void close()
           throws SDatabaseException

Description copied from class: SDatabase

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

Closing a database handle will close any open cursors that refer to it. However, you should make sure to 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 this 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 close database handles.

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.

Specified by:

close in interface java.lang.AutoCloseable

Overrides:

close in class SDatabase

Throws:

SDatabaseException - if any error occurs

getPrimaryDatabase

public SDatabase getPrimaryDatabase()

Returns the primary database associated with this secondary database.

Returns:

the primary database associated with this secondary database

getSecondaryConfig

public SSecondaryConfig getSecondaryConfig()
                                    throws SDatabaseException

Returns a copy of the secondary configuration of this database.

Returns:

a copy of the secondary configuration of this database.

Throws:

SDatabaseException - if a failure occurs.

get

public SOperationStatus get(STransaction txn,
                            SDatabaseEntry sKey,
                            SDatabaseEntry pKey,
                            SDatabaseEntry pData,
                            SLockMode lockMode)
                     throws SDatabaseException

Retrieves the secondary key / primary key / primary data tuple with the given secondary key.

Parameters:

txn - an explicit transaction may be specified, or null may be specified to use auto-commit

sKey - the secondary key used as input

pKey - the primary key returned as output

pData - the primary data returned as output

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

Returns:

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

Throws:

SDatabaseException - if any error occurs

getSearchBoth

public SOperationStatus getSearchBoth(STransaction txn,
                                      SDatabaseEntry sKey,
                                      SDatabaseEntry pKey,
                                      SDatabaseEntry pData,
                                      SLockMode lockMode)
                               throws SDatabaseException

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 - an explicit transaction may be specified, or null may be specified to use auto-commit

sKey - the secondary key used as input

pKey - the primary key used as input

pData - the primary data returned as output

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

Returns:

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

Throws:

SDatabaseException - if any error occurs

getSearchRecordNumber

public SOperationStatus getSearchRecordNumber(STransaction txn,
                                              SDatabaseEntry sKey,
                                              SDatabaseEntry pKey,
                                              SDatabaseEntry pData,
                                              SLockMode lockMode)
                                       throws SDatabaseException

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

The specified secondary key must be a record number as described in SDatabaseEntry. 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:

txn - an explicit transaction may be specified, or null may be specified to use auto-commit

sKey - the record number as input; the secondary key returned as output

pKey - the primary key returned as output

pData - the primary data returned as output

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

Returns:

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

Throws:

SDatabaseException - if any error occurs

openCursor

public SSecondaryCursor openCursor(STransaction txn,
                                   SCursorConfig config)
                            throws SDatabaseException

Return a SSecondaryCursor into this secondary database.

Overrides:

openCursor in class SDatabase

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

Throws:

SDatabaseException - if any error occurs

remoteCallWithIOException

public <V> V remoteCallWithIOException(com.sleepycat.client.RemoteServiceCallable<V> remote)
                                throws java.io.IOException

Throws:

java.io.IOException

remoteCall

public <V> V remoteCall(com.sleepycat.client.RemoteServiceCallable<V> remote)

handleRuntimeExceptions

public <V> V handleRuntimeExceptions(com.sleepycat.client.RemoteServiceCallable<V> remote)
                              throws org.apache.thrift.TException

Throws:

org.apache.thrift.TException