JoinCursor (Oracle - Berkeley DB Java API)
Date: 2017-04-13

com.sleepycat.db

## Class JoinCursor

- java.lang.Object
- - com.sleepycat.db.JoinCursor

-     public class JoinCursor
      extends java.lang.Object

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

  A join cursor is returned when calling `Database.join`.

  To open a join cursor using two secondary cursors:

          Transaction txn = ...
          Database primaryDb = ...
          SecondaryDatabase secondaryDb1 = ...
          SecondaryDatabase secondaryDb2 = ...

          SecondaryCursor cursor1 = null;
          SecondaryCursor cursor2 = null;
          JoinCursor joinCursor = null;
          try {
              DatabaseEntry key = new DatabaseEntry();
              DatabaseEntry data = new DatabaseEntry();

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

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

              if (status1 == OperationStatus.SUCCESS &&
                      status2 == OperationStatus.SUCCESS) {

                  SecondaryCursor[] cursors = {cursor1, cursor2};
                  joinCursor = primaryDb.join(cursors, null);

                  while (true) {
                      OperationStatus joinStatus = joinCursor.getNext(key, data,
                          LockMode.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
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes the cursors that have been opened by this join cursor.
    `JoinConfig` | `getConfig()` Returns this object's configuration.
    `Database` | `getDatabase()` Returns the primary database handle associated with this cursor.
    `OperationStatus` | `getNext(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)` Returns the next primary key and data resulting from the join operation.
    `OperationStatus` | `getNext(DatabaseEntry key, LockMode lockMode)` Returns the next primary key resulting from the join operation.

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

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

      The cursors passed to `Database.join` are not closed by this method, and should be closed by the caller.

      Throws:
        `DatabaseException` - if a failure occurs.

    - #### getDatabase

          public Database getDatabase()

      Returns the primary database handle associated with this cursor.

      Returns:
        the primary database handle associated with this cursor.

    - #### getConfig

          public JoinConfig getConfig()

      Returns this object's configuration.

      Returns:
        this object's configuration.

    - #### getNext

          public OperationStatus getNext(DatabaseEntry key,
                                         LockMode lockMode)
                                  throws DatabaseException

      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 `Database.join`.

      Parameters:
        `key` - the primary key 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:
        `OperationStatus.NOTFOUND` if no matching key/data pair is found; `OperationStatus.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, `OperationStatus.SUCCESS`.

      Throws:
        `java.lang.NullPointerException` - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

        `java.lang.IllegalArgumentException` - if an invalid parameter was specified.

        `DatabaseException` - if a failure occurs.

    - #### getNext

          public OperationStatus getNext(DatabaseEntry key,
                                         DatabaseEntry data,
                                         LockMode lockMode)
                                  throws DatabaseException

      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 `Database.join`.

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

      Throws:
        `java.lang.NullPointerException` - if a DatabaseEntry parameter is null or does not contain a required non-null byte array.

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

        `java.lang.IllegalArgumentException` - if an invalid parameter was specified.

        `DatabaseException` - if a failure occurs.

Copyright (c) 1996, 2017 Oracle and/or its affiliates. All rights reserved.