io.vertx.ext.sql.SQLOperations Maven / Gradle / Ivy

Go to download
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
 */
@VertxGen(concrete = false)
public interface SQLOperations {

  /**
   * Executes the given SQL SELECT statement which returns the results of the query.
   *
   * @param sql  the SQL to execute. For example SELECT * FROM table ....
   * @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> resultHandler);

  /**
   * Executes the given SQL SELECT prepared statement which returns the results of the query.
   *
   * @param sql  the SQL to execute. For example SELECT * FROM table ....
   * @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> resultHandler);

  /**
   * Executes the given SQL SELECT statement which returns the results of the query as a read stream.
   *
   * @param sql  the SQL to execute. For example SELECT * FROM table ....
   * @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> handler);

  /**
   * Executes the given SQL SELECT statement which returns the results of the query as a read stream.
   *
   * @param sql  the SQL to execute. For example SELECT * FROM table ....
   * @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> 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.
   *
   * @param sql     the statement to execute
   * @param handler the result handler
   * @return self
   */
  @Fluent
  default SQLOperations querySingle(String sql, Handler> 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.
   *
   * @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> handler) {
    return queryWithParams(sql, arguments, HandlerUtil.handleResultSetSingleRow(handler));
  }

  /**
   * Executes the given SQL statement which may be an INSERT, UPDATE, or DELETE
   * statement.
   *
   * @param sql  the SQL to execute. For example INSERT INTO table ...
   * @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> resultHandler);

  /**
   * Executes the given prepared statement which may be an INSERT, UPDATE, or DELETE
   * statement with the given parameters
   *
   * @param sql  the SQL to execute. For example INSERT INTO table ...
   * @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> resultHandler);

  /**
   * Calls the given SQL PROCEDURE which returns the result from the procedure.
   *
   * @param sql  the SQL to execute. For example {call getEmpName}.
   * @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> 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"]
   * 
   *
   * @param sql  the SQL to execute. For example {call getEmpName (?, ?)}.
   * @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> resultHandler);

}