JDBI

JDBI

is a SQL convenience library for Java. It attempts to expose relational database access in idiomatic Java, using collections, beans, and so on, while maintaining the same level of detail as JDBC.

它尝试使用 Java 来表达与关系型数据库的联系。通过集合，bean 等与数据库访问，同时保持与 JDBC 相同的细节级别。

It exposes two different style APIs, a fluent style and a sql object style.

它提供了两种不同样式的 API，流式和 sql 对象式。

Fluent API

// The fluent style looks like:

// using in-memory H2 database
DataSource ds = JdbcConnectionPool.create("jdbc:h2:mem:test",
                                          "username",
                                          "password");
DBI dbi = new DBI(ds);
Handle h = dbi.open();
h.execute("create table something (id int primary key, name varchar(100))");

h.execute("insert into something (id, name) values (?, ?)", 1, "Brian");

String name = h.createQuery("select name from something where id = :id")
                    .bind("id", 1)
                    .map(StringMapper.FIRST)
                    .first();

assertThat(name, equalTo("Brian"));

h.close();

The DBI type is analogous to a JDBC DataSource, and will usually be constructed by passing in a JDBC DataSource. There are alternate constructors which take JDBC URL and credentials, and other means. From the DBI instance you obtain Handle instances. A Handle represents a single connection to the database. Handles rely on an underlying JDBC connection object.
DBI 类型类似于 JDBC DataSource，通常将通过传递 JDBC DataSource 来构建。当然还其它的构造函数，或采用 JDBC URL 和凭据，或其他方式。从 DBI 实例获取处理实例。一个 Handle 实例表示与数据库的一个单一连接。Handle 实例依赖于底层 JDBC 连接对象。

With a handle you may create and execute statements, queries, calls, batches, or prepared batches. In the above example we execute a statement to define a table, execute another statement, this time with two positional arguments to insert a value, and finally construct a query, bind a value to a named argument in the query, map the results to a String, and take the first result which comes back.
使用句柄，您可以创建和执行语句，查询，调用，批处理或准备的批处理。在上面的示例中，我们执行一个语句来定义一个表，执行另一个语句，例子用了两个位置参数来插入一个值，最后构造出一个查询语句，绑定值到查询语句里被命名的参数，将结果映射到字符串，并采取回来的第一个结果。

The named argument facility on statements and queries is provided by JDBI – it parses out the SQL and uses positional parameters when actually constructing the prepared statements.
The above example uses the default colon-demarcated parser, but an alternative hash delimited parser is included as well for use with databases which use colons in their grammars, such as PostgreSQL.
JDBI 提供了关于语句和查询的命名参数设置 - 它解析SQL，并在实际构建准备好的语句时使用位置参数。上面的示例使用默认的冒号分隔解析器(: )，但还包括一个替代的散列分隔解析器(? )，以便与在其语法中使用冒号的数据库（如PostgreSQL）一起使用。

SQL Object API

The second, SQL object, style API simplifies the common idiom of creating DAO objects where a single method maps to a single statement.
SQL对象式 API, 简化了创建 DAO 对象的常见写法，它将单个数据库执行语句映射到了单个方法上。

A SQL object definition is an annotated interface, such as:
定义一个 SQL 对象就是一个注释接口，如：

public interface MyDAO
{
  @SqlUpdate("create table something (id int primary key, name varchar(100))")
  void createSomethingTable();

  @SqlUpdate("insert into something (id, name) values (:id, :name)")
  void insert(@Bind("id") int id, @Bind("name") String name);

  @SqlQuery("select name from something where id = :id")
  String findNameById(@Bind("id") int id);

  /**
   * close with no args is used to close the connection
   */
  void close();
}

This interface defines two updates, the first to create the same table as in the fluent api example, and the second to do the same insert, the third defines a query. In the second two cases, notice that the arguments to the statements are past to the method, and bound by name.
这个接口定义了两个数据库更新方法，第一个方法是创建与流 api 示例中相同的表，第二个方法则是同样的插入操作，第三个方法定义了一个查询操作。 在第二种用法上，请注意，数据库查询语句里的参数是传递到方法的参数，并以名称绑定。

The final method, close(), is special. When it is invoked it will close the underlying JDBC connection.
最后的方法close（）是特殊的。 当它被调用时，它将关闭底层的JDBC连接。

The method may be declared to raise an exception, such as the close() method does on java.io.Closeable, making it suitable for use with automatic resource management in Java 7.
该方法可能会引发异常，例如 java.io.Closeable 中的 close() 方法，我们应使其适用于 Java 7 中的自动资源管理写法。

To use this sql object definition, we use code like so:

// using in-memory H2 database via a pooled DataSource
JdbcConnectionPool ds = JdbcConnectionPool.create("jdbc:h2:mem:test2",
                                                  "username",
                                                  "password");
DBI dbi = new DBI(ds);

MyDAO dao = dbi.open(MyDAO.class);

dao.createSomethingTable();

dao.insert(2, "Aaron");

String name = dao.findNameById(2);

assertThat(name, equalTo("Aaron"));

dao.close();
ds.dispose();

We obtain an instance of the sql object from the DBI instance, and then call methods on it. There are a couple different ways of creating sql object instances.
我们从 DBI 实例获取一个 sql 对象的实例，然后调用它的方法。 有几种创建 sql 对象实例的方法。

The one here binds the object to a specific handle, so we need to make sure to close the object when we are finished with it.
一个是，将对象绑定到一个特定的句柄。所以我们需要确保在完成它时，关闭这个对象。

JDBI website