Package com.blackrook.sql

Class SQLConnection.Transaction

java.lang.Object
com.blackrook.sql.SQLConnection.Transaction
All Implemented Interfaces:
SQLCallable, AutoCloseable
Enclosing class:
SQLConnection
public class SQLConnection.Transaction extends Object implements SQLCallable, AutoCloseable
A transaction object that holds a connection that guarantees an isolation level of some kind. Queries can be made through this object until it has been released.

This object's Object.finalize() method attempts to roll back the transaction if it hasn't already been finished.

Author:
Matthew Tropiano

  • Method Details

    • getRow

      public SQLRow getRow(String query, Object... parameters)
      Description copied from interface: SQLCallable
      Performs a query and extracts the first row result into a single SQLRow.
      Specified by:
      getRow in interface SQLCallable
      Parameters:
      query - the query statement to execute.
      parameters - list of parameters for parameterized queries.
      Returns:
      the single result row returned, or null if no row returned.

    • getRow

      public <T> T getRow(Class<T> type, String query, Object... parameters)
      Description copied from interface: SQLCallable
      Performs a query and creates an object from it from the first result row extracted, setting relevant fields.

      Each result row is applied via the target object's public fields and setter methods.

      For instance, if there is a column is a row called "color", its value will be applied via the public field "color" or the setter "setColor()". Public fields take precedence over setters.

      Only certain types are converted without issue. Below is a set of source types and their valid target types:

      Conversion of Types
      Boolean Boolean, all numeric primitives and their autoboxed equivalents, String.
      Number Boolean (zero is false, nonzero is true), all numeric primitives and their autoboxed equivalents, String, Date, Timestamp.
      Timestamp Long (both primitive and object as milliseconds since the Epoch), Timestamp, Date, String
      Date Long (both primitive and object as milliseconds since the Epoch), Timestamp, Date, String
      String Boolean, all numeric primitives and their autoboxed equivalents, String, byte[], char[].
      Clob Boolean, all numeric primitives and their autoboxed equivalents, String, byte[], char[].
      Blob String, byte[], char[].
      NClob Boolean, all numeric primitives and their autoboxed equivalents, String, byte[], char[].
      byte[] String, byte[], char[].
      char[] Boolean, all numeric primitives and their autoboxed equivalents, String, byte[], char[].
      Specified by:
      getRow in interface SQLCallable
      Type Parameters:
      T - the returned data type.
      Parameters:
      type - the class type to instantiate.
      query - the query to execute.
      parameters - list of parameters for parameterized queries.
      Returns:
      an instantiated object with the pertinent fields set, or null if no rows.

    • getResult

      public SQLResult getResult(String query, Object... parameters)
      Description copied from interface: SQLCallable
      Performs a query that returns rows and extracts them into a result.
      Specified by:
      getResult in interface SQLCallable
      Parameters:
      query - the query to execute.
      parameters - list of parameters for parameterized queries.
      Returns:
      the result of the query.

    • getResult

      public <T> T[] getResult(Class<T> type, String query, Object... parameters)
      Description copied from interface: SQLCallable
      Performs a query and creates objects from the resultant rows, setting relevant fields on them.

      Each result row is applied via the target object's public fields and setter methods.

      For instance, if there is a column is a row called "color", its value will be applied via the public field "color" or the setter "setColor()". Public fields take precedence over setters.

      Only certain types are converted without issue. Below is a set of source types and their valid target types:

      Conversion of Types
      Boolean Boolean, all numeric primitives and their autoboxed equivalents, String.
      Number Boolean (zero is false, nonzero is true), all numeric primitives and their autoboxed equivalents, String, Date, Timestamp.
      Timestamp Long (both primitive and object as milliseconds since the Epoch), Timestamp, Date, String
      Date Long (both primitive and object as milliseconds since the Epoch), Timestamp, Date, String
      String Boolean, all numeric primitives and their autoboxed equivalents, String, byte[], char[].
      Clob Boolean, all numeric primitives and their autoboxed equivalents, String, byte[], char[].
      Blob String, byte[], char[].
      NClob Boolean, all numeric primitives and their autoboxed equivalents, String, byte[], char[].
      byte[] String, byte[], char[].
      char[] Boolean, all numeric primitives and their autoboxed equivalents, String, byte[], char[].
      Specified by:
      getResult in interface SQLCallable
      Type Parameters:
      T - the returned data type.
      Parameters:
      type - the class type to instantiate.
      query - the query to execute.
      parameters - list of parameters for parameterized queries.
      Returns:
      an array of instantiated objects with the pertinent fields set for each row.

    • getUpdateResult

      public SQLResult getUpdateResult(String query, Object... parameters)
      Description copied from interface: SQLCallable
      Performs an update query (INSERT, DELETE, UPDATE, or other commands that do not return rows) and extracts the data/affected data/generated data into a SQLResult.
      Specified by:
      getUpdateResult in interface SQLCallable
      Parameters:
      query - the query to execute.
      parameters - list of parameters for parameterized queries.
      Returns:
      the update result returned (usually number of rows affected and or generated ids).

    • getUpdateBatch

      public int[] getUpdateBatch(String query, int granularity, Collection<Object[]> parameterList)
      Description copied from interface: SQLCallable
      Performs a series of update queries on a single statement on a connection and returns the batch result.
      Specified by:
      getUpdateBatch in interface SQLCallable
      Parameters:
      query - the query statement to execute.
      granularity - the amount of statements to execute at a time. If 0 or less, no granularity.
      parameterList - the list of parameter sets to pass to the query for each update.
      Returns:
      the update result returned (usually number of rows affected and or generated ids).

    • getUpdateLargeBatch

      public long[] getUpdateLargeBatch(String query, int granularity, Collection<Object[]> parameterList)
      Description copied from interface: SQLCallable
      Performs a series of update queries on a single statement on a connection and returns the batch result.
      Specified by:
      getUpdateLargeBatch in interface SQLCallable
      Parameters:
      query - the query statement to execute.
      granularity - the amount of statements to execute at a time. If 0 or less, no granularity.
      parameterList - the list of parameter sets to pass to the query for each update.
      Returns:
      the update result returned (usually number of rows affected and or generated ids).

    • getUpdateBatchResult

      public SQLResult[] getUpdateBatchResult(String query, Collection<Object[]> parameterList)
      Description copied from interface: SQLCallable
      Performs an update query (INSERT, DELETE, UPDATE, or other commands that do not return rows) and extracts each set of result data into a SQLResult.

      This is usually more efficient than multiple calls of SQLCallable.getUpdateResult(String, Object...), since it uses the same prepared statement. However, it is not as efficient as SQLCallable.getUpdateBatch(String, int, Collection), but for this method, you will get the generated ids in each result, if any.

      Specified by:
      getUpdateBatchResult in interface SQLCallable
      Parameters:
      query - the query statement to execute.
      parameterList - the list of parameter sets to pass to the query for each update.
      Returns:
      the list of update results returned, each corresponding to an update.

    • isFinished

      public boolean isFinished()
      Returns:
      true if this transaction has been completed or false if more methods can be invoked on it.

    • complete

      public void complete() throws SQLException
      Completes this transaction and prevents further calls on it. This calls Connection.commit(). on the encapsulated connection and resets its previous transaction level state plus its auto-commit state.
      Throws:
      IllegalStateException - if this transaction was already finished.
      SQLException - if this causes a database error.

    • abort

      public void abort() throws SQLException
      Aborts this transaction and prevents further calls on it. This calls Connection.rollback(). on the encapsulated connection and resets its previous transaction level state plus its auto-commit state.
      Throws:
      IllegalStateException - if this transaction was already finished.
      SQLException - if this causes a database error.

    • commit

      public void commit() throws SQLException
      Commits the actions completed so far in this transaction. This is also called during complete().
      Throws:
      IllegalStateException - if this transaction was already finished.
      SQLException - if this causes a database error.

    • rollback

      public void rollback() throws SQLException
      Rolls back this entire transaction.
      Throws:
      IllegalStateException - if this transaction was already finished.
      SQLException - if this causes a database error.

    • rollback

      public void rollback(Savepoint savepoint) throws SQLException
      Rolls back this transaction to a Savepoint. Everything executed after the Savepoint passed into this method will be rolled back.
      Parameters:
      savepoint - the Savepoint to roll back to.
      Throws:
      IllegalStateException - if this transaction was already finished.
      SQLException - if this causes a database error.

    • setSavepoint

      public Savepoint setSavepoint() throws SQLException
      Calls Connection.setSavepoint() on the encapsulated connection.
      Returns:
      a generated Savepoint of this transaction.
      Throws:
      IllegalStateException - if this transaction was already finished.
      SQLException - if this causes a database error.

    • setSavepoint

      public Savepoint setSavepoint(String name) throws SQLException
      Calls Connection.setSavepoint() on the encapsulated connection.
      Parameters:
      name - the name of the savepoint.
      Returns:
      a generated Savepoint of this transaction.
      Throws:
      IllegalStateException - if this transaction was already finished.
      SQLException - if this causes a database error.

    • close

      public void close()
      If this transaction is not finished, this aborts it.
      Specified by:
      close in interface AutoCloseable
      See Also: