io.baratine.jdbc.JdbcService Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of api Show documentation
A reactive Java web server.
The newest version!
/*
 * Copyright (c) 1998-2016 Caucho Technology -- all rights reserved
 *
 * This file is part of Baratine(TM)
 *
 * Each copy or derived work must preserve the copyright notice and this
 * notice unmodified.
 *
 * Baratine is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * Baratine is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, or any warranty
 * of NON-INFRINGEMENT.  See the GNU General Public License for more
 * details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Baratine; if not, write to the
 *
 *   Free Software Foundation, Inc.
 *   59 Temple Place, Suite 330
 *   Boston, MA 02111-1307  USA
 *
 * @author Nam Nguyen
 */

package io.baratine.jdbc;

import io.baratine.service.Result;
import io.baratine.service.Service;

/**
 * A service to execute SQL queries on a JDBC database.  See
 * {@link JdbcServiceSync} for the synchronous interface.  Before using this
 * service, you must configure the JDBC URL with either of the following two
 * methods:
 *
 * 
 * 
 During setup of the server:
 * 
 * String jdbcUrl = "jdbc:///foo";
 * Web.property(jdbcUrl + ".url", "jdbc:mysql://localhost/myDb");
 * 
 *
 * Note: .url is a config field defined in
 * {@link JdbcConfig}.
 * 
 *
 * 
Or in a config .yaml file:
 *  * "jdbc:///foo.url" : jdbc:mysql://localhost/myDb
 * 
 *
 * Then pass in the file via the command-line:
 *
 * $ java -jar myapp.jar --conf jdbc.yaml
 *
 * Where the main() method sends the args to {@link io.baratine.web.Web.start Web.start(args)}:
 *
 * 
 * public static void main(String[] args) throws Exception {
 *   Web.include(...);
 *
 *   Web.go(args);
 * }
 * 
 *
 * 
 *
 * 
 *
 * Once configured, the service is available for injection:
 *
 * 

 * {@literal @}{@link javax.inject.Inject Inject} {@literal @}{@link Service}("jdbc:///foo")
 * private JdbcService jdbc;
 * 
 *
 * Or programmatically:
 *
 * 
 * JdbcService jdbc = Services().{@link io.baratine.service.Services#service service}("jdbc:///foo").as(JdbcService.class);
 * 
 */
@Service
public interface JdbcService
{
  /**
   * Executes the SQL with the given params and returns the update count.
   *
   *    * 
   * query(
   *   (updateCount, e) -> {
   *       System.out.println(updateCount);
   *   },
   *   "UPDATE FROM test WHERE id=111"
   * );
   * 
   * 
   *
   * @param result update count
   * @param sql
   * @param params optional query positional parameters
   */
  void execute(Result result, String sql, Object ... params);


  /**
   * Executes the SQL with the given params and returns the offline ResultSet.
   *
   *    * 
   * query(
   *   (rs, e) -> {
   *       System.out.println(rs);
   *   },
   *   "SELECT * FROM test"
   * );
   * 
   * 
   *
   * @param result ResultSet
   * @param sql
   * @param params optional query positional parameters
   */
  void query(Result result, String sql, Object ... params);

  /**
   * Executes on the SQL function on the {@link java.sql.Connection}.  After
   * completion, any opened {@link java.sql.Statement Statement}s are
   * automatically closed.
   *
   *    * 
   * jdbcService.query(
   *   (rs, e) -> {
   *       System.out.println(rs);
   *   },
   *   (conn) -> {
   *       Statement stmt = conn.createStatement();
   *
   *       stmt.execute("INSERT INTO test VALUES (123, \"value0\")");
   *
   *       return stmt.getUpdateCount();
   *   }
   * );
   * 
   * 
   *
   * @param result
   * @param fun query function to run on the {@link java.sql.Connection}
   * @param params optional arguments to SqlBiFunction
   */
   void query(Result result, SqlFunction fun);

  /**
   * Executes on the SQL function on the {@link java.sql.Connection} with
   * parameters.  After completion, any opened
   * {@link java.sql.Statement Statement}s are automatically closed.
   *
   *    * 
   * jdbcService.query(
   *   (rs, e) -> {
   *       System.out.println(rs);
   *   },
   *   (conn, params) -> {
   *       Statement stmt = conn.prepareStatement("SELECT * FROM test WHERE id = ?");
   *
   *       stmt.setString(1, params[0]);
   *
   *       stmt.execute();
   *
   *       return "done";
   *   },
   *   123456
   * );
   * 
   * 
   *
   * @param result
   * @param fun query function to run on the {@link java.sql.Connection}
   * @param params optional arguments to SqlBiFunction
   */
   void query(Result result, SqlBiFunction fun, Object ... params);

  /**
   * Returns the real-time statistics for this connection.
   *
   * @param result the {@link JdbcStat} for this connection
   */
  void stats(Result result);
}