Version 3.2.1
com.wiredtiger.db.Cursor Class Reference

A WT_CURSOR handle is the interface to a cursor. More...

Public Member Functions

synchronized void delete ()
 
String getKeyFormat ()
 
String getValueFormat ()
 
Cursor putKeyByte (byte value) throws WiredTigerPackingException
 
Cursor putKeyByteArray (byte[] value) throws WiredTigerPackingException
 
Cursor putKeyByteArray (byte[] value, int off, int len) throws WiredTigerPackingException
 
Cursor putKeyInt (int value) throws WiredTigerPackingException
 
Cursor putKeyLong (long value) throws WiredTigerPackingException
 
Cursor putKeyRecord (long value) throws WiredTigerPackingException
 
Cursor putKeyShort (short value) throws WiredTigerPackingException
 
Cursor putKeyString (String value) throws WiredTigerPackingException
 
Cursor putValueByte (byte value) throws WiredTigerPackingException
 
Cursor putValueByteArray (byte[] value) throws WiredTigerPackingException
 
Cursor putValueByteArray (byte[] value, int off, int len) throws WiredTigerPackingException
 
Cursor putValueInt (int value) throws WiredTigerPackingException
 
Cursor putValueLong (long value) throws WiredTigerPackingException
 
Cursor putValueRecord (long value) throws WiredTigerPackingException
 
Cursor putValueShort (short value) throws WiredTigerPackingException
 
Cursor putValueString (String value) throws WiredTigerPackingException
 
byte getKeyByte () throws WiredTigerPackingException
 
void getKeyByteArray (byte[] output) throws WiredTigerPackingException
 
void getKeyByteArray (byte[] output, int off, int len) throws WiredTigerPackingException
 
byte [] getKeyByteArray () throws WiredTigerPackingException
 
int getKeyInt () throws WiredTigerPackingException
 
long getKeyLong () throws WiredTigerPackingException
 
long getKeyRecord () throws WiredTigerPackingException
 
short getKeyShort () throws WiredTigerPackingException
 
String getKeyString () throws WiredTigerPackingException
 
byte getValueByte () throws WiredTigerPackingException
 
void getValueByteArray (byte[] output) throws WiredTigerPackingException
 
void getValueByteArray (byte[] output, int off, int len) throws WiredTigerPackingException
 
byte [] getValueByteArray () throws WiredTigerPackingException
 
int getValueInt () throws WiredTigerPackingException
 
long getValueLong () throws WiredTigerPackingException
 
long getValueRecord () throws WiredTigerPackingException
 
short getValueShort () throws WiredTigerPackingException
 
String getValueString () throws WiredTigerPackingException
 
int insert () throws WiredTigerException
 
int update () throws WiredTigerException
 
int remove () throws WiredTigerException
 
int compare (Cursor other) throws WiredTigerException
 
int equals (Cursor other) throws WiredTigerException
 
int next () throws WiredTigerException
 
int prev () throws WiredTigerException
 
int reset () throws WiredTigerException
 
int search () throws WiredTigerException
 
SearchStatus search_near () throws WiredTigerException
 
int modify (Modify mods[]) throws WiredTigerException
 
Session getSession ()
 
String getUri ()
 
int reserve () throws com.wiredtiger.db.WiredTigerException
 Reserve an existing record so a subsequent write is less likely to fail due to a conflict between concurrent operations. More...
 
int close () throws com.wiredtiger.db.WiredTigerException
 Close the cursor. More...
 
int reconfigure (String config) throws com.wiredtiger.db.WiredTigerException
 Reconfigure the cursor. More...
 
int modify_wrap (WT_MODIFY_LIST list, byte[] k)
 
boolean _new_check_modify_list (WT_MODIFY_LIST list)
 
boolean _new_check_modify (Modify mod)
 

Protected Member Functions

 Cursor (long cPtr, boolean cMemoryOwn)
 
String getKey_format ()
 
String getValue_format ()
 
int next_wrap () throws com.wiredtiger.db.WiredTigerException
 
int prev_wrap () throws com.wiredtiger.db.WiredTigerException
 
byte [] get_key_wrap ()
 
byte [] get_value_wrap ()
 
int insert_wrap (byte[] k, byte[] v)
 
int remove_wrap (byte[] k)
 
int reset_wrap ()
 
int search_wrap (byte[] k)
 
SearchStatus search_near_wrap (byte[] k)
 
int update_wrap (byte[] k, byte[] v)
 
int compare_wrap (Cursor other)
 
int equals_wrap (Cursor other)
 
boolean _java_raw ()
 
int _java_init (Object jcursor)
 

Static Protected Member Functions

static long getCPtr (Cursor obj)
 

Protected Attributes

boolean swigCMemOwn
 
String keyFormat
 
String valueFormat
 
PackOutputStream keyPacker
 
PackOutputStream valuePacker
 
PackInputStream keyUnpacker
 
PackInputStream valueUnpacker
 

Detailed Description

A WT_CURSOR handle is the interface to a cursor.

Cursors allow data to be searched, iterated and modified, implementing the CRUD (create, read, update and delete) operations. Cursors are opened in the context of a session. If a transaction is started, cursors operate in the context of the transaction until the transaction is resolved.

Raw data is represented by key/value pairs of WT_ITEM structures, but cursors can also provide access to fields within the key and value if the formats are described in the WT_SESSION::create method.

In the common case, a cursor is used to access records in a table. However, cursors can be used on subsets of tables (such as a single column or a projection of multiple columns), as an interface to statistics, configuration data or application-specific data sources. See WT_SESSION::open_cursor for more information.

Thread safety: A WT_CURSOR handle is not usually shared between threads, see Multithreading for more information.

Member Function Documentation

◆ close()

int com.wiredtiger.db.Cursor.close ( ) throws com.wiredtiger.db.WiredTigerException

Close the cursor.

This releases the resources associated with the cursor handle. Cursors are closed implicitly by ending the enclosing connection or closing the session in which they were opened.

error_check(cursor->close(cursor));
Parameters
cursorthe cursor handle
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ compare()

int com.wiredtiger.db.Cursor.compare ( Cursor  other) throws WiredTigerException

Compare this cursor's position to another Cursor.

Returns
The result of the comparison.

◆ equals()

int com.wiredtiger.db.Cursor.equals ( Cursor  other) throws WiredTigerException

Compare this cursor's position to another Cursor.

Returns
The result of the comparison.

◆ getKeyByte()

byte com.wiredtiger.db.Cursor.getKeyByte ( ) throws WiredTigerPackingException

Retrieve a byte from the cursor's key.

Returns
The requested value.

◆ getKeyByteArray() [1/3]

void com.wiredtiger.db.Cursor.getKeyByteArray ( byte []  output) throws WiredTigerPackingException

Retrieve a byte array from the cursor's key.

Parameters
outputThe byte array where the returned value will be stored. The array should be large enough to store the entire data item, if not a truncated value will be returned.

◆ getKeyByteArray() [2/3]

void com.wiredtiger.db.Cursor.getKeyByteArray ( byte []  output,
int  off,
int  len 
) throws WiredTigerPackingException

Retrieve a byte array from the cursor's key.

Parameters
outputThe byte array where the returned value will be stored.
offOffset into the destination buffer to start copying into.
lenThe length should be large enough to store the entire data item, if not a truncated value will be returned.

◆ getKeyByteArray() [3/3]

byte [] com.wiredtiger.db.Cursor.getKeyByteArray ( ) throws WiredTigerPackingException

Retrieve a byte array from the cursor's key.

Returns
The requested value.

◆ getKeyFormat()

String com.wiredtiger.db.Cursor.getKeyFormat ( )

Retrieve the format string for this cursor's key.

◆ getKeyInt()

int com.wiredtiger.db.Cursor.getKeyInt ( ) throws WiredTigerPackingException

Retrieve an integer from the cursor's key.

Returns
The requested value.

◆ getKeyLong()

long com.wiredtiger.db.Cursor.getKeyLong ( ) throws WiredTigerPackingException

Retrieve a long from the cursor's key.

Returns
The requested value.

◆ getKeyRecord()

long com.wiredtiger.db.Cursor.getKeyRecord ( ) throws WiredTigerPackingException

Retrieve a record number from the cursor's key.

Returns
The requested value.

◆ getKeyShort()

short com.wiredtiger.db.Cursor.getKeyShort ( ) throws WiredTigerPackingException

Retrieve a short integer from the cursor's key.

Returns
The requested value.

◆ getKeyString()

String com.wiredtiger.db.Cursor.getKeyString ( ) throws WiredTigerPackingException

Retrieve a string from the cursor's key.

Returns
The requested value.

◆ getValueByte()

byte com.wiredtiger.db.Cursor.getValueByte ( ) throws WiredTigerPackingException

Retrieve a byte from the cursor's value.

Returns
The requested value.

◆ getValueByteArray() [1/3]

void com.wiredtiger.db.Cursor.getValueByteArray ( byte []  output) throws WiredTigerPackingException

Retrieve a byte array from the cursor's value.

Parameters
outputThe byte array where the returned value will be stored. The array should be large enough to store the entire data item, if not a truncated value will be returned.

◆ getValueByteArray() [2/3]

void com.wiredtiger.db.Cursor.getValueByteArray ( byte []  output,
int  off,
int  len 
) throws WiredTigerPackingException

Retrieve a byte array from the cursor's value.

Parameters
outputThe byte array where the returned value will be stored.
offOffset into the destination buffer to start copying into.
lenThe length should be large enough to store the entire data item, if not a truncated value will be returned.

◆ getValueByteArray() [3/3]

byte [] com.wiredtiger.db.Cursor.getValueByteArray ( ) throws WiredTigerPackingException

Retrieve a byte array from the cursor's value.

Returns
The requested value.

◆ getValueFormat()

String com.wiredtiger.db.Cursor.getValueFormat ( )

Retrieve the format string for this cursor's value.

◆ getValueInt()

int com.wiredtiger.db.Cursor.getValueInt ( ) throws WiredTigerPackingException

Retrieve an integer from the cursor's value.

Returns
The requested value.

◆ getValueLong()

long com.wiredtiger.db.Cursor.getValueLong ( ) throws WiredTigerPackingException

Retrieve a long from the cursor's value.

Returns
The requested value.

◆ getValueRecord()

long com.wiredtiger.db.Cursor.getValueRecord ( ) throws WiredTigerPackingException

Retrieve a record number from the cursor's value.

Returns
The requested value.

◆ getValueShort()

short com.wiredtiger.db.Cursor.getValueShort ( ) throws WiredTigerPackingException

Retrieve a short integer from the cursor's value.

Returns
The requested value.

◆ getValueString()

String com.wiredtiger.db.Cursor.getValueString ( ) throws WiredTigerPackingException

Retrieve a string from the cursor's value.

Returns
The requested value.

◆ insert()

int com.wiredtiger.db.Cursor.insert ( ) throws WiredTigerException

Insert the cursor's current key/value into the table.

Returns
The status of the operation.

◆ modify()

int com.wiredtiger.db.Cursor.modify ( Modify  mods[]) throws WiredTigerException

Modify an existing record.

The cursor must already be positioned, and the key's value will be updated.

Parameters
modsan array of modifications.
Returns
0 on success, errno on error.

◆ next()

int com.wiredtiger.db.Cursor.next ( ) throws WiredTigerException

Retrieve the next item in the table.

Returns
The result of the comparison.

◆ prev()

int com.wiredtiger.db.Cursor.prev ( ) throws WiredTigerException

Retrieve the previous item in the table.

Returns
The result of the comparison.

◆ putKeyByte()

Cursor com.wiredtiger.db.Cursor.putKeyByte ( byte  value) throws WiredTigerPackingException

Append a byte to the cursor's key.

Parameters
valueThe value to append.
Returns
This cursor object, so put calls can be chained.

◆ putKeyByteArray() [1/2]

Cursor com.wiredtiger.db.Cursor.putKeyByteArray ( byte []  value) throws WiredTigerPackingException

Append a byte array to the cursor's key.

Parameters
valueThe value to append.
Returns
This cursor object, so put calls can be chained.

◆ putKeyByteArray() [2/2]

Cursor com.wiredtiger.db.Cursor.putKeyByteArray ( byte []  value,
int  off,
int  len 
) throws WiredTigerPackingException

Append a byte array to the cursor's key.

Parameters
valueThe value to append.
offThe offset into value at which to start.
lenThe length of the byte array.
Returns
This cursor object, so put calls can be chained.

◆ putKeyInt()

Cursor com.wiredtiger.db.Cursor.putKeyInt ( int  value) throws WiredTigerPackingException

Append an integer to the cursor's key.

Parameters
valueThe value to append
Returns
This cursor object, so put calls can be chained.

◆ putKeyLong()

Cursor com.wiredtiger.db.Cursor.putKeyLong ( long  value) throws WiredTigerPackingException

Append a long to the cursor's key.

Parameters
valueThe value to append
Returns
This cursor object, so put calls can be chained.

◆ putKeyRecord()

Cursor com.wiredtiger.db.Cursor.putKeyRecord ( long  value) throws WiredTigerPackingException

Append a record number to the cursor's key.

Parameters
valueThe value to append
Returns
This cursor object, so put calls can be chained.

◆ putKeyShort()

Cursor com.wiredtiger.db.Cursor.putKeyShort ( short  value) throws WiredTigerPackingException

Append a short integer to the cursor's key.

Parameters
valueThe value to append
Returns
This cursor object, so put calls can be chained.

◆ putKeyString()

Cursor com.wiredtiger.db.Cursor.putKeyString ( String  value) throws WiredTigerPackingException

Append a string to the cursor's key.

Parameters
valueThe value to append
Returns
This cursor object, so put calls can be chained.

◆ putValueByte()

Cursor com.wiredtiger.db.Cursor.putValueByte ( byte  value) throws WiredTigerPackingException

Append a byte to the cursor's value.

Parameters
valueThe value to append
Returns
This cursor object, so put calls can be chained.

◆ putValueByteArray() [1/2]

Cursor com.wiredtiger.db.Cursor.putValueByteArray ( byte []  value) throws WiredTigerPackingException

Append a byte array to the cursor's value.

Parameters
valueThe value to append
Returns
This cursor object, so put calls can be chained.

◆ putValueByteArray() [2/2]

Cursor com.wiredtiger.db.Cursor.putValueByteArray ( byte []  value,
int  off,
int  len 
) throws WiredTigerPackingException

Append a byte array to the cursor's value.

Parameters
valueThe value to append
offThe offset into value at which to start.
lenThe length of the byte array.
Returns
This cursor object, so put calls can be chained.

◆ putValueInt()

Cursor com.wiredtiger.db.Cursor.putValueInt ( int  value) throws WiredTigerPackingException

Append an integer to the cursor's value.

Parameters
valueThe value to append
Returns
This cursor object, so put calls can be chained.

◆ putValueLong()

Cursor com.wiredtiger.db.Cursor.putValueLong ( long  value) throws WiredTigerPackingException

Append a long to the cursor's value.

Parameters
valueThe value to append
Returns
This cursor object, so put calls can be chained.

◆ putValueRecord()

Cursor com.wiredtiger.db.Cursor.putValueRecord ( long  value) throws WiredTigerPackingException

Append a record number to the cursor's value.

Parameters
valueThe value to append
Returns
This cursor object, so put calls can be chained.

◆ putValueShort()

Cursor com.wiredtiger.db.Cursor.putValueShort ( short  value) throws WiredTigerPackingException

Append a short integer to the cursor's value.

Parameters
valueThe value to append
Returns
This cursor object, so put calls can be chained.

◆ putValueString()

Cursor com.wiredtiger.db.Cursor.putValueString ( String  value) throws WiredTigerPackingException

Append a string to the cursor's value.

Parameters
valueThe value to append
Returns
This cursor object, so put calls can be chained.

◆ reconfigure()

int com.wiredtiger.db.Cursor.reconfigure ( String  config) throws com.wiredtiger.db.WiredTigerException

Reconfigure the cursor.

The cursor is reset.

error_check(
session->open_cursor(session, "table:mytable", NULL, "overwrite=false", &cursor));
/* Reconfigure the cursor to overwrite the record. */
error_check(cursor->reconfigure(cursor, "overwrite=true"));
cursor->set_key(cursor, key);
cursor->set_value(cursor, value);
error_check(cursor->insert(cursor));
Parameters
cursorthe cursor handle
configconfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
appendappend the value as a new record, creating a new record number key; valid only for cursors with record number keys.a boolean flag; default false.
overwriteconfigures whether the cursor's insert, update and remove methods check the existing state of the record. If overwrite is false, WT_CURSOR::insert fails with WT_DUPLICATE_KEY if the record exists, WT_CURSOR::update and WT_CURSOR::remove fail with WT_NOTFOUND if the record does not exist.a boolean flag; default true.
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ remove()

int com.wiredtiger.db.Cursor.remove ( ) throws WiredTigerException

Remove the cursor's current key/value into the table.

Returns
The status of the operation.

◆ reserve()

int com.wiredtiger.db.Cursor.reserve ( ) throws com.wiredtiger.db.WiredTigerException

Reserve an existing record so a subsequent write is less likely to fail due to a conflict between concurrent operations.

The key must first be set and the record must already exist.

Note that reserve works by doing a special update operation that is not logged and does not change the value of the record. This update is aborted when the enclosing transaction ends regardless of whether it commits or rolls back. Given that, reserve can only be used to detect conflicts between transactions that execute concurrently. It cannot detect all logical conflicts between transactions. For that, some update to the record must be committed.

const char *key = "some key";
error_check(session->begin_transaction(session, NULL));
cursor->set_key(cursor, key);
error_check(cursor->reserve(cursor));
error_check(session->commit_transaction(session, NULL));

On success, the cursor ends positioned at the specified record; to minimize cursor resources, the WT_CURSOR::reset method should be called as soon as the cursor no longer needs that position.

Parameters
cursorthe cursor handle
Returns
zero on success and a non-zero error code on failure. See Error handling for details.

◆ reset()

int com.wiredtiger.db.Cursor.reset ( ) throws WiredTigerException

Reset a cursor.

Returns
The status of the operation.

◆ search()

int com.wiredtiger.db.Cursor.search ( ) throws WiredTigerException

Search for an item in the table.

Returns
The result of the comparison.

◆ search_near()

SearchStatus com.wiredtiger.db.Cursor.search_near ( ) throws WiredTigerException

Search for an item in the table.

Returns
The result of the comparison.

◆ update()

int com.wiredtiger.db.Cursor.update ( ) throws WiredTigerException

Update the cursor's current key/value into the table.

Returns
The status of the operation.