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

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