io.vertx.ext.sql

## Interface SQLConnection

- All Superinterfaces:
    AutoCloseable, Closeable, SQLOperations

      public interface SQLConnection
      extends SQLOperations, Closeable

  Represents a connection to a SQL database
  Author:
    Nick Scavelli

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `SQLConnection` | `batch(List<String> sqlStatements, Handler<AsyncResult<List<Integer>>> handler)` Batch simple SQL strings and execute the batch where the async result contains a array of Integers.
    `SQLConnection` | `batchCallableWithParams(String sqlStatement, List<JsonArray> inArgs, List<JsonArray> outArgs, Handler<AsyncResult<List<Integer>>> handler)` Batch a callable statement with all entries from the args list.
    `SQLConnection` | `batchWithParams(String sqlStatement, List<JsonArray> args, Handler<AsyncResult<List<Integer>>> handler)` Batch a prepared statement with all entries from the args list.
    `SQLConnection` | `call(String sql, Handler<AsyncResult<ResultSet>> resultHandler)` Calls the given SQL `PROCEDURE` which returns the result from the procedure.
    `SQLConnection` | `callWithParams(String sql, JsonArray params, JsonArray outputs, Handler<AsyncResult<ResultSet>> resultHandler)` Calls the given SQL `PROCEDURE` which returns the result from the procedure.
    `void` | `close()` Closes the connection.
    `void` | `close(Handler<AsyncResult<Void>> handler)` Closes the connection.
    `SQLConnection` | `commit(Handler<AsyncResult<Void>> handler)` Commits all changes made since the previous commit/rollback.
    `SQLConnection` | `execute(String sql, Handler<AsyncResult<Void>> resultHandler)` Executes the given SQL statement
    `SQLConnection` | `getTransactionIsolation(Handler<AsyncResult<TransactionIsolation>> handler)` Attempts to return the transaction isolation level for this Connection object to the one given.
    `SQLConnection` | `query(String sql, Handler<AsyncResult<ResultSet>> resultHandler)` Executes the given SQL `SELECT` statement which returns the results of the query.
    `SQLConnection` | `queryStream(String sql, Handler<AsyncResult<SQLRowStream>> handler)` Executes the given SQL `SELECT` statement which returns the results of the query as a read stream.
    `SQLConnection` | `queryStreamWithParams(String sql, JsonArray params, Handler<AsyncResult<SQLRowStream>> handler)` Executes the given SQL `SELECT` statement which returns the results of the query as a read stream.
    `SQLConnection` | `queryWithParams(String sql, JsonArray params, Handler<AsyncResult<ResultSet>> resultHandler)` Executes the given SQL `SELECT` prepared statement which returns the results of the query.
    `SQLConnection` | `rollback(Handler<AsyncResult<Void>> handler)` Rolls back all changes made since the previous commit/rollback.
    `SQLConnection` | `setAutoCommit(boolean autoCommit, Handler<AsyncResult<Void>> resultHandler)` Sets the auto commit flag for this connection.
    `SQLConnection` | `setOptions(SQLOptions options)` Sets the desired options to be applied to the current connection when statements are executed.
    `default SQLConnection` | `setQueryTimeout(int timeoutInSeconds)` Deprecated. instead use `setOptions(SQLOptions)` with `SQLOptions.setQueryTimeout(int)`
    `SQLConnection` | `setTransactionIsolation(TransactionIsolation isolation, Handler<AsyncResult<Void>> handler)` Attempts to change the transaction isolation level for this Connection object to the one given.
    `default <N> N` | `unwrap()` Return the underlying Connection object if available.
    `SQLConnection` | `update(String sql, Handler<AsyncResult<UpdateResult>> resultHandler)` Executes the given SQL statement which may be an `INSERT`, `UPDATE`, or `DELETE` statement.
    `SQLConnection` | `updateWithParams(String sql, JsonArray params, Handler<AsyncResult<UpdateResult>> resultHandler)` Executes the given prepared statement which may be an `INSERT`, `UPDATE`, or `DELETE` statement with the given parameters

    - ### Methods inherited from interface io.vertx.ext.sql.SQLOperations

      `querySingle, querySingleWithParams`

- - ### Method Detail

    - #### setOptions

          SQLConnection setOptions(SQLOptions options)

      Sets the desired options to be applied to the current connection when statements are executed. The options are not applied globally but applicable to the current connection. For example changing the transaction isolation level will only affect statements run on this connection and not future or current connections acquired from the connection pool. This method is not async in nature since the apply will only happen at the moment a query is run.
      Parameters:
        `options` - the options to modify the unwrapped connection.

    - #### setAutoCommit

          SQLConnection setAutoCommit(boolean autoCommit,
                                      Handler<AsyncResult<Void>> resultHandler)

      Sets the auto commit flag for this connection. True by default.
      Parameters:
        `autoCommit` - the autoCommit flag, true by default.
        `resultHandler` - the handler which is called once this operation completes.
      See Also:
        `Connection.setAutoCommit(boolean)`

    - #### execute

          SQLConnection execute(String sql,
                                Handler<AsyncResult<Void>> resultHandler)

      Executes the given SQL statement
      Parameters:
        `sql` - the SQL to execute. For example `CREATE TABLE IF EXISTS table ...`
        `resultHandler` - the handler which is called once this operation completes.
      See Also:
        `Statement.execute(String)`

    - #### query

          SQLConnection query(String sql,
                              Handler<AsyncResult<ResultSet>> resultHandler)

      Executes the given SQL `SELECT` statement which returns the results of the query.
      Specified by:
        `query` in interface `SQLOperations`
      Parameters:
        `sql` - the SQL to execute. For example `SELECT * FROM table ...`.
        `resultHandler` - the handler which is called once the operation completes. It will return a `ResultSet`.
      See Also:
        `Statement.executeQuery(String)`, `Statement.executeQuery(String)`

    - #### queryStream

          SQLConnection queryStream(String sql,
                                    Handler<AsyncResult<SQLRowStream>> handler)

      Executes the given SQL `SELECT` statement which returns the results of the query as a read stream.
      Specified by:
        `queryStream` in interface `SQLOperations`
      Parameters:
        `sql` - the SQL to execute. For example `SELECT * FROM table ...`.
        `handler` - the handler which is called once the operation completes. It will return a `SQLRowStream`.
      See Also:
        `Statement.executeQuery(String)`, `Statement.executeQuery(String)`

    - #### queryWithParams

          SQLConnection queryWithParams(String sql,
                                        JsonArray params,
                                        Handler<AsyncResult<ResultSet>> resultHandler)

      Executes the given SQL `SELECT` prepared statement which returns the results of the query.
      Specified by:
        `queryWithParams` in interface `SQLOperations`
      Parameters:
        `sql` - the SQL to execute. For example `SELECT * FROM table ...`.
        `params` - these are the parameters to fill the statement.
        `resultHandler` - the handler which is called once the operation completes. It will return a `ResultSet`.
      See Also:
        `Statement.executeQuery(String)`, `Statement.executeQuery(String)`

    - #### queryStreamWithParams

          SQLConnection queryStreamWithParams(String sql,
                                              JsonArray params,
                                              Handler<AsyncResult<SQLRowStream>> handler)

      Executes the given SQL `SELECT` statement which returns the results of the query as a read stream.
      Specified by:
        `queryStreamWithParams` in interface `SQLOperations`
      Parameters:
        `sql` - the SQL to execute. For example `SELECT * FROM table ...`.
        `params` - these are the parameters to fill the statement.
        `handler` - the handler which is called once the operation completes. It will return a `SQLRowStream`.
      See Also:
        `Statement.executeQuery(String)`, `Statement.executeQuery(String)`

    - #### update

          SQLConnection update(String sql,
                               Handler<AsyncResult<UpdateResult>> resultHandler)

      Executes the given SQL statement which may be an `INSERT`, `UPDATE`, or `DELETE` statement.
      Specified by:
        `update` in interface `SQLOperations`
      Parameters:
        `sql` - the SQL to execute. For example `INSERT INTO table ...`
        `resultHandler` - the handler which is called once the operation completes.
      See Also:
        `Statement.executeUpdate(String)`, `Statement.executeUpdate(String)`

    - #### updateWithParams

          SQLConnection updateWithParams(String sql,
                                         JsonArray params,
                                         Handler<AsyncResult<UpdateResult>> resultHandler)

      Executes the given prepared statement which may be an `INSERT`, `UPDATE`, or `DELETE` statement with the given parameters
      Specified by:
        `updateWithParams` in interface `SQLOperations`
      Parameters:
        `sql` - the SQL to execute. For example `INSERT INTO table ...`
        `params` - these are the parameters to fill the statement.
        `resultHandler` - the handler which is called once the operation completes.
      See Also:
        `Statement.executeUpdate(String)`, `Statement.executeUpdate(String)`

    - #### call

          SQLConnection call(String sql,
                             Handler<AsyncResult<ResultSet>> resultHandler)

      Calls the given SQL `PROCEDURE` which returns the result from the procedure.
      Specified by:
        `call` in interface `SQLOperations`
      Parameters:
        `sql` - the SQL to execute. For example `{call getEmpName}`.
        `resultHandler` - the handler which is called once the operation completes. It will return a `ResultSet`.
      See Also:
        `Statement.execute(String)`

    - #### callWithParams

          SQLConnection callWithParams(String sql,
                                       JsonArray params,
                                       JsonArray outputs,
                                       Handler<AsyncResult<ResultSet>> resultHandler)

      Calls the given SQL `PROCEDURE` which returns the result from the procedure. The index of params and outputs are important for both arrays, for example when dealing with a prodecure that takes the first 2 arguments as input values and the 3 arg as an output then the arrays should be like:

             params = [VALUE1, VALUE2, null]
             outputs = [null, null, "VARCHAR"]

      Specified by:
        `callWithParams` in interface `SQLOperations`
      Parameters:
        `sql` - the SQL to execute. For example `{call getEmpName (?, ?)}`.
        `params` - these are the parameters to fill the statement.
        `outputs` - these are the outputs to fill the statement.
        `resultHandler` - the handler which is called once the operation completes. It will return a `ResultSet`.
      See Also:
        `Statement.execute(String)`

    - #### close

          void close(Handler<AsyncResult<Void>> handler)

      Closes the connection. Important to always close the connection when you are done so it's returned to the pool.
      Parameters:
        `handler` - the handler called when this operation completes.

    - #### close

          void close()

      Closes the connection. Important to always close the connection when you are done so it's returned to the pool.
      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in interface `Closeable`

    - #### commit

          SQLConnection commit(Handler<AsyncResult<Void>> handler)

      Commits all changes made since the previous commit/rollback.
      Parameters:
        `handler` - the handler called when this operation completes.

    - #### rollback

          SQLConnection rollback(Handler<AsyncResult<Void>> handler)

      Rolls back all changes made since the previous commit/rollback.
      Parameters:
        `handler` - the handler called when this operation completes.

    - #### setQueryTimeout

          @Deprecated
          default SQLConnection setQueryTimeout(int timeoutInSeconds)

      Deprecated. instead use `setOptions(SQLOptions)` with `SQLOptions.setQueryTimeout(int)`
      Sets a connection wide query timeout. It can be over written at any time and becomes active on the next query call.
      Parameters:
        `timeoutInSeconds` - the max amount of seconds the query can take to execute.

    - #### batch

          SQLConnection batch(List<String> sqlStatements,
                              Handler<AsyncResult<List<Integer>>> handler)

      Batch simple SQL strings and execute the batch where the async result contains a array of Integers.
      Parameters:
        `sqlStatements` - sql statement
        `handler` - the result handler

    - #### batchWithParams

          SQLConnection batchWithParams(String sqlStatement,
                                        List<JsonArray> args,
                                        Handler<AsyncResult<List<Integer>>> handler)

      Batch a prepared statement with all entries from the args list. Each entry is a batch. The operation completes with the execution of the batch where the async result contains a array of Integers.
      Parameters:
        `sqlStatement` - sql statement
        `args` - the prepared statement arguments
        `handler` - the result handler

    - #### batchCallableWithParams

          SQLConnection batchCallableWithParams(String sqlStatement,
                                                List<JsonArray> inArgs,
                                                List<JsonArray> outArgs,
                                                Handler<AsyncResult<List<Integer>>> handler)

      Batch a callable statement with all entries from the args list. Each entry is a batch. The size of the lists inArgs and outArgs MUST be the equal. The operation completes with the execution of the batch where the async result contains a array of Integers.
      Parameters:
        `sqlStatement` - sql statement
        `inArgs` - the callable statement input arguments
        `outArgs` - the callable statement output arguments
        `handler` - the result handler

    - #### setTransactionIsolation

          SQLConnection setTransactionIsolation(TransactionIsolation isolation,
                                                Handler<AsyncResult<Void>> handler)

      Attempts to change the transaction isolation level for this Connection object to the one given. The constants defined in the interface Connection are the possible transaction isolation levels.
      Parameters:
        `isolation` - the level of isolation
        `handler` - the handler called when this operation completes.

    - #### getTransactionIsolation

          SQLConnection getTransactionIsolation(Handler<AsyncResult<TransactionIsolation>> handler)

      Attempts to return the transaction isolation level for this Connection object to the one given.
      Parameters:
        `handler` - the handler called when this operation completes.

    - #### unwrap

          default <N> N unwrap()

      Return the underlying Connection object if available. This is not mandated to be implemented by the clients.
      Type Parameters:
        `N` - the underlying connection object type
      Returns:
        the unwrapped connection or null

Copyright © 2023 Eclipse. All rights reserved.