Package oracle.kv.table

# Interface Table

public interface Table
Table is a handle on a table in the Oracle NoSQL Database. Tables are created in a store using administrative interfaces. The Table handle is obtained using `TableAPI.getTable(java.lang.String)` and `getChildTable(java.lang.String)`. Table contains immutable metadata for a table and acts as a factory for objects used in the `TableAPI` interface.

Tables are defined in terms of named fields where each field is defined by an instance of `FieldDef`. A single record in a table is called a `Row` and is uniquely identified by the table's `PrimaryKey`. The primary key is defined upon construction by an ordered list of fields. Tables also have a `shardKey` which is a proper subset of the primary key. A shard key has the property that all rows in a table that share the same shard key values are stored in the same partition and can be accessed transactionally. If not otherwise defined the shard key is the same as the table's primary key.

A table may be a top-level table, with no parent table, or a child table, which has a parent. A child table shares its parent table's primary key but adds its own fields to its primary key to uniquely identify child table rows. It is not possible to define a shard key on a child table. It inherits its parent table's shard key.

Since:
  3.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `childTableExists(String name)`
  Returns true if the named child table exists, false otherwise.
  `Table`
  `clone()`
  Clone the table.
  `FieldRange`
  `createFieldRange(String fieldName)`
  Creates a `FieldRange` object used to specify a value range for use in a table iteration operation in `TableAPI`.
  `MultiRowOptions`
  `createMultiRowOptions(List<String> tableNames, FieldRange fieldRange)`
  Returns a MultiRowOptions object initialized with ancestor and child tables from the list of table names and/or FieldRange.
  `PrimaryKey`
  `createPrimaryKey()`
  Creates an empty `PrimaryKey` for the table that can only hold fields that are part of the primary key for the table.
  `PrimaryKey`
  `createPrimaryKey(RecordValue value)`
  Creates a `PrimaryKey` for the table populated with relevant fields from the `RecordValue` parameter.
  `PrimaryKey`
  `createPrimaryKeyFromJson(InputStream jsonInput, boolean exact)`
  Creates a `PrimaryKey` based on JSON input.
  `PrimaryKey`
  `createPrimaryKeyFromJson(String jsonInput, boolean exact)`
  Creates a `PrimaryKey` based on JSON input.
  `ReturnRow`
  `createReturnRow(ReturnRow.Choice returnChoice)`
  Creates a ReturnRow object for the ReturnRow parameter in table put and delete methods in `TableAPI` such as `TableAPI.put(oracle.kv.table.Row, oracle.kv.table.ReturnRow, oracle.kv.table.WriteOptions)` and `TableAPI.delete(oracle.kv.table.PrimaryKey, oracle.kv.table.ReturnRow, oracle.kv.table.WriteOptions)`.
  `Row`
  `createRow()`
  Creates an empty Row for the table that can hold any field value.
  `Row`
  `createRow(RecordValue value)`
  Creates a Row for the table populated with relevant fields from the `RecordValue` parameter.
  `Row`
  `createRowFromJson(InputStream jsonInput, boolean exact)`
  Creates a Row based on JSON input.
  `Row`
  `createRowFromJson(String jsonInput, boolean exact)`
  Creates a Row based on JSON string input.
  `Row`
  `createRowWithDefaults()`
  Creates a Row using the default values for all fields.
  `Table`
  `getChildTable(String name)`
  Gets the named child table if it exists.
  `Map<String,Table>`
  `getChildTables()`
  Gets an unmodifiable view of all child tables of this table.
  `TimeToLive`
  `getDefaultTTL()`
  Returns the default TimeToLive for the table or null if not set.
  `FieldValue`
  `getDefaultValue(String name)`
  Creates an instance using the default value for the named field.
  `String`
  `getDescription()`
  Returns the table's description if present, otherwise null.
  `FieldDef`
  `getField(String name)`
  Returns the named field from the table definition, or null if the field does not exist.
  `List<String>`
  `getFields()`
  Returns an unmodifiable list of the field names of the table in declaration order which is done during table definition.
  `String`
  `getFullName()`
  Returns the table's full name which includes its ancestor tables in a dot (".") separated path.
  `String`
  `getFullNamespaceName()`
  Returns the table's full name which includes its ancestor tables in a dot (".") separated path, prefixed with the namespace in the format namespace:full-name for namespaces other than the "sysdefault" namespace.
  `Index`
  `getIndex(String indexName)`
  Gets the named index if it exists, null otherwise.
  `Map<String,Index>`
  `getIndexes()`
  Returns an unmodifiable map of all of the indexes on this table.
  `Map<String,Index>`
  `getIndexes(Index.IndexType type)`
  Returns an unmodifiable map of all of the indexes of the given type on this table.
  `String`
  `getName()`
  Gets the short name of the table.
  `String`
  `getNamespace()`
  Returns the namespace in which the table is defined.
  `Table`
  `getParent()`
  Returns the parent table, or null if this table has no parent.
  `List<String>`
  `getPrimaryKey()`
  Returns an unmodifable list of the field names that comprise the primary key for the table.
  `List<String>`
  `getShardKey()`
  Returns an unmodifable list of the shard key fields.
  `int`
  `getTableVersion()`
  Returns the current version of the table metadata.
  `Table`
  `getVersion(int version)`
  Gets the specified version of the table.
  `boolean`
  `isNullable(String name)`
  Returns true if the named field is nullable.
  `int`
  `numTableVersions()`
  Returns the number of versions of this table that exist.

- ## Method Details

  - ### getChildTable

    Table getChildTable(String name)
    Gets the named child table if it exists. The name must specify a direct child of this table. Null is returned if the table does not exist.
    Parameters:
      `name` - the table name for the desired table
    Returns:
      the child table or null

  - ### childTableExists

    boolean childTableExists(String name)
    Returns true if the named child table exists, false otherwise. The name must specify a direct child of this table.
    Parameters:
      `name` - the table name for the desired table
    Returns:
      true if the child table exists, false otherwise

  - ### getChildTables

    Map<String,Table> getChildTables()
    Gets an unmodifiable view of all child tables of this table. Only direct child tables are returned. If no child tables exist an empty map is returned.
    Returns:
      the map of child tables, which may be empty

  - ### getParent

    Table getParent()
    Returns the parent table, or null if this table has no parent.
    Returns:
      the parent table or null

  - ### getTableVersion

    int getTableVersion()
    Returns the current version of the table metadata. Each time a table is evolved its version number will increment. A table starts out at version 1.
    Returns:
      the version of the table

  - ### getVersion

    Table getVersion(int version)
    Gets the specified version of the table. This allows an application to use an older version of a table if it is not prepared to use the latest version (the default). Table versions change when a table is evolved by adding or removing fields. Most applications should use the default (latest) version if at all possible.

    The version must be a valid version between 0 and the value of `numTableVersions()`. If the version is 0 the latest version is used. Actual version numbers begin with 1.

    Parameters:
      `version` - the version to use
    Returns:
      the requested table
    Throws:
      `IllegalArgumentException` - if the requested version number is negative or out of range of the known versions

  - ### numTableVersions

    int numTableVersions()
    Returns the number of versions of this table that exist. Versions are identified by integer, starting with 1. Versions are added if the table is modified (evolved) with each new version getting the next integer.

    By default when a table is accessed its current (latest) version will be used. It is possible to see an earlier or later version using `getVersion(int)`.

    Returns:
      the number of table versions

  - ### getIndex

    Index getIndex(String indexName)
    Gets the named index if it exists, null otherwise.
    Parameters:
      `indexName` - the name of the index
    Returns:
      the index or null

  - ### getIndexes

    Map<String,Index> getIndexes()
    Returns an unmodifiable map of all of the indexes on this table. If there are no indexes defined an empty map is returned.
    Returns:
      a map of indexes

  - ### getIndexes

    Map<String,Index> getIndexes(Index.IndexType type)
    Returns an unmodifiable map of all of the indexes of the given type on this table. If there are no such indexes defined, an empty map is returned.
    Returns:
      a map of indexes
    Since:
      3.5

  - ### getName

    String getName()
    Gets the short name of the table. If this is a child table only the last component of the full name is returned.
    Returns:
      the last component of the full table name

  - ### getFullName

    String getFullName()
    Returns the table's full name which includes its ancestor tables in a dot (".") separated path. For top-level tables this value is the same as the table name. It doesn't include any namespace component.
    Returns:
      the full table name

  - ### getDescription

    String getDescription()
    Returns the table's description if present, otherwise null. This is a description of the table that is optionally supplied during definition of the table.
    Returns:
      the description or null

  - ### getFields

    List<String> getFields()
    Returns an unmodifiable list of the field names of the table in declaration order which is done during table definition. This will never be empty.

    If the table is a JSON Collection the fields will be those defined in the primary key.

    Returns:
      the fields

  - ### getField

    FieldDef getField(String name)
    Returns the named field from the table definition, or null if the field does not exist.
    Returns:
      the field or null

  - ### isNullable

    boolean isNullable(String name)
    Returns true if the named field is nullable.
    Parameters:
      `name` - the name of the field
    Returns:
      true if the named field is nullable
    Throws:
      `IllegalArgumentException` - if the named field does not exist in the table definition

  - ### getDefaultValue

    FieldValue getDefaultValue(String name)
    Creates an instance using the default value for the named field. The return value is `FieldValue` and not a more specific type because in the case of nullable fields the default will be a null value, which is a special value that returns true for `isNullable(java.lang.String)`.
    Parameters:
      `name` - the name of the field
    Returns:
      a default value
    Throws:
      `IllegalArgumentException` - if the named field does not exist in the table definition

  - ### getPrimaryKey

    List<String> getPrimaryKey()
    Returns an unmodifable list of the field names that comprise the primary key for the table. This will never be null.
    Returns:
      the list of fields

  - ### getShardKey

    List<String> getShardKey()
    Returns an unmodifable list of the shard key fields. This is a strict subset of the primary key. This will never be null.
    Returns:
      the list of fields

  - ### createRow

    Row createRow()
    Creates an empty Row for the table that can hold any field value.
    Returns:
      an empty row

  - ### createRow

    Row createRow(RecordValue value)
    Creates a Row for the table populated with relevant fields from the `RecordValue` parameter. Only fields that belong in this table are added. Other fields are silently ignored.
    Parameters:
      `value` - a RecordValue instance containing fields that may or may not be applicable to this table
    Returns:
      the row
    Throws:
      `IllegalArgumentException` - if the input is an instance of `IndexKey`. The definition of IndexKey does not match that of the table's Row.
      `IllegalArgumentException` - if the table is a JSON collection.

  - ### createRowWithDefaults

    Row createRowWithDefaults()
    Creates a Row using the default values for all fields. This includes the primary key fields which are not allowed to be defaulted in put operations.
    Returns:
      a new row
    Throws:
      `IllegalArgumentException` - if the table is a JSON collection.

  - ### createPrimaryKey

    PrimaryKey createPrimaryKey()
    Creates an empty `PrimaryKey` for the table that can only hold fields that are part of the primary key for the table. Other fields will be rejected if an attempt is made to set them on the returned object.
    Returns:
      an empty primary key

  - ### createPrimaryKey

    PrimaryKey createPrimaryKey(RecordValue value)
    Creates a `PrimaryKey` for the table populated with relevant fields from the `RecordValue` parameter. Only fields that belong in this primary key are added. Other fields are silently ignored.
    Parameters:
      `value` - a `RecordValue` instance containing fields that may or may not be applicable to this table's primary key. Only fields that belong in the key are added.
    Throws:
      `IllegalArgumentException` - if the input is an instance of `IndexKey`. The definition of IndexKey does not match that of the table's PrimaryKey.

  - ### createReturnRow

    ReturnRow createReturnRow(ReturnRow.Choice returnChoice)
    Creates a ReturnRow object for the ReturnRow parameter in table put and delete methods in `TableAPI` such as `TableAPI.put(oracle.kv.table.Row, oracle.kv.table.ReturnRow, oracle.kv.table.WriteOptions)` and `TableAPI.delete(oracle.kv.table.PrimaryKey, oracle.kv.table.ReturnRow, oracle.kv.table.WriteOptions)`.
    Parameters:
      `returnChoice` - describes the state to return
    Returns:
      a `ReturnRow` containing the choice passed in the parameter

  - ### createRowFromJson

    Row createRowFromJson(String jsonInput, boolean exact)
    Creates a Row based on JSON string input. If the `exact` parameter is true the input string must contain an exact match to the table row, including all fields, required or not. It must not have additional data. If false, only matching fields will be added and the input may have additional, unrelated data.
    Parameters:
      `jsonInput` - a JSON string
      `exact` - set to true for an exact match. See above
    Throws:
      `IllegalArgumentException` - if exact is true and a field is missing or extra. It will also be thrown if a field type or value is not correct
      `IllegalArgumentException` - if the input is malformed

  - ### createRowFromJson

    Row createRowFromJson(InputStream jsonInput, boolean exact)
    Creates a Row based on JSON input.

    For a table with normal schema (i.e. not a JSON collection) If the `exact` parameter is true the input string must contain an exact match to the table row, including all fields, required or not. It must not have additional data. If false, only matching fields will be added and the input may have additional, unrelated data.

    For a JSON Collection table all fields are put into the row. If `exact` is true all primary key fields must be set or an exception is thrown.

    Parameters:
      `jsonInput` - a JSON string
      `exact` - set to true for an exact match. See above
    Throws:
      `IllegalArgumentException` - if exact is true and a field is missing or extra. It will also be thrown if a field type or value is not correct
      `IllegalArgumentException` - if the input is malformed

  - ### createPrimaryKeyFromJson

    PrimaryKey createPrimaryKeyFromJson(String jsonInput, boolean exact)
    Creates a `PrimaryKey` based on JSON input. If the `exact` parameter is true the input string must contain an exact match to the primary key, including all fields, required or not. It must not have additional data. If false, only matching fields will be added and the input may have additional, unrelated data.
    Parameters:
      `jsonInput` - a JSON string
      `exact` - set to true for an exact match. See above
    Throws:
      `IllegalArgumentException` - if exact is true and a field is missing or extra. It will also be thrown if a field type or value is not correct
      `IllegalArgumentException` - if the input is malformed

  - ### createPrimaryKeyFromJson

    PrimaryKey createPrimaryKeyFromJson(InputStream jsonInput, boolean exact)
    Creates a `PrimaryKey` based on JSON input. If the `exact` parameter is true the input string must contain an exact match to the primary key, including all fields, required or not. It must not have additional data. If false, only matching fields will be added and the input may have additional, unrelated data.
    Parameters:
      `jsonInput` - a JSON string
      `exact` - set to true for an exact match. See above
    Throws:
      `IllegalArgumentException` - if exact is true and a field is missing or extra. It will also be thrown if a field type or value is not correct
      `IllegalArgumentException` - if the input is malformed

  - ### createFieldRange

    FieldRange createFieldRange(String fieldName)
    Creates a `FieldRange` object used to specify a value range for use in a table iteration operation in `TableAPI`.
    Parameters:
      `fieldName` - the name of the field from the PrimaryKey to use for the range
    Returns:
      an empty `FieldRange` based on the table and field
    Throws:
      `IllegalArgumentException` - if the field is not defined in the table's primary key

  - ### createMultiRowOptions

    MultiRowOptions createMultiRowOptions(List<String> tableNames, FieldRange fieldRange)
    Returns a MultiRowOptions object initialized with ancestor and child tables from the list of table names and/or FieldRange.
    Parameters:
      `tableNames` - an optional list of fully-qualified table names to include in results, or null. This list must not include the name of this (the target) table.
      `fieldRange` - an optional FieldRange to be used in construction of MultiRowOptions, or null.
    Throws:
      `IllegalArgumentException` - if neither parameter has information or this table is included in the list of table names.

  - ### clone

    Table clone()
    Clone the table.
    Returns:
      a deep copy of the table

  - ### getDefaultTTL

    TimeToLive getDefaultTTL()
    Returns the default TimeToLive for the table or null if not set. This default TTL is applied when a row is put without an explicit TTL value. If the default is not set and a row is put without an explicit TTL the row does not expire.
    Returns:
      the default TimeToLive or null
    Since:
      4.0

  - ### getNamespace

    String getNamespace()
    Returns the namespace in which the table is defined. Note that the "sysdefault" namespace will return `TableAPI.SYSDEFAULT_NAMESPACE_NAME`.
    Returns:
      the namespace for the table
    Since:
      18.3

  - ### getFullNamespaceName

    String getFullNamespaceName()
    Returns the table's full name which includes its ancestor tables in a dot (".") separated path, prefixed with the namespace in the format namespace:full-name for namespaces other than the "sysdefault" namespace. For tables created in the "sysdefault" namespace, the return value just contains the full name without a namespace prefix.
    Returns:
      the namespace qualified table name
    Since:
      18.3