How it Works

MyBatis does four main things:

1. It executes SQL safely and abstracts away all the intricacies of JDBC
2. It maps parameter objects to JDBC prepared statement parameters
3. It maps rows in JDBC result sets to objects
4. It can generate dynamic SQL with special tags in XML, or through the use of various templating engines

This library takes full advantage of the first three capabilities in MyBatis and essentially becomes another templating engine for generating dynamic SQL.

For example, MyBatis can execute an SQL string formatted like this:

  select id, description from table_codes where id = #{id,jdbcType=INTEGER}

This is standard SQL with a MyBatis twist - the parameter notation #{id,jdbcType=INTEGER} tells MyBatis to take the id property of a parameter object and use it as a JDBC prepared statement parameter.

Now suppose we have two Java classes like this:

public class TableCode {
  private Integer id;
  private String description;
  ... getters/setters
}

public class Parameter {
  private String sql = "select id, description from table_codes where id = #{id,jdbcType=INTEGER}";
  private Integer id;

  public Parameter(Integer id) {
    this.id = id;
  }

  public Integer getId() {
    return id;
  }

  public String getSql() {
    return sql;
  }
}

These classes can be used in conjunction with a MyBatis mapper like this:

public interface Mapper {

  @Select({
    "${sql}"
  })
  TableCode getTableCode(Parameter parameter);
}

Using this mapper with MyBatis looks like this:

  try(SqlSession sqlSession = sqlSessionFactory.openSession()) {
    Mapper mapper = sqlSession.getMapper(Mapper.class);
    Parameter parameter = new Parameter(2);
    TableCode tableCode = mapper.getTableCode(parameter);
    assertThat(tableCode.getId()).isEqualTo(2);
  }

The parameter object has a property called sql. That SQL string will be prepared as a JDBC prepared statement in MyBatis. The SQL string also references a property called id. That property - from the same parameter object - will be used as the value of the prepared statement parameter.

So the main idea is this - this library builds a version of the Parameter class shown above. The class includes the full SQL statement to execute, formatted for MyBatis, and any parameters referenced by the statement. There are different versions of these classes for the different types of SQL statements. But in every case, the class is designed to be the one single parameter for a MyBatis mapper method.