JDBC Result Mapping
@CompiledJdbcMapper generates direct mappings from JDBC ResultSet columns to Java objects. It handles row mapping, not SQL execution, connection management, or transactions.
Targets include POJOs, records, JOJOs, and Map<String, Object>. This is separate from Java-to-Java Object Mapping.
Getting Started
Start with an ordinary Java class:
class User {
public String userName;
public int age;
public User() {}
}Declare single-row, multi-row, or prepared mappings:
@CompiledJdbcMapper
interface UserJdbcMapper {
User user(ResultSet rs);
List<User> users(ResultSet rs);
JdbcRowMapper<User> prepare(ResultSetMetaData metadata);
}
UserJdbcMapper mapper = CompiledInstances.create(UserJdbcMapper.class);
try (Statement statement = connection.createStatement();
ResultSet rs = statement.executeQuery(
"SELECT user_name, age FROM users")) {
List<User> users = mapper.users(rs);
}The ResultSet must be positioned before its first row for the first two methods; generated code advances the cursor.
| Method | Behavior |
|---|---|
User user(ResultSet rs) | Returns one object, null if empty, and fails on multiple rows by default |
List<User> users(ResultSet rs) | Reads the remaining rows into a list |
Use @JdbcMappingOptions(singleResult = SingleResultPolicy.FIRST) when a single-object method should select only the first row.
SJF4J never closes the supplied ResultSet. Your JDBC code remains responsible for its lifecycle.
Prepared Row Mapping
For an existing cursor loop, prepare a reusable row mapper from the result metadata:
JdbcRowMapper<User> rowMapper = mapper.prepare(rs.getMetaData());
while (rs.next()) {
User user = rowMapper.map(rs);
// Process the current row
}prepare() resolves the column layout once. The returned JdbcRowMapper<User> keeps column indexes and labels but does not own the ResultSet.
map(rs) maps only the current row: it does not advance or close the cursor. Prepared row mappers are stateless and reusable for results with the same column layout.
Column Mapping
Column labels match Java properties automatically. For example, user_name maps to userName by default.
ColumnNamingPolicy | Matching |
|---|---|
EXACT | Exact label and case |
INSENSITIVE | Exact first, then case-insensitive |
INSENSITIVE_SNAKE | Also matches camelCase to snake_case (default) |
Override individual columns with @Mapping:
@CompiledJdbcMapper
interface LegacyUserMapper {
@Mapping(target = "userName", source = "full_name")
User user(ResultSet rs);
}Use @JdbcMappingOptions for method-specific behavior:
columnProjection = REQUIRE_ALL(default) requires columns for mapped POJO properties;PRESENT_ONLYleaves absent mutable properties at their initial values.singleResult = FAIL_ON_MULTIPLE(default) rejects multiple rows for a single-object method;FIRSTselects one.columnNamingselects the matching policy above.
An ambiguous match within the same naming tier fails explicitly. JDBC mapping also supports constructor/record targets and @MappingCreator for custom construction.
Framework Integration
Prepared mappers work with existing JDBC frameworks. For example, with Spring JdbcTemplate:
UserJdbcMapper mapper = CompiledInstances.create(UserJdbcMapper.class);
List<User> users = jdbcTemplate.query(
"SELECT user_name, age FROM users", rs -> {
JdbcRowMapper<User> rowMapper = mapper.prepare(rs.getMetaData());
List<User> result = new ArrayList<>();
while (rs.next()) {
result.add(rowMapper.map(rs));
}
return result;
});Spring handles query execution and resource management; SJF4J maps the rows. With sjf4j-spring or the Spring Boot Starter, UserJdbcMapper is available through @Autowired — no manual CompiledInstances.create() needed. See Spring Integration. Plain JDBC requires no Spring dependency.
To enable code generation, see Installation.
Performance
In the measured Customer Account POJO workload, generated list mapping outperforms Spring JDBC's BeanPropertyRowMapper and MyBatis automatic mapping.
See JDBC Result Mapping benchmarks and the full benchmark report. The benchmarks include ResultSet traversal and object materialization, not SQL execution or network I/O.
API Reference (latest release): @CompiledJdbcMapper · JdbcRowMapper · @JdbcMappingOptions