Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB Java Edition version 4.0.103
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sleepycat.je
Class JoinCursor

    java.lang.Object
      com.sleepycat.je.JoinCursor

    public class JoinCursor

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

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
`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:
    `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
    `DatabaseException`

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

  In a replicated environment, an explicit transaction must have been specified when opening each cursor, unless read-uncommitted isolation is specified via the `CursorConfig` or `LockMode` parameters.

  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; otherwise, `OperationStatus.SUCCESS`.
  Throws:
    `OperationFailureException` - if one of the Read Operation Failures occurs.
    `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
    `IllegalArgumentException` - if an invalid parameter is specified, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.
    `DatabaseException`

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

  In a replicated environment, an explicit transaction must have been specified when opening each cursor, unless read-uncommitted isolation is specified via the `CursorConfig` or `LockMode` parameters.

  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; otherwise, `OperationStatus.SUCCESS`.
  Throws:
    `OperationFailureException` - if one of the Read Operation Failures occurs.
    `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
    `IllegalArgumentException` - if an invalid parameter is specified, for example, if a DatabaseEntry parameter is null or does not contain a required non-null byte array.
    `DatabaseException`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB Java Edition version 4.0.103
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2004-2010 Oracle. All rights reserved.