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

    Methods
    Modifier and Type | Method and 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`.
    `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.
    `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 fully-qualified name which includes its ancestor tables in a dot (".") separated path.
    `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.
    `String` | `getName()` Gets the name of the table.
    `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 Detail

    - #### 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

    - #### getName

          String getName()

      Gets the name of the table.
      Returns:
        the table name

    - #### getFullName

          String getFullName()

      Returns the table's fully-qualified name which includes its ancestor tables in a dot (".") separated path. For top-level tables this value is the same as the table name.
      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.
      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

    - #### 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

    - #### 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.

    - #### 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. 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

    - #### 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

    - #### clone

          Table clone()

      Clone the table.
      Returns:
        a deep copy of the table

Copyright (c) 2011, 2014 Oracle and/or its affiliates. All rights reserved.