Jdbi3官方教程（一） 简介
Jdbi3官方教程（二） 入门
Jdbi3官方教程（三） Jdbi和Handle
Jdbi3官方教程（四） 参数绑定
Jdbi3官方教程（五） 查询Query
Jdbi3官方教程（六） 映射器Mapper
3.5 映射器
Jdbi利用映射器将结果数据转换为Java对象。有两种类型的映射器：
- 行映射器，映射整行结果集数据。
- 列映射器，映射结果集行的单个列。
3.5.1 行映射器
RowMapper是一个函数接口，它将JDBC ResultSet的当前行 映射到被映射的类型。对于结果集中的每一行，将调用一次行映射器。
由于RowMapper是一个函数接口，因此可以使用lambda表达式将它们内联到查询中：
List users = handle.createQuery("SELECT id, name FROM user ORDER BY id ASC")
.map((rs, ctx) -> new User(rs.getInt("id"), rs.getString("name")))
.list();
- mapTo加类型，map加映射函数
在上面的例子中使用了三种不同的类型。
Handle.createQuery()返回的Query，实现了ResultBearing接口。该ResultBearing.map()方法采输入一个RowMapper并返回一个ResultIterable。最后，ResultBearing.list()将结果集中的每一行收集到一个List。
行映射器可以定义为类，允许重用：
class UserMapper implements RowMapper {
@Override
public User map(ResultSet rs, StatementContext ctx) throws SQLException {
return new User(rs.getInt("id"), rs.getString("name"));
}
}
List users = handle.createQuery("SELECT id, name FROM user ORDER BY id ASC")
.map(new UserMapper())
.list();
RowMapper相当于上面的lambda映射器，但更明确。
RowMappers注册表
可以为特定类型注册行映射器。这简化了使用，只需要指定要映射到的类型。Jdbi会自动从注册表中查找映射器并使用它。
jdbi.registerRowMapper(User.class,
(rs, ctx) -> new User(rs.getInt("id"), rs.getString("name"));
try (Handle handle = jdbi.open()) {
List users = handle.createQuery("SELECT id, name FROM user ORDER BY id ASC")
.mapTo(User.class)
.list();
}
它实现了一个映射器RowMapper具有显式映射类型（如 UserMapper前一节中的类）可以被注册，而无需指定映射类型：
handle.registerRowMapper(new UserMapper());
使用此方法时，Jdbi会检查映射器的泛型类签名以自动发现映射类型。
- jdbi和handle都能注册
- 可以注册Mapper，也可以动态注册映射函数
对于任何给定类型，可以注册多个映射器。发生这种情况时，给定类型的最后注册的映射器优先。这允许进行优化，例如为某些类型注册“默认”映射器，同时允许在适当时使用不同的映射器覆盖该默认映射器。
RowMapperFactory
待补充...
3.5.2 列映射器
ColumnMapper是一个函数式接口，它将JDBC ResultSet的当前行中的列 映射到映射类型。
由于ColumnMapper是一个函数式接口，因此可以使用lambda表达式将它们内联到查询中：
List amounts = handle
.select("select amount from transactions where account_id = ?", accountId)
.map((rs, col, ctx) -> Money.parse(rs.getString(col)))
.list();
每当使用列映射器映射行时，只映射每行的第一列。
列映射器可以定义为类，允许重用：
public class MoneyMapper implements ColumnMapper {
public T map(ResultSet r, int columnNumber, StatementContext ctx) throws SQLException {
return Money.parse(r.getString(columnNumber));
}
}
List amounts = handle
.select("select amount from transactions where account_id = ?", accountId)
.map(new MoneyMapper())
.list();
这ColumnMapper相当于上面的lambda映射器，但更明确。
ColumnMappers注册表
可以为特定类型注册列映射器。这简化了使用，只需要指定要映射到的类型。Jdbi会自动从注册表中查找映射器并使用它。
jdbi.registerColumnMapper(Money.class,
(rs, col, ctx) -> Money.parse(rs.getString(col)));
List amounts = jdbi.withHandle(handle ->
handle.select("select amount from transactions where account_id = ?", accountId)
.mapTo(Money.class)
.list());
它实现了一个映射器ColumnMapper具有显式映射类型（如MoneyMapper前一节中的类）可以被注册，而无需指定映射类型：
handle.registerColumnMapper(new MoneyMapper());
使用此方法时，Jdbi会检查映射器的泛型类签名以自动发现映射类型。
对于任何给定类型，可以注册多个映射器。发生这种情况时，给定类型的最后注册的映射器优先。这允许进行优化，例如为某些类型注册“默认”映射器，同时允许在适当时使用不同的映射器覆盖该默认映射器。
列映射器注册了以下类型：
- 原语：
boolean，byte，short，int，long，char，float，和double - java.lang中：
Boolean，Byte，Short，Integer，Long，Character，Float，Double，String，和Enum（存储为枚举值的名字） - java.math中：
BigDecimal -
byte[]数组（例如BLOB或VARBINARY列） - java.net： ，
InetAddress，URL和URI - java.sql中：
Timestamp - java.time： ，
Instant，LocalDate，LocalDateTime，LocalTime，OffsetDateTime，ZonedDateTime和ZoneId - java.util中：
UUID -
java.util.Collection和Java数组（用于数组列）。根据数组元素的类型，可能还需要一些额外的设置 - 请参阅 SQL数组。
ColumnMapperFactory
待补充...
3.5.3 反射映射器
Jdbi提供了一些开箱即用的基于反射的映射器。
反射映射器将列名视为bean属性名称（BeanMapper），构造函数参数名称（ConstructorMapper）或字段名称（FieldMapper）。
反射映射器可识别snake_case，并会自动将这些列与camelCase字段/参数/属性名称匹配。
ConstructorMapper
Jdbi提供了一个简单的构造函数映射器，它使用反射按名称将列分配给构造函数参数。
@ConstructorProperties({"id", "name"})
public User(int id, String name) {
this.id = id;
this.name = name;
}
该@ConstructorProperties注解告诉Jdbi每个构造函数参数的属性名称，因此它可以找出哪些列对应于每一个构造函数的参数。
启用-parametersJava编译器标志将不再需要 @ConstructorProperties注释 - 请参阅使用参数名称进行编译。从而：
public User(int id, String name) {
this.id = id;
this.name = name;
}
使用以下factory() 方法为映射的类注册构造函数映射器：
handle.registerRowMapper(ConstructorMapper.factory(User.class));
Set userSet = handle.createQuery("SELECT * FROM user ORDER BY id ASC")
.mapTo(User.class)
.collect(Collectors.toSet());
assertThat(userSet).hasSize(4);
构造函数参数名称“id”，“name”与数据库列名称匹配，因此根本不需要自定义映射器代码。
可以为每个映射的构造函数参数配置构造函数映射器的列名前缀。这有助于消除映射连接的歧义，例如，当两个映射的类具有相同的属性名称（如id或name）时：
handle.registerRowMapper(ConstructorMapper.factory(Contact.class, "c"));
handle.registerRowMapper(ConstructorMapper.factory(Phone.class, "p"));
handle.registerRowMapper(JoinRowMapper.forTypes(Contact.class, Phone.class);
List contactPhones = handle.select("select " +
"c.id cid, c.name cname, " +
"p.id pid, p.name pname, p.number pnumber " +
"from contacts c left join phones p on c.id = p.contact_id")
.mapTo(JoinRow.class)
.list();
通常，映射的类将具有单个构造函数。如果它有多个构造函数，Jdbi将根据这些规则选择一个：
- 首先，使用带注释的构造函数
@JdbiConstructor（如果有）。 - 接下来，使用带注释的构造函数
@ConstructorProperties（如果有）。 - 否则，抛出Jdbi不知道要使用哪个构造函数的异常。
对于与属性名称不匹配的旧列名称，请使用 @ColumnName批注提供精确的列名称。
public User(@ColumnName("user_id") int id, String name) {
this.id = id;
this.name = name;
}
可以使用@Nested注释映射嵌套的构造函数注入类型：
public class User {
public User(int id,
String name,
@Nested Address address) {
...
}
}
public class Address {
public Address(String street,
String city,
String state,
String zip) {
...
}
}
handle.registerRowMapper(ConstructorMapper.factory(User.class));
List users = handle
.select("select id, name, street, city, state, zip from users")
.mapTo(User.class)
.list();
该@Nested注释有一个可选的value()属性，该属性可以被用于一列名的前缀应用于每个嵌套构造参数：
public User(int id,
String name,
@Nested("addr") Address address) {
...
}
handle.registerRowMapper(ConstructorMapper.factory(User.class));
List users = handle
.select("select id, name, addr_street, addr_city, addr_state, addr_zip from users")
.mapTo(User.class)
.list();
BeanMapper
我们还为映射bean提供基本支持：
public class UserBean {
private int id;
private String name;
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
}
使用以下factory()方法为映射的类注册bean映射器：
handle.registerRowMapper(BeanMapper.factory(UserBean.class));
List users = handle
.createQuery("select id, name from user")
.mapTo(UserBean.class)
.list();
或者，调用mapToBean()而不是注册bean映射器：
List users = handle
.createQuery("select id, name from user")
.mapToBean(UserBean.class)
.list();
可以为每个映射属性配置Bean映射器的列名前缀。这有助于消除映射连接的歧义，例如，当两个映射的类具有相同的属性名称（如id或name）时：
handle.registerRowMapper(BeanMapper.factory(ContactBean.class, "c"));
handle.registerRowMapper(BeanMapper.factory(PhoneBean.class, "p"));
handle.registerRowMapper(JoinRowMapper.forTypes(ContactBean.class, PhoneBean.class));
List contactPhones = handle.select("select "
+ "c.id cid, c.name cname, "
+ "p.id pid, p.name pname, p.number pnumber "
+ "from contacts c left join phones p on c.id = p.contact_id")
.mapTo(JoinRow.class)
.list();
对于与属性名称不匹配的旧列名称，请使用 @ColumnName批注提供精确的列名称。
public class User {
private int id;
@ColumnName("user_id")
public int getId() { return id; }
public void setId(int id) { this.id = id; }
}
所述@ColumnName注释可以放在任一getter或setter方法。
可以使用@Nested注释映射嵌套的Java Bean类型：
public class User {
private int id;
private String name;
private Address address;
... (getters and setters)
@Nested
public Address getAddress() { ... }
public void setAddress(Address address) { ... }
}
public class Address {
private String street;
private String city;
private String state;
private String zip;
... (getters and setters)
}
handle.registerRowMapper(BeanMapper.factory(User.class));
List users = handle
.select("select id, name, street, city, state, zip from users")
.mapTo(User.class)
.list();
该@Nested注释有一个可选的value()属性，该属性可以被用于一列名的前缀应用于每个嵌套bean属性：
@Nested("addr")
public Address getAddress() { ... }
handle.registerRowMapper(BeanMapper.factory(User.class));
List users = handle
.select("select id, name, addr_street, addr_city, addr_state, addr_zip from users")
.mapTo(User.class)
.list();
FieldMapper
FieldMapper使用反射将数据库列直接映射到对象字段（包括私有字段）。
public class User {
public int id;
public String name;
}
使用以下factory()方法为映射的类注册一个字段映射器：
handle.registerRowMapper(FieldMapper.factory(User.class));
List users = handle
.createQuery("select id, name from user")
.mapTo(User.class)
.list();
可以为每个映射字段配置字段映射器的列名前缀。这有助于消除映射连接的歧义，例如，当两个映射的类具有相同的属性名称（如id或name）时：
handle.registerRowMapper(FieldMapper.factory(Contact.class, "c"));
handle.registerRowMapper(FieldMapper.factory(Phone.class, "p"));
handle.registerRowMapper(JoinRowMapper.forTypes(Contact.class, Phone.class);
List contactPhones = handle.select("select " +
"c.id cid, c.name cname, " +
"p.id pid, p.name pname, p.number pnumber " +
"from contacts c left join phones p on c.id = p.contact_id")
.mapTo(JoinRow.class)
.list();
对于与字段名称不匹配的旧列名称，请使用 @ColumnName批注提供精确的列名称：
public class User {
@ColumnName("user_id")
public int id;
public String name;
}
可以使用@Nested注释映射嵌套的字段映射类型：
public class User {
public int id;
public String name;
@Nested
public Address address;
}
public class Address {
public String street;
public String city;
public String state;
public String zip;
}
handle.registerRowMapper(FieldMapper.factory(User.class));
List users = handle
.select("select id, name, street, city, state, zip from users")
.mapTo(User.class)
.list();
该@Nested注释有一个可选的value()属性，该属性可以被用于一列名的前缀应用于每个嵌套字段：
public class User {
public int id;
public String name;
@Nested("addr")
public Address address;
}
handle.registerRowMapper(FieldMapper.factory(User.class));
List users = handle
.select("select id, name, addr_street, addr_city, addr_state, addr_zip from users")
.mapTo(User.class)
.list();
Map.Entry映射
Jdbi注册了一个RowMapper。由于结果集中的每一行都是Map.Entry，因此整个结果集可以很容易地收集到Map（或Guava Multimap）中。
通过指定通用映射签名，可以将连接行收集到映射结果中：
String sql = "select u.id u_id, u.name u_name, p.id p_id, p.phone p_phone "
+ "from user u left join phone p on u.id = p.user_id";
Map map = h.createQuery(sql)
.registerRowMapper(ConstructorMapper.factory(User.class, "u"))
.registerRowMapper(ConstructorMapper.factory(Phone.class, "p"))
.collectInto(new GenericType>() {});
在前面的示例中，User映射器使用“u”列名称前缀，Phone映射器使用“p”。由于每个映射器只读取具有预期前缀的id列，因此相应的列是明确的。
通过设置键列名称可以获得唯一索引（例如，通过ID列）：
Map map = h.createQuery("select * from user")
.setMapKeyColumn("id")
.registerRowMapper(ConstructorMapper.factory(User.class))
.collectInto(new GenericType>() {});
设置键列值和值列，以将两列查询收集到映射结果中：
Map map = h.createQuery("select key, value from config")
.setMapKeyColumn("key")
.setMapValueColumn("value")
.collectInto(new GenericType>() {});
所有上述示例都假设一对一键/值关系。如果有一对多关系怎么办？
Google Guava提供了一种Multimap类型，支持为每个键映射多个值。
首先，按照Google Guava部分中的说明安装 GuavaPlugin到Jdbi中。
然后，只需要一个Multimap而不是Map：
String sql = "select u.id u_id, u.name u_name, p.id p_id, p.phone p_phone "
+ "from user u left join phone p on u.id = p.user_id";
Multimap map = h.createQuery(sql)
.registerRowMapper(ConstructorMapper.factory(User.class, "u"))
.registerRowMapper(ConstructorMapper.factory(Phone.class, "p"))
.collectInto(new GenericType>() {});
该collectInto()方法值得解释，当调用时，幕后发生了几件事：
- 请查询
JdbiCollectors注册表以获取支持给定容器类型的 CollectorFactory。 - 接下来，要求
CollectorFactory从容器类型签名中提取元素类型。在上面的例子中，元素类型Multimap是Map.Entry。 - 从映射注册表获取该元素类型的映射器。
- 从中获取容器类型的收集器
CollectorFactory。 - 最后，回来
map(elementMapper).collect(collector)。
可以增强Jdbi以支持任意容器类型。有关详细信息，请参阅 [JdbiCollectors]。
- Jdbi3官方教程（一） 简介
- Jdbi3官方教程（二） 入门
- Jdbi3官方教程（三） Jdbi和Handle
- Jdbi3官方教程（四） 参数绑定
- Jdbi3官方教程（五） 查询Query
- Jdbi3官方教程（六）映射器Mapper
- Jdbi3官方教程（七）结果Result