Package oracle.kv.table

Class MultiRowOptions

java.lang.Object
oracle.kv.table.MultiRowOptions
public class MultiRowOptions extends Object
Defines parameters used in multi-row operations. A multi-row operation selects rows from at least one table, called the target table, and optionally selects rows from its ancestor and descendant tables.

The target table is defined by the PrimaryKey or IndexKey passed as the first parameter of the multi-row method. These include

By default only matching records from the target table are returned or deleted. MultiRowOptions can be used to specify whether the operation should affect (return or delete) records from ancestor and/or descendant tables for matching records. In addition MultiRowOptions can be used to specify sub-ranges within a table or index for all operations it supports using FieldRange.

When results from multiple tables are returned they are always returned with results from ancestor tables first even if the iteration is in reverse order or unordered. In this case results from multiple tables are mixed. Because an index iteration can result in multiple index entries matching the same primary record it is possible to get duplicate return values for those records as well as specified ancestor tables. It is not valid to specify child tables for index operations. It is up to the caller to handle duplicates and filter results from multiple tables.

The ability to return ancestor and child table rows and keys is useful and can avoid additional calls from the client but it comes at a cost and should be used only when necessary. In the case of ancestor tables it means verification or fetching of the ancestor row. In the case of child tables it means that the iteration cannot end until it has scanned all child table records which may involve iteration over uninteresting records.

Since:
3.0

  • Constructor Details

    • MultiRowOptions

      public MultiRowOptions(FieldRange fieldRange, List<Table> ancestors, List<Table> children)
      Full constructor requiring all members.

    • MultiRowOptions

      public MultiRowOptions(FieldRange fieldRange)
      A convenience constructor that takes only FieldRange.

  • Method Details

    • getFieldRange

      public FieldRange getFieldRange()
      Gets the FieldRange to be used to restrict the range of the operation.
      Returns:
      the range or null if not set

    • getIncludedParentTables

      public List<Table> getIncludedParentTables()
      Gets the list of ancestor tables to be included in an operation that returns multiple rows or keys.
      Returns:
      the list or null if none have been set

    • getIncludedChildTables

      public List<Table> getIncludedChildTables()
      Gets the list of child tables to be included in an operation that returns multiple rows or keys.
      Returns:
      the list or null if none have been set

    • setFieldRange

      public MultiRowOptions setFieldRange(FieldRange newFieldRange)
      Restricts the selected rows to those matching a range of field values for the first unspecified field in the target key.

      The first unspecified key field is defined as the first key field following the fields in a partial target key, or the very first key field when a null target key is specified.

      This method may only be used when a partial or null target key is specified. If a complete target key is given, this member must be null.

      Parameters:
      newFieldRange - the range to use
      Returns:
      this

    • setIncludedParentTables

      public MultiRowOptions setIncludedParentTables(List<Table> newAncestors)
      Specifies the parent (ancestor) tables for which rows are selected by the operation.

      Each table must be an ancestor table (parent, grandparent, etc.) of the target table.

      A row selected from a parent table will have that row's complete primary key, which is a partial primary key for the row selected from the target table. At most one row from each parent table will be selected for each selected target table row.

      Rows from a parent table are always returned before rows from its child tables. This is the case for both forward and reverse iterations.

      For an index method, fetching the parent table rows requires additional operations per selected index key. Redundant fetches (when multiple selected target table rows have the same parent) can be avoided by maintaining and checking a set of already selected keys.

      Parameters:
      newAncestors - the list to set
      Returns:
      this

    • setIncludedChildTables

      public MultiRowOptions setIncludedChildTables(List<Table> newChildren)
      Specifies the child (descendant) tables for which rows are selected by the operation.

      Each child table must be an descendant table (child, grandchild, great- grandchild, etc.) of the target table.

      The rows selected from each child table will have key field values matching those in the key of a selected target table row. Multiple child table rows may be selected for each selected target table row.

      Rows from a parent table are always returned before rows from its child tables for forward iteration. Reverse iterations will return child rows first.

      Child tables may not be specified for inclusion in an index operation.

      Parameters:
      newChildren - the list to set
      Returns:
      this