com.sleepycat.je

Class JoinCursor

java.lang.Object

com.sleepycat.je.JoinCursor

All Implemented Interfaces:

ForwardCursor, java.io.Closeable, java.lang.AutoCloseable

public class JoinCursor
extends java.lang.Object
implements ForwardCursor, java.io.Closeable

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();
         }
     }
 

The join algorithm is described here so that its cost can be estimated and compared to other approaches for performing a query. Say that N cursors are provided for the join operation. According to the order they appear in the array the cursors are labeled C(1) through C(n), and the keys at each cursor position are labeled K(1) through K(n).

1. Using C(1), the join algorithm iterates sequentially through all records having K(1). This iteration is equivalent to a Cursor.getNextDup operation on the secondary index. The primary key of a candidate record is determined in this manner. The primary record itself is not retrieved and the primary database is not accessed.
2. For each candidate primary key found in step 1, a Btree lookup is performed using C(2) through C(n), in that order. The Btree lookups are exact searches to determine whether the candidate record also contains secondary keys K(2) through K(n). The lookups are equivalent to a Cursor.getSearchBoth operation on the secondary index. The primary record itself is not retrieved and the primary database is not accessed.
3. If any lookup in step 2 fails, the algorithm advances to the next candidate record using C(1). Lookups are performed in the order of the cursor array, and the algorithm proceeds to the next C(1) candidate key as soon as a single lookup fails.
4. If all lookups in step 2 succeed, then the matching key and/or data is returned by the getNext method. If the getNext(DatabaseEntry,DatabaseEntry,LockMode) method signature is used, then the primary database is read to obtain the record data, as if Cursor.getSearchKey were called for the primary database. If the getNext(DatabaseEntry,LockMode) method signature is used, then only the primary key is returned and the primary database is not accessed.
5. The algorithm ends when C(1) has no more candidate records with K(1), and the getNext method will then return OperationStatus.NOTFOUND.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the cursors that have been opened by this join cursor.
OperationResult	get(DatabaseEntry key, DatabaseEntry data, Get getType, ReadOptions options) Returns the next primary key and data resulting from the join operation.
JoinConfig	getConfig() Returns this object's configuration.
OperationStatus	getCurrent(DatabaseEntry key, DatabaseEntry data, LockMode lockMode) This operation is not allowed on a join cursor.
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.

WARNING: To guard against memory leaks, the application should discard all references to the closed handle. While BDB makes an effort to discard references from closed objects to the allocated memory for an environment, this behavior is not guaranteed. The safe course of action for an application is to discard all references to closed BDB objects.

Specified by:

close in interface ForwardCursor

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException

getDatabase

public Database getDatabase()

Returns the primary database handle associated with this cursor.

Specified by:

getDatabase in interface ForwardCursor

Returns:

the primary database handle associated with this cursor.

getConfig

public JoinConfig getConfig()

Returns this object's configuration.

Returns:

this object's configuration.

get

public OperationResult get(DatabaseEntry key,
                           DatabaseEntry data,
                           Get getType,
                           ReadOptions options)

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

Specified by:

get in interface ForwardCursor

Parameters:

getType - is Get.NEXT.

key - the key returned as output.

data - the data returned as output.

options - the ReadOptions, or null to use default options.

Returns:

the OperationResult if the record requested is found, else null.

getCurrent

public OperationStatus getCurrent(DatabaseEntry key,
                                  DatabaseEntry data,
                                  LockMode lockMode)

This operation is not allowed on a join cursor. UnsupportedOperationException will always be thrown by this method.

Specified by:

getCurrent in interface ForwardCursor

Parameters:

key - the key returned as output.

data - the data returned as output.

lockMode - the locking attributes; if null, default attributes are used. LockMode.READ_COMMITTED is not allowed.

Returns:

OperationStatus.KEYEMPTY if the key/pair at the cursor position has been deleted; otherwise, OperationStatus.SUCCESS.

getNext

public OperationStatus getNext(DatabaseEntry key,
                               LockMode lockMode)

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 key returned as output.

lockMode - the locking attributes; if null, default attributes are used. LockMode.READ_COMMITTED is not allowed.

Returns:

OperationStatus.NOTFOUND if no matching key/data pair is found; otherwise, OperationStatus.SUCCESS.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

java.lang.IllegalStateException - if the cursor or database has been closed, or the non-transactional cursor was created in a different thread.

java.lang.IllegalArgumentException - if an invalid parameter is specified.

getNext

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

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.

Specified by:

getNext in interface ForwardCursor

Parameters:

key - the key returned as output.

data - the data returned as output.

lockMode - the locking attributes; if null, default attributes are used. LockMode.READ_COMMITTED is not allowed.

Returns:

OperationStatus.NOTFOUND if no matching key/data pair is found; otherwise, OperationStatus.SUCCESS.