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

com.sleepycat.client

## Class SJoinCursor

- java.lang.Object
- - com.sleepycat.client.SJoinCursor

- All Implemented Interfaces:
    java.lang.AutoCloseable

      public class SJoinCursor
      extends java.lang.Object
      implements java.lang.AutoCloseable

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

  A join cursor is returned when calling `SDatabase.join(com.sleepycat.client.SCursor[], com.sleepycat.client.SJoinConfig)`.

  To open a join cursor using two secondary cursors:

        STransaction txn = ...
        SDatabase primaryDb = ...
        SSecondaryDatabase secondaryDb1 = ...
        SSecondaryDatabase secondaryDb2 = ...

        SSecondaryCursor cursor1 = null;
        SSecondaryCursor cursor2 = null;
        SJoinCursor joinCursor = null;
        try {
            SDatabaseEntry key = new SDatabaseEntry();
            SDatabaseEntry data = new SDatabaseEntry();

            cursor1 = secondaryDb1.openSecondaryCursor(txn, null);
            cursor2 = secondaryDb2.openSecondaryCursor(txn, null);

            key.setData(...); // initialize key for secondary index 1
            SOperationStatus status1 =
                cursor1.getSearchKey(key, data, SLockMode.DEFAULT);
            key.setData(...); // initialize key for secondary index 2
            OperationStatus status2 =
                cursor2.getSearchKey(key, data, SLockMode.DEFAULT);

            if (status1 == OperationStatus.SUCCESS &&
                    status2 == OperationStatus.SUCCESS) {
                SSecondaryCursor[] cursors = {cursor1, cursor2};
                joinCursor = primaryDb.join(cursors, null);

                while (true) {
                    SOperationStatus joinStatus = joinCursor.getNext(key, data,
                        SLockMode.DEFAULT);
                    if (joinStatus == OperationStatus.SUCCESS) {
                        // Do something with the key and data.
                    } else {
                        break;
                    }
                }
            }
        } finally {
            if (cursor1 != null) {
                cursor1.close();
            }
            if (cursor2 != null) {
                cursor2.close();
            }
            if (joinCursor != null) {
                joinCursor.close();
            }
       }

- - ### Method Summary

    All Methods Instance Methods Concrete Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes the cursors that have been opened by this join cursor.
    `SJoinConfig` | `getConfig()` Returns this object's configuration.
    `SDatabase` | `getDatabase()` Returns the primary database handle associated with this cursor.
    `SOperationStatus` | `getNext(SDatabaseEntry key, SDatabaseEntry data, SLockMode lockMode)` Returns the next primary key and data resulting from the join operation.
    `SOperationStatus` | `getNext(SDatabaseEntry key, SLockMode lockMode)` Returns the next primary key resulting from the join operation.
    `default <V> V` | `handleRuntimeExceptions(com.sleepycat.client.RemoteServiceCallable<V> remote)`
    `default <V> V` | `remoteCall(com.sleepycat.client.RemoteServiceCallable<V> remote)`
    `default <V> V` | `remoteCallWithIOException(com.sleepycat.client.RemoteServiceCallable<V> remote)`

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### close

          public void close()
                     throws SDatabaseException

      Closes the cursors that have been opened by this join cursor.

      The cursors passed to `SDatabase.join(com.sleepycat.client.SCursor[], com.sleepycat.client.SJoinConfig)` are not closed by this method, and should be closed by the caller.

      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Throws:
        `SDatabaseException` - if any error occurs

    - #### getConfig

          public SJoinConfig getConfig()

      Returns this object's configuration.
      Returns:
        this object's configuration

    - #### getDatabase

          public SDatabase getDatabase()

      Returns the primary database handle associated with this cursor.
      Returns:
        the primary database handle associated with this cursor

    - #### getNext

          public SOperationStatus getNext(SDatabaseEntry key,
                                          SLockMode lockMode)
                                   throws SDatabaseException

      Returns the next primary key resulting from the join operation.

      An entry is returned by the join cursor for each primary key/data pair having all secondary key values that were specified using the array of secondary cursors passed to `SDatabase.join(com.sleepycat.client.SCursor[], com.sleepycat.client.SJoinConfig)`.

      Parameters:
        `key` - the primary key 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

    - #### getNext

          public SOperationStatus getNext(SDatabaseEntry key,
                                          SDatabaseEntry data,
                                          SLockMode lockMode)
                                   throws SDatabaseException

      Returns the next primary key and data resulting from the join operation.

      An entry is returned by the join cursor for each primary key/data pair having all secondary key values that were specified using the array of secondary cursors passed to `SDatabase.join(com.sleepycat.client.SCursor[], com.sleepycat.client.SJoinConfig)`.

      Parameters:
        `key` - the primary key returned as output
        `data` - 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

    - #### 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.