package io.vertx.ext.sql;

import io.vertx.codegen.annotations.Fluent;
import io.vertx.codegen.annotations.Nullable;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.AsyncResult;
import io.vertx.core.Handler;
import io.vertx.core.json.JsonArray;

Represents a SQL query interface to a database
Author:
Paulo Lopes/**
 * Represents a SQL query interface to a database
 *
 * @author <a href="mailto:plopes@redhat.com">Paulo Lopes</a>
 */
@VertxGen(concrete = false)
public interface SQLOperations {

  
Executes the given SQL SELECT statement which returns the results of the query.
Params:
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)/**
   * Executes the given SQL <code>SELECT</code> statement which returns the results of the query.
   *
   * @param sql  the SQL to execute. For example <code>SELECT * FROM table ...</code>.
   * @param resultHandler  the handler which is called once the operation completes. It will return a {@code ResultSet}.
   *
   * @see java.sql.Statement#executeQuery(String)
   * @see java.sql.PreparedStatement#executeQuery(String)
   */
  @Fluent
  SQLOperations query(String sql, Handler<AsyncResult<ResultSet>> resultHandler);

  
Executes the given SQL SELECT prepared statement which returns the results of the query.
Params:
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)/**
   * Executes the given SQL <code>SELECT</code> prepared statement which returns the results of the query.
   *
   * @param sql  the SQL to execute. For example <code>SELECT * FROM table ...</code>.
   * @param params  these are the parameters to fill the statement.
   * @param resultHandler  the handler which is called once the operation completes. It will return a {@code ResultSet}.
   *
   * @see java.sql.Statement#executeQuery(String)
   * @see java.sql.PreparedStatement#executeQuery(String)
   */
  @Fluent
  SQLOperations queryWithParams(String sql, JsonArray params, Handler<AsyncResult<ResultSet>> resultHandler);

  
Executes the given SQL SELECT statement which returns the results of the query as a read stream.
Params:
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)/**
   * Executes the given SQL <code>SELECT</code> statement which returns the results of the query as a read stream.
   *
   * @param sql  the SQL to execute. For example <code>SELECT * FROM table ...</code>.
   * @param handler  the handler which is called once the operation completes. It will return a {@code SQLRowStream}.
   *
   * @see java.sql.Statement#executeQuery(String)
   * @see java.sql.PreparedStatement#executeQuery(String)
   */
  @Fluent
  SQLOperations queryStream(String sql, Handler<AsyncResult<SQLRowStream>> handler);

  
Executes the given SQL SELECT statement which returns the results of the query as a read stream.
Params:
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)/**
   * Executes the given SQL <code>SELECT</code> statement which returns the results of the query as a read stream.
   *
   * @param sql  the SQL to execute. For example <code>SELECT * FROM table ...</code>.
   * @param params  these are the parameters to fill the statement.
   * @param handler  the handler which is called once the operation completes. It will return a {@code SQLRowStream}.
   *
   * @see java.sql.Statement#executeQuery(String)
   * @see java.sql.PreparedStatement#executeQuery(String)
   */
  @Fluent
  SQLOperations queryStreamWithParams(String sql, JsonArray params, Handler<AsyncResult<SQLRowStream>> handler);

  
Execute a one shot SQL statement that returns a single SQL row. This method will reduce the boilerplate code by
getting a connection from the pool (this object) and return it back after the execution. Only the first result
from the result set is returned.
Params:
sql –     the statement to execute
handler – the result handler
Returns:
self/**
   * Execute a one shot SQL statement that returns a single SQL row. This method will reduce the boilerplate code by
   * getting a connection from the pool (this object) and return it back after the execution. Only the first result
   * from the result set is returned.
   *
   * @param sql     the statement to execute
   * @param handler the result handler
   * @return self
   */
  @Fluent
  default SQLOperations querySingle(String sql, Handler<AsyncResult<@Nullable JsonArray>> handler) {
    return query(sql, HandlerUtil.handleResultSetSingleRow(handler));
  }

  
Execute a one shot SQL statement with arguments that returns a single SQL row. This method will reduce the
boilerplate code by getting a connection from the pool (this object) and return it back after the execution.
Only the first result from the result set is returned.
Params:
sql –       the statement to execute
arguments – the arguments
handler –   the result handler
Returns:
self/**
   * Execute a one shot SQL statement with arguments that returns a single SQL row. This method will reduce the
   * boilerplate code by getting a connection from the pool (this object) and return it back after the execution.
   * Only the first result from the result set is returned.
   *
   * @param sql       the statement to execute
   * @param arguments the arguments
   * @param handler   the result handler
   * @return self
   */
  @Fluent
  default SQLOperations querySingleWithParams(String sql, JsonArray arguments, Handler<AsyncResult<@Nullable JsonArray>> handler) {
    return queryWithParams(sql, arguments, HandlerUtil.handleResultSetSingleRow(handler));
  }

  
Executes the given SQL statement which may be an INSERT, UPDATE, or DELETE
statement.
Params:
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)/**
   * Executes the given SQL statement which may be an <code>INSERT</code>, <code>UPDATE</code>, or <code>DELETE</code>
   * statement.
   *
   * @param sql  the SQL to execute. For example <code>INSERT INTO table ...</code>
   * @param resultHandler  the handler which is called once the operation completes.
   *
   * @see java.sql.Statement#executeUpdate(String)
   * @see java.sql.PreparedStatement#executeUpdate(String)
   */
  @Fluent
  SQLOperations update(String sql, Handler<AsyncResult<UpdateResult>> resultHandler);

  
Executes the given prepared statement which may be an INSERT, UPDATE, or DELETE
statement with the given parameters
Params:
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)/**
   * Executes the given prepared statement which may be an <code>INSERT</code>, <code>UPDATE</code>, or <code>DELETE</code>
   * statement with the given parameters
   *
   * @param sql  the SQL to execute. For example <code>INSERT INTO table ...</code>
   * @param params  these are the parameters to fill the statement.
   * @param resultHandler  the handler which is called once the operation completes.
   *
   * @see java.sql.Statement#executeUpdate(String)
   * @see java.sql.PreparedStatement#executeUpdate(String)
   */
  @Fluent
  SQLOperations updateWithParams(String sql, JsonArray params, Handler<AsyncResult<UpdateResult>> resultHandler);

  
Calls the given SQL PROCEDURE which returns the result from the procedure.
Params:
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)/**
   * Calls the given SQL <code>PROCEDURE</code> which returns the result from the procedure.
   *
   * @param sql  the SQL to execute. For example <code>{call getEmpName}</code>.
   * @param resultHandler  the handler which is called once the operation completes. It will return a {@code ResultSet}.
   *
   * @see java.sql.CallableStatement#execute(String)
   */
  @Fluent
  SQLOperations call(String sql, 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"]

Params:
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)/**
   * Calls the given SQL <code>PROCEDURE</code> 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:
   *
   * <pre>
   *   params = [VALUE1, VALUE2, null]
   *   outputs = [null, null, "VARCHAR"]
   * </pre>
   *
   * @param sql  the SQL to execute. For example <code>{call getEmpName (?, ?)}</code>.
   * @param params  these are the parameters to fill the statement.
   * @param outputs  these are the outputs to fill the statement.
   * @param resultHandler  the handler which is called once the operation completes. It will return a {@code ResultSet}.
   *
   * @see java.sql.CallableStatement#execute(String)
   */
  @Fluent
  SQLOperations callWithParams(String sql, JsonArray params, JsonArray outputs, Handler<AsyncResult<ResultSet>> resultHandler);

}