Module org.cojen.tupl
Package org.cojen.tupl

Interface Table<R>

All Superinterfaces:
AutoCloseable, Closeable
public interface Table<R> extends Closeable
Defines a relational collection of persistent rows. A row is defined by an interface consisting of accessor/mutator methods corresponding to each column:

Supported column types:

  • Simple objects — String, BigInteger, and BigDecimal
  • Primitives — int, double, etc
  • Boxed primitives — Integer, Double, etc
  • Primitive arrays — int[], double[], etc
By default, object columns cannot be set to null, and attempting to do so causes an IllegalArgumentException to be thrown. The column definition must be annotated with @Nullable to support nulls.

The actual row implementation class is generated at runtime, and the standard equals, hashCode, toString, and clone methods are automatically generated as well. If the row interface declares a clone method which returns the exact row type, then the row can be cloned without requiring an explicit cast. If the row interface extends Comparable, then rows are comparable by primary key. Any default methods defined in the row interface are never overridden by the generated class, unless the method is defined in the Object class.

Scans over the rows of the table can be reduced by a query, described by this syntax: 


 Query        = RowFilter
              | Projection [ RowFilter ]
 RowFilter    = AndFilter { "||" AndFilter }
 AndFilter    = EntityFilter { "&&" EntityFilter }
 EntityFilter = ColumnFilter | ParenFilter
 ParenFilter  = [ "!" ] "(" RowFilter ")"
 ColumnFilter = ColumnName RelOp ( ArgRef | ColumnName )
              | ColumnName "in" ArgRef
 RelOp        = "==" | "!=" | ">=" | "<" | "<=" | ">"
 Projection   = "{" ProjColumns "}"
 ProjColumns  = [ ProjColumn { "," ProjColumn } ]
 ProjColumn   = ( ( ( ( "+" | "-" ) [ "!" ] ) | "~" ) ColumnName ) | "*"
 ColumnName   = string
 ArgRef       = "?" [ uint ]
See Also:

  • Method Details

    • rowType

      Class<R> rowType()
      Returns the interface which defines the rows of this table.

    • newRow

      R newRow()
      Returns a new row instance with unset columns.

    • cloneRow

      R cloneRow(R row)
      Returns a new row instance which is an exact copy of the given row.

    • unsetRow

      void unsetRow(R row)
      Resets the state of the given row such that all columns are unset.

    • copyRow

      void copyRow(R from, R to)
      Copies all columns and states from one row to another.

    • newScanner

      Scanner<R> newScanner(Transaction txn) throws IOException
      Returns a new scanner for all rows of this table.
      Parameters:
      txn - optional transaction for the scanner to use; pass null for auto-commit mode
      Returns:
      a new scanner positioned at the first row in the table
      Throws:
      IllegalStateException - if transaction belongs to another database instance
      IOException
      See Also:

    • newScanner

      Scanner<R> newScanner(Transaction txn, String query, Object... args) throws IOException
      Returns a new scanner for a subset of rows from this table, as specified by the query expression.
      Parameters:
      txn - optional transaction for the scanner to use; pass null for auto-commit mode
      Returns:
      a new scanner positioned at the first row in the table accepted by the query
      Throws:
      IllegalStateException - if transaction belongs to another database instance
      IOException
      See Also:

    • newUpdater

      Updater<R> newUpdater(Transaction txn) throws IOException
      Returns a new updater for all rows of this table.

      When providing a transaction which acquires locks (or the transaction is null), upgradable locks are acquired for each row visited by the updater. If the transaction lock mode is non-repeatable, any lock acquisitions for rows which are stepped over are released when moving to the next row. Updates with a null transaction are auto-committed and become visible to other transactions as the updater moves along.

      Parameters:
      txn - optional transaction for the updater to use; pass null for auto-commit mode
      Returns:
      a new updater positioned at the first row in the table
      Throws:
      IllegalStateException - if transaction belongs to another database instance
      IOException
      See Also:

    • newUpdater

      Updater<R> newUpdater(Transaction txn, String query, Object... args) throws IOException
      Returns a new updater for a subset of rows from this table, as specified by the query expression.

      When providing a transaction which acquires locks (or the transaction is null), upgradable locks are acquired for each row visited by the updater. If the transaction lock mode is non-repeatable, any lock acquisitions for rows which are stepped over are released when moving to the next row. Updates with a null transaction are auto-committed and become visible to other transactions as the updater moves along.

      Parameters:
      txn - optional transaction for the updater to use; pass null for auto-commit mode
      Returns:
      a new updater positioned at the first row in the table accepted by the query
      Throws:
      IllegalStateException - if transaction belongs to another database instance
      IOException
      See Also:

    • newStream

      default Stream<R> newStream(Transaction txn)
      Returns a new stream for all rows of this table. The stream must be explicitly closed when no longer used, or else it must be used with a try-with-resources statement. If an underlying IOException is generated, it's thrown as if it was unchecked.
      Parameters:
      txn - optional transaction for the stream to use; pass null for auto-commit mode
      Returns:
      a new stream positioned at the first row in the table
      Throws:
      IllegalStateException - if transaction belongs to another database instance
      See Also:

    • newStream

      default Stream<R> newStream(Transaction txn, String query, Object... args)
      Returns a new stream for a subset of rows from this table, as specified by the query expression. The stream must be explicitly closed when no longer used, or else it must be used with a try-with-resources statement. If an underlying IOException is generated, it's thrown as if it was unchecked.
      Parameters:
      txn - optional transaction for the stream to use; pass null for auto-commit mode
      Returns:
      a new stream positioned at the first row in the table accepted by the query
      Throws:
      IllegalStateException - if transaction belongs to another database instance
      See Also:

    • newTransaction

      Transaction newTransaction(DurabilityMode durabilityMode)
      Returns a new transaction which is compatible with this table. If the provided durability mode is null, a default mode is selected.

    • isEmpty

      boolean isEmpty() throws IOException
      Non-transactionally determines if the table has nothing in it. A return value of true guarantees that the table is empty, but false negatives are possible.
      Throws:
      IOException

    • load

      boolean load(Transaction txn, R row) throws IOException
      Fully loads the row by primary key.
      Returns:
      false if a corresponding row doesn't exist
      Throws:
      IllegalStateException - if primary key isn't fully specified
      IOException

    • exists

      boolean exists(Transaction txn, R row) throws IOException
      Checks if a row exists by searching against the primary key. This method should be called only if the row doesn't need to be loaded or stored — calling exists and then calling a load or store method is typically less efficient than skipping the exists check entirely.
      Returns:
      false if a corresponding row doesn't exist
      Throws:
      IllegalStateException - if primary key isn't fully specified
      IOException

    • store

      void store(Transaction txn, R row) throws IOException
      Unconditionally stores the given row, potentially replacing a corresponding row which already exists.
      Throws:
      IllegalStateException - if any required columns aren't set
      UniqueConstraintException - if a conflicting alternate key exists
      IOException

    • exchange

      R exchange(Transaction txn, R row) throws IOException
      Unconditionally stores the given row, potentially replacing a corresponding row which already exists.
      Returns:
      a copy of the replaced row, or null if none existed
      Throws:
      IllegalStateException - if any required columns aren't set
      UniqueConstraintException - if a conflicting alternate key exists
      IOException

    • insert

      boolean insert(Transaction txn, R row) throws IOException
      Stores the given row when a corresponding row doesn't exist.
      Returns:
      false if a corresponding row already exists and nothing was inserted
      Throws:
      IllegalStateException - if any required columns aren't set
      UniqueConstraintException - if a conflicting alternate key exists
      IOException

    • replace

      boolean replace(Transaction txn, R row) throws IOException
      Stores the given row when a corresponding row already exists.
      Returns:
      false if a corresponding row doesn't exist
      Throws:
      IllegalStateException - if any required columns aren't set
      UniqueConstraintException - if a conflicting alternate key exists
      IOException

    • update

      boolean update(Transaction txn, R row) throws IOException
      Updates an existing row with the modified columns of the given row, but the resulting row isn't loaded back.
      Returns:
      false if a corresponding row doesn't exist
      Throws:
      IllegalStateException - if primary key isn't fully specified
      UniqueConstraintException - if a conflicting alternate key exists
      IOException

    • merge

      boolean merge(Transaction txn, R row) throws IOException
      Updates an existing row with the modified columns of the given row, and then loads the result back into the given row.
      Returns:
      false if a corresponding row doesn't exist
      Throws:
      IllegalStateException - if primary key isn't fully specified
      UniqueConstraintException - if a conflicting alternate key exists
      IOException

    • delete

      boolean delete(Transaction txn, R row) throws IOException
      Unconditionally removes an existing row by primary key.
      Returns:
      false if a corresponding row doesn't exist
      Throws:
      IllegalStateException - if primary key isn't fully specified
      IOException

    • comparator

      Comparator<R> comparator(String spec)
      Returns a row comparator based on the given specification, which defines the ordering columns. Each column name is prefixed with '+' or '-', to indicate ascending or descending order. For example: "+lastName+firstName-birthdate". By default, nulls are treated as higher non-nulls, but a '!' after the '+'/'-' character causes nulls to be treated as lower than non-nulls.
      Throws:
      IllegalArgumentException - if the specification is malformed
      IllegalStateException - if the specification refers to non-existent columns

    • predicate

      Predicate<R> predicate(String query, Object... args)
      Returns a row predicate for the given query expression and arguments.

    • scannerPlan

      QueryPlan scannerPlan(Transaction txn, String query, Object... args) throws IOException
      Returns a query plan used by newScanner.
      Parameters:
      txn - optional transaction to be used; pass null for auto-commit mode
      query - optional query expression
      args - optional query arguments
      Throws:
      IOException

    • updaterPlan

      QueryPlan updaterPlan(Transaction txn, String query, Object... args) throws IOException
      Returns a query plan used by newUpdater.
      Parameters:
      txn - optional transaction to be used; pass null for auto-commit mode
      query - optional query expression
      args - optional query arguments
      Throws:
      IOException

    • streamPlan

      default QueryPlan streamPlan(Transaction txn, String query, Object... args) throws IOException
      Returns a query plan used by newStream.
      Parameters:
      txn - optional transaction to be used; pass null for auto-commit mode
      query - optional query expression
      args - optional query arguments
      Throws:
      IOException

    • close

      void close() throws IOException
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException
      See Also:

    • isClosed

      boolean isClosed()