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 all child tables of this table.
FieldValue	getDefaultValue(String name) Creates an instance using the default value for the named field.
String	getDescription() Gets 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 the field names of the table in declaration order which is done during table definition.
String	getFullName() Gets 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 a 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 a list of the field names that comprise the primary key for the table.
List<String>	getShardKey() Returns 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 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 a 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()

Gets 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()

Gets 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 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 a 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 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