Call File Mapper

File Mapper keeps SQL in XML files for maintenance. Mapper API maps interface methods or statement IDs to those SQL statements.

Suitable For

• SQL is long and hard to read inside annotations.
• You need to reuse rules, dynamic SQL tags, resultMap, or entity mappings.
• SQL should be centrally maintained in dedicated files, with interfaces keeping only method signatures.

Not Suitable For

• Short SQL – use method annotations for clarity.
• Simple single-table CRUD – prefer BaseMapper.
• Conditions composed in code – prefer Builder API.

Interface Call (Recommended)

Use @RefMapper to bind an interface to an XML file. The XML namespace should be the fully qualified interface name, and the statement id should match the interface method name.

UserMapper.java

@RefMapper("/mapper/userMapper.xml")
public interface UserMapper {
    List<User> listUsers(@Param("name") String name);
}

mapper/userMapper.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//dbvisitor.net//DTD Mapper 1.0//EN"
        "https://www.dbvisitor.net/schema/dbvisitor-mapper.dtd">
<mapper namespace="net.example.mapper.UserMapper">
    <select id="listUsers" resultType="net.example.dto.User">
        select * from users
        where 1 = 1
        @{and, name like concat('%', #{name}, '%')}
    </select>
</mapper>

Using the Mapper

Session session = config.newSession(dataSource);
UserMapper mapper = session.createMapper(UserMapper.class);

List<User> users = mapper.listUsers("alice");

tip

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

Direct Statement Call

If you don't have an interface method, you can also call XML SQL directly via statement ID. The statement ID is typically namespace + "." + id.

Call via BaseMapper

BaseMapper<User> mapper = session.createBaseMapper(User.class);
List<User> users = mapper.queryStatement("net.example.mapper.UserMapper.listUsers", args);

Call via Session

List<User> users = session.queryStatement("net.example.mapper.UserMapper.listUsers", args);

note

Interface calls are better for business code: the method signature is the contract. Direct statement calls are more suitable for framework wrappers, migration compatibility, or a few low-level scenarios.

Pagination Query

An interface method can accept a Page parameter and return either List<User> or PageResult<User> with totals. Reuse the XML above and change the method signature to:

@RefMapper("/mapper/userMapper.xml")
public interface UserMapper {
    PageResult<User> listUsers(@Param("name") String name, Page page);
}

Call mapper.listUsers("alice", PageObject.of(0, 20)) to retrieve the first page and the total number of matching records.

For direct statement calls, both BaseMapper and Session support queryStatement with pagination:

Pagination query (returns List)

Page page = PageObject.of(0, 20);
BaseMapper<User> mapper = session.createBaseMapper(User.class);

List<User> users = mapper.queryStatement(
        "net.example.mapper.UserMapper.listUsers",
        args,
        page);

Session pagination query (returns PageResult)

Page page = PageObject.of(0, 20);
PageResult<User> users = session.pageStatement(
        "net.example.mapper.UserMapper.listUsers",
        args,
        page);

PageResult contains the original pagination info, total record count, and total page count.

Further Reading

• Mapper File — XML document structure, tags, dynamic SQL, mapping configuration.
• Statement Tags — <select>, <insert>, <update>, <delete> and other tags.
• Pagination Query — Pagination capabilities of File Mapper.
• Parameter Passing — How Mapper method parameters and statement parameters are bound.