SSecondaryDatabase (Oracle - Berkeley DB Client-Server API)
Date: 2018-05-29

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

    All Methods Instance Methods Concrete Methods Default Methods
    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`

Copyright (c) 2016, 2018 Oracle and/or its affiliates. All rights reserved.