WiredTiger: com.wiredtiger.db.Cursor Class Reference

| Version 3.1.0

Fork me on GitHub Join my user group
List of all members | Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes
com.wiredtiger.db.Cursor Class Reference
WiredTiger Java API

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

  cursor | the 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

  output | The 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

  output | The byte array where the returned value will be stored.
  off | Offset into the destination buffer to start copying into.
  len | The 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

  output | The 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

  output | The byte array where the returned value will be stored.
  off | Offset into the destination buffer to start copying into.
  len | The 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

  mods | an 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

  value | The 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

  value | The 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

  value | The value to append.
  off | The offset into value at which to start.
  len | The 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

  value | The 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

  value | The 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

  value | The 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

  value | The 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

  value | The 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

  value | The 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

  value | The 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

  value | The value to append
  off | The offset into value at which to start.
  len | The 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

  value | The 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

  value | The 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

  value | The 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

  value | The 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

  value | The 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

  cursor | the cursor handle
  config | configuration string, see Configuration Strings. Permitted values:
  Name | Effect | Values
  --- | --- | ---
  `append` | append 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`.
  `overwrite` | configures 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.

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

  cursor | the 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.