Package com.blackrook.sql

Interface SQLCallable

All Known Implementing Classes:
SQLConnection, SQLConnection.Transaction
public interface SQLCallable
The interface used for all SQL connections that can have queries performed through them.
Author:
Matthew Tropiano

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_BATCH_SIZE
    Default batch size.

  • Method Summary

    Modifier and Type
    Method
    Description
    <T> T[]
    getResult(Class<T> type, String query, Object... parameters)
    Performs a query and creates objects from the resultant rows, setting relevant fields on them.
    SQLResult
    getResult(String query, Object... parameters)
    Performs a query that returns rows and extracts them into a result.
    <T> T
    getRow(Class<T> type, String query, Object... parameters)
    Performs a query and creates an object from it from the first result row extracted, setting relevant fields.
    SQLRow
    getRow(String query, Object... parameters)
    Performs a query and extracts the first row result into a single SQLRow.
    default int[]
    getUpdateBatch(String query, int granularity, Object[][] parameterList)
    Performs a series of update queries on a single statement on a connection and returns the batch result.
    int[]
    getUpdateBatch(String query, int granularity, Collection<Object[]> parameterList)
    Performs a series of update queries on a single statement on a connection and returns the batch result.
    default int[]
    getUpdateBatch(String query, Object[][] parameterList)
    Performs a series of update queries on a single statement on a connection and returns the batch result.
    default int[]
    getUpdateBatch(String query, Collection<Object[]> parameterList)
    Performs a series of update queries on a single statement on a connection and returns the batch result.
    default SQLResult[]
    getUpdateBatchResult(String query, Object[][] parameterList)
    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.
    SQLResult[]
    getUpdateBatchResult(String query, Collection<Object[]> parameterList)
    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.
    default long[]
    getUpdateLargeBatch(String query, int granularity, Object[][] parameterList)
    Performs a series of update queries on a single statement on a connection and returns the batch result.
    long[]
    getUpdateLargeBatch(String query, int granularity, Collection<Object[]> parameterList)
    Performs a series of update queries on a single statement on a connection and returns the batch result.
    default long[]
    getUpdateLargeBatch(String query, Object[][] parameterList)
    Performs a series of update queries on a single statement on a connection and returns the batch result.
    default long[]
    getUpdateLargeBatch(String query, Collection<Object[]> parameterList)
    Performs a series of update queries on a single statement on a connection and returns the batch result.
    SQLResult
    getUpdateResult(String query, Object... parameters)
    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.

  • Field Details

    • DEFAULT_BATCH_SIZE

      static final int DEFAULT_BATCH_SIZE
      Default batch size.
      See Also:

  • Method Details

    • getRow

      SQLRow getRow(String query, Object... parameters)
      Performs a query and extracts the first row result into a single SQLRow.
      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.
      Throws:
      SQLRuntimeException - if the query cannot be executed or the query causes an error.

    • getRow

      <T> T getRow(Class<T> type, String query, Object... parameters)
      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[].
      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.
      Throws:
      SQLRuntimeException - if the query cannot be executed or the query causes an error.
      ClassCastException - if one object type cannot be converted to another.

    • getResult

      SQLResult getResult(String query, Object... parameters)
      Performs a query that returns rows and extracts them into a result.
      Parameters:
      query - the query to execute.
      parameters - list of parameters for parameterized queries.
      Returns:
      the result of the query.
      Throws:
      SQLRuntimeException - if the query cannot be executed or the query causes an error.

    • getResult

      <T> T[] getResult(Class<T> type, String query, Object... parameters)
      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[].
      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.
      Throws:
      SQLRuntimeException - if the query cannot be executed or the query causes an error.
      ClassCastException - if one object type cannot be converted to another.

    • getUpdateResult

      SQLResult getUpdateResult(String query, Object... parameters)
      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.
      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).
      Throws:
      SQLRuntimeException - if the query cannot be executed or the query causes an error.

    • getUpdateBatch

      default int[] getUpdateBatch(String query, Object[][] parameterList)
      Performs a series of update queries on a single statement on a connection and returns the batch result.
      Parameters:
      query - the query statement to execute.
      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).
      Throws:
      SQLRuntimeException - if the query cannot be executed or the query causes an error.
      Since:
      1.1.0, 1.2.0, returns int[]. See getUpdateLargeBatch(String, Object[][]) for long[].

    • getUpdateBatch

      default int[] getUpdateBatch(String query, int granularity, Object[][] parameterList)
      Performs a series of update queries on a single statement on a connection and returns the batch result.
      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).
      Throws:
      SQLRuntimeException - if the query cannot be executed or the query causes an error.
      Since:
      1.1.0, 1.2.0, returns int[]. See getUpdateLargeBatch(String, int, Object[][]) for long[].

    • getUpdateBatch

      default int[] getUpdateBatch(String query, Collection<Object[]> parameterList)
      Performs a series of update queries on a single statement on a connection and returns the batch result.
      Parameters:
      query - the query statement to execute.
      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).
      Throws:
      SQLRuntimeException - if the query cannot be executed or the query causes an error.
      Since:
      1.1.0, 1.2.0, returns int[]. See getUpdateLargeBatch(String, Collection) for long[].

    • getUpdateBatch

      int[] getUpdateBatch(String query, int granularity, Collection<Object[]> parameterList)
      Performs a series of update queries on a single statement on a connection and returns the batch result.
      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).
      Throws:
      SQLRuntimeException - if the query cannot be executed or the query causes an error.
      Since:
      1.1.0, 1.2.0, returns int[]. See getUpdateLargeBatch(String, int, Collection) for long[].

    • getUpdateLargeBatch

      default long[] getUpdateLargeBatch(String query, Object[][] parameterList)
      Performs a series of update queries on a single statement on a connection and returns the batch result.
      Parameters:
      query - the query statement to execute.
      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).
      Throws:
      SQLRuntimeException - if the query cannot be executed or the query causes an error.
      Since:
      1.2.0

    • getUpdateLargeBatch

      default long[] getUpdateLargeBatch(String query, int granularity, Object[][] parameterList)
      Performs a series of update queries on a single statement on a connection and returns the batch result.
      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).
      Throws:
      SQLRuntimeException - if the query cannot be executed or the query causes an error.
      Since:
      1.2.0

    • getUpdateLargeBatch

      default long[] getUpdateLargeBatch(String query, Collection<Object[]> parameterList)
      Performs a series of update queries on a single statement on a connection and returns the batch result.
      Parameters:
      query - the query statement to execute.
      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).
      Throws:
      SQLRuntimeException - if the query cannot be executed or the query causes an error.
      Since:
      1.2.0

    • getUpdateLargeBatch

      long[] getUpdateLargeBatch(String query, int granularity, Collection<Object[]> parameterList)
      Performs a series of update queries on a single statement on a connection and returns the batch result.
      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).
      Throws:
      SQLRuntimeException - if the query cannot be executed or the query causes an error.
      Since:
      1.2.0

    • getUpdateBatchResult

      default SQLResult[] getUpdateBatchResult(String query, Object[][] parameterList)
      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 getUpdateResult(String, Object...), since it uses the same prepared statement. However, it is not as efficient as getUpdateBatch(String, int, Collection), but for this method, you will get the generated ids in each result, if any.

      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.
      Throws:
      SQLRuntimeException - if the query cannot be executed or the query causes an error.
      Since:
      1.1.0

    • getUpdateBatchResult

      SQLResult[] getUpdateBatchResult(String query, Collection<Object[]> parameterList)
      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 getUpdateResult(String, Object...), since it uses the same prepared statement. However, it is not as efficient as getUpdateBatch(String, int, Collection), but for this method, you will get the generated ids in each result, if any.

      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.
      Throws:
      SQLRuntimeException - if the query cannot be executed or the query causes an error.
      Since:
      1.1.0