Package oracle.kv.table

# Interface Row

All Superinterfaces:
  `Comparable<FieldValue>`, `FieldValue`, `RecordValue`

All Known Subinterfaces:
  `PrimaryKey`, `ReturnRow`

public interface Row extends RecordValue
Row is a specialization of RecordValue to represent a single record, or row, in a table. It is a central object used in most table operations defined in `TableAPI`.

Row objects are constructed explicitly using `createRow` or implicitly when returned from table access operations.

Since:
  3.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Row`
  `clone()`
  Returns a deep copy of this object.
  `PrimaryKey`
  `createPrimaryKey()`
  Creates a PrimaryKey from this Row.
  `boolean`
  `equals(Object other)`
  Equality comparison for Row instances is based on equality of the individual field values and ignores the included `Version`, if present.
  `long`
  `getExpirationTime()`
  Returns the expiration time of the row.
  `long`
  `getLastModificationTime()`
  Returns the last modification time of the row or zero if it is not available or not yet set.
  `String`
  `getRowMetadata()`
  This method is **EXPERIMENTAL** and its behavior, signature, or even its existence may change without prior notice in future versions.
  `Table`
  `getTable()`
  Return the Table associated with this row.
  `int`
  `getTableVersion()`
  Returns the version of the table used to create this row if it has been deserialized from a get operation.
  `TimeToLive`
  `getTTL()`
  Returns the time to live (TTL) value for this row or null if it has not been set by a call to `setTTL(oracle.kv.table.TimeToLive)`.
  `Version`
  `getVersion()`
  Returns the Version for the row.
  `void`
  `setRowMetadata(String rowMetadata)`
  This method is **EXPERIMENTAL** and its behavior, signature, or even its existence may change without prior notice in future versions.
  `void`
  `setTTL(TimeToLive ttl)`
  Sets a time to live (TTL) value for the row to be used when the row is inserted into a store.

  ### Methods inherited from interface java.lang.Comparable

  `compareTo`

  ### Methods inherited from interface oracle.kv.table.FieldValue

  `asArray, asBinary, asBoolean, asDouble, asEnum, asFixedBinary, asFloat, asIndexKey, asInteger, asLong, asMap, asNumber, asPrimaryKey, asRecord, asRow, asString, asTimestamp, getType, isArray, isAtomic, isBinary, isBoolean, isComplex, isDouble, isEMPTY, isEnum, isFixedBinary, isFloat, isIndexKey, isInteger, isJsonNull, isLong, isMap, isNull, isNumber, isNumeric, isPrimaryKey, isRecord, isRow, isString, isTimestamp, toJsonString`

  ### Methods inherited from interface oracle.kv.table.RecordValue

  `clear, contains, contains, copyFrom, get, get, getDefinition, getFieldName, getFieldNames, getFieldPos, getFields, isEmpty, put, put, put, put, put, put, put, put, put, put, put, put, put, put, put, put, put, put, putArray, putArray, putArray, putArray, putArray, putArray, putArrayAsJson, putArrayAsJson, putArrayAsJson, putArrayAsJson, putEnum, putEnum, putFixed, putFixed, putJson, putJson, putJson, putJson, putJsonNull, putJsonNull, putMap, putMap, putMap, putMap, putMapAsJson, putMapAsJson, putMapAsJson, putMapAsJson, putNull, putNull, putNumber, putNumber, putNumber, putNumber, putNumber, putNumber, putNumber, putNumber, putNumber, putNumber, putRecord, putRecord, putRecord, putRecord, putRecordAsJson, putRecordAsJson, putRecordAsJson, putRecordAsJson, remove, size, toString`

- ## Method Details

  - ### getTable

    Table getTable()
    Return the Table associated with this row.
    Returns:
      the Table

  - ### getVersion

    Version getVersion()
    Returns the Version for the row. The description of `Version` in its class description refers to its use in the `KVStore` interface. In `TableAPI` it it used as a return value for the various put methods as well as `TableAPI.putIfVersion(oracle.kv.table.Row, oracle.kv.Version, oracle.kv.table.ReturnRow, oracle.kv.table.WriteOptions)` and `TableAPI.deleteIfVersion(oracle.kv.table.PrimaryKey, oracle.kv.Version, oracle.kv.table.ReturnRow, oracle.kv.table.WriteOptions)` to perform conditional updates to allow an application to ensure that an update is occurring on the desired version of a row.
    Returns:
      the Version object if it has been initialized, null otherwise. The Version will only be set if the row was retrieved from the store.

  - ### createPrimaryKey

    PrimaryKey createPrimaryKey()
    Creates a PrimaryKey from this Row. The non-key fields are removed.
    Returns:
      the PrimaryKey

  - ### getTableVersion

    int getTableVersion()
    Returns the version of the table used to create this row if it has been deserialized from a get operation. If the row has been created and never been serialized the version returned is 0. New Table versions are created when a table is schema evolved. Tables start out with version 1 and it increments with each change. This method can be used by applications to help handle version changes.

  - ### equals

    boolean equals(Object other)
    Equality comparison for Row instances is based on equality of the individual field values and ignores the included `Version`, if present.
    Overrides:
      `equals` in class `Object`
    Returns:
      true if the objects are equal

  - ### clone

    Row clone()
    Returns a deep copy of this object.
    Specified by:
      `clone` in interface `FieldValue`
    Specified by:
      `clone` in interface `RecordValue`
    Returns:
      a deep copy of this object

  - ### setTTL

    void setTTL(TimeToLive ttl)
    Sets a time to live (TTL) value for the row to be used when the row is inserted into a store. If not set, or if the value is null, the table default value will be used. If no expiration time is desired, a TimeToLive instance of duration 0 should be used. The constant, `TimeToLive.DO_NOT_EXPIRE`, exists as a convenience for that purpose.

    It is recommended that the TimeToLive be constructed using `TimeToLive.ofDays(long)` to use less space in the store. If hours are needed then `TimeToLive.ofHours(long)` can be used at the expense of additional storage used.

    Parameters:
      `ttl` - the value to use, may be null
    Throws:
      `IllegalArgumentException` - if the TimeToLive is negative
    Since:
      4.0

  - ### getTTL

    TimeToLive getTTL()
    Returns the time to live (TTL) value for this row or null if it has not been set by a call to `setTTL(oracle.kv.table.TimeToLive)`. If this is null it means that the table default will be used on a put operation. The TTL property of a Row is used only on input. The expiration time of a Row is available on output, or after a put operation using `getExpirationTime()`.
    Returns:
      the TimeToLive for the row or null if not set
    Since:
      4.0

  - ### getExpirationTime

    long getExpirationTime()
    Returns the expiration time of the row. A zero value indicates that the row does not expire or has not yet been set. The expiration time is set if this row was returned by a get (e.g. `TableAPI.get(oracle.kv.table.PrimaryKey, oracle.kv.table.ReadOptions)`) or table iterator (e.g. `TableAPI.tableIterator(oracle.kv.table.PrimaryKey, oracle.kv.table.MultiRowOptions, oracle.kv.table.TableIteratorOptions)`) call. It will also be set after a successful put of the row (e.g. `TableAPI.put(oracle.kv.table.Row, oracle.kv.table.ReturnRow, oracle.kv.table.WriteOptions)`.
    Returns:
      the expiration time in milliseconds since January 1, 1970 GMT, or zero if the record never expires
    Since:
      4.0

  - ### getLastModificationTime

    long getLastModificationTime()
    Returns the last modification time of the row or zero if it is not available or not yet set. If the row was written by a version of the system older than 19.5 the last modification time will not be available at all and will be zero.

    The modification time is set if this row was returned by a get (e.g. `TableAPI.get(oracle.kv.table.PrimaryKey, oracle.kv.table.ReadOptions)`) or table iterator (e.g. `TableAPI.tableIterator(oracle.kv.table.PrimaryKey, oracle.kv.table.MultiRowOptions, oracle.kv.table.TableIteratorOptions)`) call. It will also be valid after a successful put of the row (e.g. `TableAPI.put(oracle.kv.table.Row, oracle.kv.table.ReturnRow, oracle.kv.table.WriteOptions)`).

    Returns:
      the last update time in milliseconds since January 1st, 1970 GMT or 0 if not available.
    Since:
      22.1

  - ### setRowMetadata

    void setRowMetadata(String rowMetadata)
    This method is **EXPERIMENTAL** and its behavior, signature, or even its existence may change without prior notice in future versions. Use with caution.

    Sets row metadata associated with the row (for insert or update operations) or primary key (for delete operations). Row metadata is associated to a certain version of a row. Any subsequent write operation will use its own row metadata value. If not specified null will be used by default. NOTE that if you have previously written a record with metadata and a subsequent write does not supply metadata, the metadata associated with the row will be null. Therefore, if you wish to have metadata associated with every write operation, you must supply a valid JSON construct to this method.

    Parameters:
      `rowMetadata` - the row metadata, must be null or a valid JSON construct: object, array, string, number, true, false or null, otherwise an IllegalArgumentException is thrown.
    Throws:
      `IllegalArgumentException` - if rowMetadata not null and invalid JSON Object format
    Since:
      25.3

  - ### getRowMetadata

    String getRowMetadata()
    This method is **EXPERIMENTAL** and its behavior, signature, or even its existence may change without prior notice in future versions. Use with caution.

    Returns the metadata associated with the row.

    Returns:
      the metadata, or null if not set
    Since:
      25.3