Simplified Java Database Access with SqlMapper

.NET has a large amount of Micro ORMs (Dapper, NPoco, OrmLite, ...) to access databases in a very simple way, while Java is lacking small libraries. SqlMapper is a wrapper over the JDBC ResultSet, and makes it very easy to map between Java Beans and a database table:

Basic Usage

Imagine we want to read a list of Persons from a database, where each Person has a first name, last name and a birthdate.

Database Table

The table in the database could look like this (PostgreSQL):

CREATE TABLE sample.unit_test
    first_name text,
    last_name text,
    birth_date date

Domain Model

The domain model in the application might look like this:

private class Person {

    private String firstName;

    private String lastName;

    private LocalDate birthDate;

    public Person() {}

    public String getFirstName() {
        return firstName;

    public void setFirstName(String firstName) {
        this.firstName = firstName;

    public String getLastName() {
        return lastName;

    public void setLastName(String lastName) {
        this.lastName = lastName;

    public LocalDate getBirthDate() {
        return birthDate;

    public void setBirthDate(LocalDate birthDate) {
        this.birthDate = birthDate;

Define the Mapping

All you have implement is the mapping between both, which is done with a ResultSetMapping:

public class PersonMap extends ResultSetMapping<Person>
    public PersonMap() {
        map("first_name", String.class, Person::setFirstName);
        map("last_name", String.class, Person::setLastName);
        map("birth_date", LocalDate.class, Person::setBirthDate);

Map ResultSet to an Entity

An SqlMapper is used to perform the actual mapping between a ResultSet and the Entities. It takes an IObjectCreator and an ResultSetMapping. TheIObjectCreator`` is a functional interface, that is used to instantiate a target object.

The SqlMapper.toEntity method returns a SqlMappingResult<TEntity>. The SqlMappingResult<TEntity> holds either the populated target object or an error, which can be checked with the SqlMappingResult<TEntity>.isValid() method.

If the mapping was successful, the populated entity can be obtained by calling SqlMappingResult<TEntity>.getEntity().

public void testToEntity() throws Exception {
    SqlMapper<Person> sqlMapper = new SqlMapper<>(() -> new Person(), new PersonMap());

    Person person0 = new Person();

    person0.firstName = "Philipp";
    person0.lastName = "Wagner";
    person0.birthDate = LocalDate.of(1986, 5, 12);


    ResultSet resultSet = selectAll();

    while ( ) {

        SqlMappingResult<Person> person = sqlMapper.toEntity(resultSet);

        Assert.assertEquals(true, person.isValid());

        Assert.assertEquals("Philipp", person.getEntity().get().getFirstName());
        Assert.assertEquals("Wagner", person.getEntity().get().getLastName());
        Assert.assertEquals(LocalDate.of(1986, 5, 12), person.getEntity().get().getBirthDate());