public interface TableAPI
key/value interface
. While the two interfaces
are not incompatible, in general applications will use one or the other.
To create a TableAPI instance use getTableAPI()
.
The table interface is required to use secondary indexes and supported data types.
Tables are similar to tables in a relational database. They are named and
contain a set of strongly typed records, called rows. Rows in an Oracle
NoSQL Database table are analogous to rows in a relational system and each
row has one or more named, typed data values. These fields can be compared
to a relational database column. A single top-level row in a table is
contained in a Row
object. Row is used as return value for TableAPI
get operations as well as a key plus value object for TableAPI put
operations. All rows in a given table have the same fields. Tables have a
well-defined primary key which comprises one or more of its fields, in
order. Primary key fields must be simple (single-valued) data types.
The data types supported in tables are well-defined and include simple single-valued types such as Integer, String, Date, etc., in addition to several complex, multi-valued types -- Array, Map, and Record. Complex objects allow for creation of arbitrarily complex, nested rows.
All operations on this interface include parameters that supply optional arguments to control non-default behavior. The types of these parameter objects varies depending on whether the operation is a read, update, or a multi-read style operation returning more than one result or an iterator.
In order to control, and take advantage of sharding across partitions tables may be defined in a hierarchy. A top-level table is one without a parent and may be defined in a way such that its primary key spreads the table rows across partitions. The primary key for this sort of table has a complete shard key but an empty minor key. Tables with parents always have a primary key with a minor key. The primary key of a child table comprises the primary key of its immediate parent plus the fields defined in the child table as being part of its primary key. This means that the fields of a child table implicitly include the primary key fields of all of its ancestors.
Some of the methods in this interface include MultiRowOptions
which
can be used to cause operations to return not only rows from the target
table but from its ancestors and descendant tables as well. This allows
for efficient and transactional mechanisms to return related groups of rows.
The MultiRowOptions object is also used to specify value ranges that apply
to the operation.
Modifier and Type | Method and Description |
---|---|
boolean |
delete(PrimaryKey key,
ReturnRow prevRow,
WriteOptions writeOptions)
Deletes a row from a table.
|
boolean |
deleteIfVersion(PrimaryKey key,
Version matchVersion,
ReturnRow prevRow,
WriteOptions writeOptions)
Deletes a row from a table but only if its version matches the one
specified in matchVersion.
|
List<TableOperationResult> |
execute(List<TableOperation> operations,
WriteOptions writeOptions)
This method provides an efficient and transactional mechanism for
executing a sequence of operations associated with tables that share the
same shard key portion of their primary keys.
|
Row |
get(PrimaryKey key,
ReadOptions readOptions)
Gets the
Row associated with the primary key. |
Table |
getTable(String tableName)
Gets an instance of a table.
|
TableOperationFactory |
getTableOperationFactory()
Returns a
TableOperationFactory to create operations passed
to execute(java.util.List<oracle.kv.table.TableOperation>, oracle.kv.table.WriteOptions) . |
Map<String,Table> |
getTables()
Gets all known tables.
|
int |
multiDelete(PrimaryKey key,
MultiRowOptions getOptions,
WriteOptions writeOptions)
Deletes multiple rows from a table in an atomic operation.
|
List<Row> |
multiGet(PrimaryKey key,
MultiRowOptions getOptions,
ReadOptions readOptions)
Returns the rows associated with a partial primary key in an
atomic manner.
|
List<PrimaryKey> |
multiGetKeys(PrimaryKey key,
MultiRowOptions getOptions,
ReadOptions readOptions)
Return the rows associated with a partial primary key in an
atomic manner.
|
Version |
put(Row row,
ReturnRow prevRow,
WriteOptions writeOptions)
Puts a row into a table.
|
Version |
putIfAbsent(Row row,
ReturnRow prevRow,
WriteOptions writeOptions)
Puts a row into a table, but only if the row does not exist.
|
Version |
putIfPresent(Row row,
ReturnRow prevRow,
WriteOptions writeOptions)
Puts a row into a table, but only if the row already exists.
|
Version |
putIfVersion(Row row,
Version matchVersion,
ReturnRow prevRow,
WriteOptions writeOptions)
Puts a row, but only if the version of the existing row matches the
matchVersion argument.
|
TableIterator<Row> |
tableIterator(IndexKey key,
MultiRowOptions getOptions,
TableIteratorOptions iterateOptions)
Returns an iterator over the rows associated with an index key.
|
TableIterator<Row> |
tableIterator(PrimaryKey key,
MultiRowOptions getOptions,
TableIteratorOptions iterateOptions)
Returns an iterator over the rows associated with a partial primary key.
|
TableIterator<KeyPair> |
tableKeysIterator(IndexKey key,
MultiRowOptions getOptions,
TableIteratorOptions iterateOptions)
Return the keys for matching rows associated with an index key.
|
TableIterator<PrimaryKey> |
tableKeysIterator(PrimaryKey key,
MultiRowOptions getOptions,
TableIteratorOptions iterateOptions)
Returns an iterator over the keys associated with a partial primary key.
|
Table getTable(String tableName) throws FaultException
This interface will only retrieve top-level tables -- those with no
parent table. Child tables are retrieved using
Table.getChildTable(java.lang.String)
.
tableName
- the name of the target tableFaultException
- if the operation fails to communicate with a
server node that has the table metadataMap<String,Table> getTables() throws FaultException
Table.getChildTables()
.FaultException
- if the operation fails to communicate with a
server node that has the table metadataRow get(PrimaryKey key, ReadOptions readOptions) throws ConsistencyException, RequestTimeoutException, FaultException
Row
associated with the primary key.key
- the primary key for a table. It must be a complete primary
key, with all fields set.readOptions
- non-default options for the operation or null to
get default behaviorConsistencyException
- if the specified Consistency
cannot
be satisfiedRequestTimeoutException
- if the request timeout interval was
exceededFaultException
- if the operation cannot be completed for any
reasonIllegalArgumentException
- if the primary key is not completeList<Row> multiGet(PrimaryKey key, MultiRowOptions getOptions, ReadOptions readOptions) throws ConsistencyException, RequestTimeoutException, FaultException
key
- the primary key for the operation. It may be partial or
complete.getOptions
- a MultiRowOptions
object used to control
ranges in the operation and whether ancestor and descendant tables are
included in the results. It may be null. The table used to construct
the PrimaryKey
parameter is always included as a target.readOptions
- non-default options for the operation or null to
get default behaviorConsistencyException
- if the specified Consistency
cannot
be satisfiedRequestTimeoutException
- if the request timeout interval was
exceededFaultException
- if the operation cannot be completed for any
reasonIllegalArgumentException
- if the primary key is malformed or
does not contain the required fieldsList<PrimaryKey> multiGetKeys(PrimaryKey key, MultiRowOptions getOptions, ReadOptions readOptions) throws ConsistencyException, RequestTimeoutException, FaultException
key
- the primary key for the operation. It may be partial or
completegetOptions
- a MultiRowOptions
object used to control
ranges in the operation and whether ancestor and descendant tables are
included in the results. It may be null. The table used to construct
the PrimaryKey
parameter is always included as a target.readOptions
- non-default options for the operation or null to
get default behaviorConsistencyException
- if the specified Consistency
cannot
be satisfiedRequestTimeoutException
- if the request timeout interval was
exceededFaultException
- if the operation cannot be completed for any
reasonIllegalArgumentException
- if the primary key is malformed or
does not contain the required fieldsTableIterator<Row> tableIterator(PrimaryKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions) throws ConsistencyException, RequestTimeoutException, FaultException
key
- the primary key for the operation. It may be partial or
complete shard key. If the key contains a partial shard key the
iteration goes to all partitions in the store. If the key contains a
complete shard key the operation is restricted to the target partition.
If the key has no fields set the entire table is matched.getOptions
- a MultiRowOptions
object used to control
ranges in the operation and whether ancestor and descendant tables are
included in the results. It may be null. The table used to construct
the PrimaryKey
parameter is always included as a target.iterateOptions
- the non-default arguments for consistency of the
operation and to control the iteration or null to get default behavior.
The default Direction in TableIteratorOptions
is
Direction.UNORDERED
. If the primary key contains a complete
shard key both Direction.FORWARD
and Direction.REVERSE
are allowed, otherwise the direction must be defaulted or
Direction.UNORDERED
.ParallelScanIterator
,
such as statistics, will not return meaningful information because the
iteration will be single-partition and not parallel.ConsistencyException
- if the specified Consistency
cannot
be satisfiedRequestTimeoutException
- if the request timeout interval was
exceededFaultException
- if the operation cannot be completed for any
reasonIllegalArgumentException
- if the primary key is malformed or an
invalid option is specified, such as iteration order without a complete
shard key.TableIterator<PrimaryKey> tableKeysIterator(PrimaryKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions) throws ConsistencyException, RequestTimeoutException, FaultException
key
- the primary key for the operation. It may be partial or
complete shard key. If the key contains a partial shard key the
iteration goes to all partitions in the store. If the key contains a
complete shard key the operation is restricted to the target partition.
If the key has no fields set the entire table is matched.getOptions
- a MultiRowOptions
object used to control
ranges in the operation and whether ancestor and descendant tables are
included in the results. It may be null. The table used to construct
the PrimaryKey
parameter is always included as a target.iterateOptions
- the non-default arguments for consistency of the
operation and to control the iteration or null to get default behavior.
The default Direction in TableIteratorOptions
is
Direction.UNORDERED
. If the primary key contains a complete
shard key both Direction.FORWARD
and Direction.REVERSE
are allowed, otherwise the direction must be defaulted or
Direction.UNORDERED
.ParallelScanIterator
, such as statistics, will not return meaningful
information because the iteration will be single-partition and not
parallel.ConsistencyException
- if the specified Consistency
cannot
be satisfiedRequestTimeoutException
- if the request timeout interval was
exceededFaultException
- if the operation cannot be completed for any
reasonIllegalArgumentException
- if the primary key is malformed or an
invalid option is specified, such as iteration order without a complete
shard key.TableIterator<Row> tableIterator(IndexKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions) throws ConsistencyException, RequestTimeoutException, FaultException
getOptions
paramter. Index operations may not specify the
return of child table rows.key
- the index key for the operation. It may be partial or
complete. If the key has no fields set the entire index is matched.getOptions
- a MultiRowOptions
object used to control
ranges in the operation and whether ancestor and descendant tables are
included in the results. It may be null. The table on which the
index is defined is always included as a target. Child tables cannot
be included for index operations.iterateOptions
- the non-default arguments for consistency of the
operation and to control the iteration or null to get default behavior.
The default Direction in TableIteratorOptions
is
Direction.FORWARD
.ConsistencyException
- if the specified Consistency
cannot
be satisfiedRequestTimeoutException
- if the request timeout interval was
exceededFaultException
- if the operation cannot be completed for any
reasonIllegalArgumentException
- if the primary key is malformedUnsupportedOperationException
- if the getOptions
parameter specifies the return of child tablesTableIterator<KeyPair> tableKeysIterator(IndexKey key, MultiRowOptions getOptions, TableIteratorOptions iterateOptions) throws ConsistencyException, RequestTimeoutException, FaultException
getOptions
paramter. Index operations may not specify the
return of child table keys.key
- the index key for the operation. It may be partial or
complete. If the key has no fields set the entire index is matched.getOptions
- a MultiRowOptions
object used to control
ranges in the operation and whether ancestor and descendant tables are
included in the results. It may be null. The table on which the
index is defined is always included as a target. Child tables cannot
be included for index operations.iterateOptions
- the non-default arguments for consistency of the
operation and to control the iteration or null to get default behavior.
The default Direction in TableIteratorOptions
is
Direction.FORWARD
.KeyPair
objects, which provide access
to both the PrimaryKey
associated with a match but the values
in the matching IndexKey
as well without an additional fetch of
the Row itself.ConsistencyException
- if the specified Consistency
cannot
be satisfiedRequestTimeoutException
- if the request timeout interval was
exceededFaultException
- if the operation cannot be completed for any
reasonIllegalArgumentException
- if the primary key is malformedUnsupportedOperationException
- if the getOptions
parameter specifies the return of child tablesVersion put(Row row, ReturnRow prevRow, WriteOptions writeOptions) throws DurabilityException, RequestTimeoutException, FaultException
row
- the row to putprevRow
- a ReturnRow
object to contain the previous row
value and version associated with the given row, or null if they should
not be returned. If a previous row does not exist, or the ReturnRow.Choice
specifies that they should not be returned, the
version in this object is set to null and none of the row's fields are
available.writeOptions
- non-default arguments controlling the
durability of the operation, or null to get default behavior.
See WriteOptions
for more information.DurabilityException
- if the specified Durability
cannot
be satisfiedRequestTimeoutException
- if the request timeout interval was
exceededFaultException
- if the operation cannot be completed for any
reasonIllegalArgumentException
- if the row
does not have
a complete primary key or is otherwise invalidVersion putIfAbsent(Row row, ReturnRow prevRow, WriteOptions writeOptions) throws DurabilityException, RequestTimeoutException, FaultException
row
- the row to putprevRow
- a ReturnRow
object to contain the previous row
value and version associated with the given row, or null if they should
not be returned. If a previous row does not exist, or the ReturnRow.Choice
specifies that they should not be returned, the
version in this object is set to null and none of the row's fields are
available.writeOptions
- non-default arguments controlling the
durability of the operation, or null to get default behavior.DurabilityException
- if the specified Durability
cannot
be satisfiedRequestTimeoutException
- if the request timeout interval was
exceededFaultException
- if the operation cannot be completed for any
reasonIllegalArgumentException
- if the row
does not have
a complete primary key or is otherwise invalidVersion putIfPresent(Row row, ReturnRow prevRow, WriteOptions writeOptions) throws DurabilityException, RequestTimeoutException, FaultException
row
- the row to putprevRow
- a ReturnRow
object to contain the previous row
value and version associated with the given row, or null if they should
not be returned. If a previous row does not exist, or the ReturnRow.Choice
specifies that they should not be returned, the
version in this object is set to null and none of the row's fields are
available.writeOptions
- non-default arguments controlling the
durability of the operation, or null to get default behavior.DurabilityException
- if the specified Durability
cannot
be satisfiedRequestTimeoutException
- if the request timeout interval was
exceededFaultException
- if the operation cannot be completed for any
reasonIllegalArgumentException
- if the Row
does not have
a complete primary key or is otherwise invalid.Version putIfVersion(Row row, Version matchVersion, ReturnRow prevRow, WriteOptions writeOptions) throws DurabilityException, RequestTimeoutException, FaultException
row
- the row to putmatchVersion
- the version to matchprevRow
- a ReturnRow
object to contain the previous row
value and version associated with the given row, or null if they should
not be returned. If a previous row does not exist, or the ReturnRow.Choice
specifies that they should not be returned, the
version in this object is set to null and none of the row's fields are
available.writeOptions
- non-default arguments controlling the
durability of the operation, or null to get default behavior.DurabilityException
- if the specified Durability
cannot
be satisfiedRequestTimeoutException
- if the request timeout interval was
exceededFaultException
- if the operation cannot be completed for any
reasonIllegalArgumentException
- if the Row
does not have
a complete primary key or is otherwise invalidboolean delete(PrimaryKey key, ReturnRow prevRow, WriteOptions writeOptions) throws DurabilityException, RequestTimeoutException, FaultException
key
- the primary key for the row to deleteprevRow
- a ReturnRow
object to contain the previous row
value and version associated with the given row, or null if they should
not be returned. If a previous row does not exist, or the ReturnRow.Choice
specifies that they should not be returned, the
version in this object is set to null and none of the row's fields are
available.writeOptions
- non-default arguments controlling the
durability of the operation, or null to get default behavior.DurabilityException
- if the specified Durability
cannot
be satisfiedRequestTimeoutException
- if the request timeout interval was
exceededFaultException
- if the operation cannot be completed for any
reasonIllegalArgumentException
- if the primary key is not completeboolean deleteIfVersion(PrimaryKey key, Version matchVersion, ReturnRow prevRow, WriteOptions writeOptions) throws DurabilityException, RequestTimeoutException, FaultException
key
- the primary key for the row to deletematchVersion
- the version to matchprevRow
- a ReturnRow
object to contain the previous row
value and version associated with the given row, or null if they should
not be returned. If a previous row does not exist, or the ReturnRow.Choice
specifies that they should not be returned, or
the matchVersion parameter matches the existing value and the delete is
successful, the version in this object is set to null and none of the
row's fields are available.writeOptions
- non-default arguments controlling the
durability of the operation, or null to get default behavior.DurabilityException
- if the specified Durability
cannot
be satisfiedRequestTimeoutException
- if the request timeout interval was
exceededFaultException
- if the operation cannot be completed for any
reasonIllegalArgumentException
- if the primary key is not completeint multiDelete(PrimaryKey key, MultiRowOptions getOptions, WriteOptions writeOptions) throws DurabilityException, RequestTimeoutException, FaultException
key
- the primary key for the row to deletegetOptions
- a MultiRowOptions
object used to control
ranges in the operation and whether ancestor and descendant tables are
included in the operation. It may be null. The table used to construct
the PrimaryKey
parameter is always included as a target.writeOptions
- non-default arguments controlling the
durability of the operation, or null to get default behavior.DurabilityException
- if the specified Durability
cannot
be satisfiedRequestTimeoutException
- if the request timeout interval was
exceededFaultException
- if the operation cannot be completed for any
reasonIllegalArgumentException
- if the primary key is malformed or does
not contain all shard key fieldsTableOperationFactory getTableOperationFactory()
TableOperationFactory
to create operations passed
to execute(java.util.List<oracle.kv.table.TableOperation>, oracle.kv.table.WriteOptions)
. Not all operations must use the same table but
they must all use the same shard portion of the primary key.TableOperationFactory
List<TableOperationResult> execute(List<TableOperation> operations, WriteOptions writeOptions) throws OperationExecutionException, DurabilityException, FaultException
The operations passed to this method are created using an TableOperationFactory
, which is obtained from the getTableOperationFactory()
method.
All the operations
specified are executed within the scope of a
single transaction that effectively provides serializable isolation.
The transaction is started and either committed or aborted by this
method. If the method returns without throwing an exception, then all
operations were executed atomically, the transaction was committed, and
the returned list contains the result of each operation.
If the transaction is aborted for any reason, an exception is thrown. An abort may occur for two reasons:
FaultException
is thrown.true
was passed for the abortIfUnsuccessful
parameter when the operation was created using
the TableOperationFactory
.
An OperationExecutionException
is thrown, and the exception contains information about the failed
operation.
Operations are not executed in the sequence they appear the operations
list, but are rather executed in an internally defined
sequence that prevents deadlocks. Additionally, if there are two
operations for the same key, their relative order of execution is
arbitrary; this should be avoided.
operations
- the list of operations to be performed. Note that all
operations in the list must specify primary keys with the same
complete shard key.writeOptions
- non-default arguments controlling the
durability of the operation, or null to get default behavior.OperationExecutionException
- if an operation is not successful as
defined by the particular operation (e.g., a delete operation for a
non-existent key) and true
was passed for the abortIfUnsuccessful
parameter when the operation was created using the
TableOperationFactory
.DurabilityException
- if the specified Durability
cannot
be satisfiedRequestTimeoutException
- if the request timeout interval was
exceededFaultException
- if the operation cannot be completed for any
reasonIllegalArgumentException
- if operations is null or empty, or not
all operations operate on primary keys with the same shard key, or more
than one operation has the same primary key, or any of the primary keys
are incomplete.Copyright (c) 2011, 2014 Oracle and/or its affiliates. All rights reserved.