public class JoinCursor extends java.lang.Object implements ForwardCursor, java.io.Closeable
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).
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.Cursor.getSearchBoth
operation on the secondary index.
The primary record itself is not retrieved and the primary database is not
accessed.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.getNext
method will then return OperationStatus.NOTFOUND
.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.
|
public void close() throws DatabaseException
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.
close
in interface ForwardCursor
close
in interface java.io.Closeable
close
in interface java.lang.AutoCloseable
EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.DatabaseException
public Database getDatabase()
getDatabase
in interface ForwardCursor
public JoinConfig getConfig()
public OperationResult get(DatabaseEntry key, DatabaseEntry data, Get getType, ReadOptions options)
get
in interface ForwardCursor
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.public OperationStatus getCurrent(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
UnsupportedOperationException
will always be thrown by this method.getCurrent
in interface ForwardCursor
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.OperationStatus.KEYEMPTY
if the key/pair at the cursor position has
been deleted; otherwise, OperationStatus.SUCCESS
.public OperationStatus getNext(DatabaseEntry key, LockMode lockMode)
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
.
key
- the key returned as
output.lockMode
- the locking attributes; if null, default attributes are
used. LockMode.READ_COMMITTED
is not allowed.OperationStatus.NOTFOUND
if no matching key/data pair is found;
otherwise, OperationStatus.SUCCESS
.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.public OperationStatus getNext(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
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
.
getNext
in interface ForwardCursor
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.OperationStatus.NOTFOUND
if no matching key/data pair is found;
otherwise, OperationStatus.SUCCESS
.Copyright (c) 2002, 2017 Oracle and/or its affiliates. All rights reserved.