Skip to main content

Call Builder API

After a Mapper interface extends BaseMapper<T>, it can call builder capabilities such as query(), update(), delete(), and insert() from default methods or business code.

Suitable For​

  • Conditions are composed in Java code, which is more natural than writing dynamic SQL.
  • Entity mappings should be reused, avoiding hand-written table and column names.
  • Complex queries should be encapsulated as default methods on a Mapper interface.

Not Suitable For​

  • SQL is already stable and short – use method annotations for clarity.
  • SQL is long or needs complex XML mappings – use Mapper files.
  • Simple single-table CRUD – use BaseMapper's CRUD methods directly.

Pattern in Mapper​

UserMapper.java
@SimpleMapper
public interface UserMapper extends BaseMapper<User> {
    default List<User> listActiveUsers(String name, int minAge) {
        return query()
                .eq(User::getStatus, "ACTIVE")
                .like(name != null, User::getName, name)
                .ge(User::getAge, minAge)
                .orderByDesc(User::getCreateTime)
                .queryForList();
    }
}

The caller still only interacts with the Mapper interface:

Using the Mapper
UserMapper mapper = session.createMapper(UserMapper.class);
List<User> users = mapper.listActiveUsers("alice", 18);

Common Examples​

Insert
mapper.insert()
        .applyEntity(user)
        .executeSumResult();
Update
mapper.update()
        .eq(User::getId, 1)
        .updateTo(User::getName, "Mary")
        .updateTo(User::getStatus, 2)
        .doUpdate();
Delete
mapper.delete()
        .eq(User::getId, 1)
        .doDelete();
Query
List<User> result = mapper.query()
        .le(User::getId, 100)
        .queryForList();
tip

How to obtain a Session depends on your project architecture. See Framework Integration.

Further Reading​