Use Mybatis every day, but do you really know how it works?

Keywords: Java Mybatis SQL xml JDBC

Recently, I want to write a mybatis paging plug-in, but before I write the plug-in, I must understand the specific working principle of mybatis, so I will start to work by referring to other blogs and reading the source code.

Core components:

  • SqlSession

  • Executor

  • StatementHandler

  • ParameterHandler

  • ResultSetHandler

  • TypeHandler

  • MappedStatement

  • Configuration

Before analyzing how it works, first take a look at my mybatis global configuration file

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration
PUBLIC "-// Config 3.0//EN"
    <!-- and spring After integration environments Configuration will be abolished -->
    <environments default="development">
        <environment id="development">
            <!-- Use jdbc transaction management -->
            <transactionManager type="JDBC" />
            <!-- Database connection pool -->
            <dataSource type="POOLED">
                <property name="driver" value="com.mysql.jdbc.Driver" />
                <property name="url"
                    value="jdbc:mysql://localhost:3306/test?characterEncoding=utf-8" />
                <property name="username" value="root" />
                <property name="password" value="123456" />
       <mapper  resource="sqlMapper/userMapper.xml"/>

Step 1: create an sqlSessionFactory

Before you learn how to create sqlSessionFactory, take a look at how mybatis loads the global Configuration file and parses the xml file to generate the Configuration

public Configuration parse() {
    if (parsed) {
      throw new BuilderException("Each XMLConfigBuilder can only be used once.");
    parsed = true;
    return configuration;

private void parseConfiguration(XNode root) {
    try {
      propertiesElement(root.evalNode("properties")); //issue #117 read properties first
      environmentsElement(root.evalNode("environments")); // read it after objectFactory and objectWrapperFactory issue #631
    } catch (Exception e) {
      throw new BuilderException("Error parsing SQL Mapper Configuration. Cause: " + e, e);

There is a sentence in the second code above


Just in our global configuration file, there is a mapper configuration. Thus, mapperElemet() method parses the mapper mapping file. The specific code is as follows

private void mapperElement(XNode parent) throws Exception {
    if (parent != null) {
      for (XNode child : parent.getChildren()) {
        if ("package".equals(child.getName())) {
          String mapperPackage = child.getStringAttribute("name");
        } else {
          String resource = child.getStringAttribute("resource");
          String url = child.getStringAttribute("url");
          String mapperClass = child.getStringAttribute("class");
          if (resource != null && url == null && mapperClass == null) {//Enter the judgment
            InputStream inputStream = Resources.getResourceAsStream(resource);
            XMLMapperBuilder mapperParser = new XMLMapperBuilder(inputStream, configuration, resource, configuration.getSqlFragments());
          } else if (resource == null && url != null && mapperClass == null) {
            InputStream inputStream = Resources.getUrlAsStream(url);
            XMLMapperBuilder mapperParser = new XMLMapperBuilder(inputStream, configuration, url, configuration.getSqlFragments());
          } else if (resource == null && url == null && mapperClass != null) {
            Class<?> mapperInterface = Resources.classForName(mapperClass);
          } else {
            throw new BuilderException("A mapper element may only specify a url, resource or class, but not more than one.");

According to the above code, when writing the address of mapper mapping file, it can be written not only as resource, but also in the form of url and maperclass. Because we use resource, we can directly enter the first judgment. Finally, the method of parsing mapper mapping file is

private void configurationElement(XNode context) {
    try {
      String namespace = context.getStringAttribute("namespace");
      if (namespace.equals("")) {
          throw new BuilderException("Mapper's namespace cannot be empty");
    } catch (Exception e) {
      throw new BuilderException("Error parsing Mapper XML. Cause: " + e, e);

Among them, the specific analysis of each sql statement node is


Go to this method and go deep into it. At last, we can know that MappedStatement is created by builder assistant.

public void parseStatementNode() {
    builderAssistant.addMappedStatement(id, sqlSource, statementType, sqlCommandType,
        fetchSize, timeout, parameterMap, parameterTypeClass, resultMap, resultTypeClass,
        resultSetTypeEnum, flushCache, useCache, resultOrdered, 
        keyGenerator, keyProperty, keyColumn, databaseId, langDriver, resultSets);

Finally, enter the method addMappedStatement(), mappedStatement and save it in a map variable mappedStatements in Configuration with id as the key.

public MappedStatement addMappedStatement(
      String id,
      SqlSource sqlSource,
      StatementType statementType,
      SqlCommandType sqlCommandType,
      Integer fetchSize,
      Integer timeout,
      String parameterMap,
      Class<?> parameterType,
      String resultMap,
      Class<?> resultType,
      ResultSetType resultSetType,
      boolean flushCache,
      boolean useCache,
      boolean resultOrdered,
      KeyGenerator keyGenerator,
      String keyProperty,
      String keyColumn,
      String databaseId,
      LanguageDriver lang,
      String resultSets) {

    if (unresolvedCacheRef) throw new IncompleteElementException("Cache-ref not yet resolved");

    id = applyCurrentNamespace(id, false);
    boolean isSelect = sqlCommandType == SqlCommandType.SELECT;

    MappedStatement.Builder statementBuilder = new MappedStatement.Builder(configuration, id, sqlSource, sqlCommandType);
    setStatementTimeout(timeout, statementBuilder);

    setStatementParameterMap(parameterMap, parameterType, statementBuilder);
    setStatementResultMap(resultMap, resultType, resultSetType, statementBuilder);
    setStatementCache(isSelect, flushCache, useCache, currentCache, statementBuilder);

    MappedStatement statement =;
    return statement;

Finally, we go back to our creation of sqlSessionFactory. All the previous work is to generate a sqlSessionFactory service

public SqlSessionFactory build(InputStream inputStream, String environment, Properties properties) {
    try {
      XMLConfigBuilder parser = new XMLConfigBuilder(inputStream, environment, properties);
      return build(parser.parse());
    } catch (Exception e) {
      throw ExceptionFactory.wrapException("Error building SqlSession.", e);
    } finally {
      try {
      } catch (IOException e) {
        // Intentionally ignore. Prefer previous error.

  public SqlSessionFactory build(Configuration config) {
    return new DefaultSqlSessionFactory(config);

From the above code, we can see that the final step is to generate the DefautSqlSessionFactory with the Configuration as the parameter build() method.

Step 2: create sqlSession

  public SqlSession openSession() {
    return openSessionFromDataSource(configuration.getDefaultExecutorType(), null, false);

private SqlSession openSessionFromDataSource(ExecutorType execType, TransactionIsolationLevel level, boolean autoCommit) {
    Transaction tx = null;
    try {
      final Environment environment = configuration.getEnvironment();
      final TransactionFactory transactionFactory = getTransactionFactoryFromEnvironment(environment);
      tx = transactionFactory.newTransaction(environment.getDataSource(), level, autoCommit);
      final Executor executor = configuration.newExecutor(tx, execType);
      return new DefaultSqlSession(configuration, executor, autoCommit);
    } catch (Exception e) {
      closeTransaction(tx); // may have fetched a connection so lets call close()
      throw ExceptionFactory.wrapException("Error opening session.  Cause: " + e, e);
    } finally {

//Returns a SqlSession. DefaultSqlSession is used by default
 public DefaultSqlSession(Configuration configuration, Executor executor, boolean autoCommit) {
    this.configuration = configuration;
    this.executor = executor;
    this.dirty = false;
    this.autoCommit = autoCommit;

The executor is created in this step, and the specific use is in the next step.

Step 3: execute the specific sql request

What's going on in my code is

User user = sqlSession.selectOne("test.findUserById", 1);

The specific way is

public <E> List<E> selectList(String statement, Object parameter, RowBounds rowBounds) {
    try {
     //1. Find MappedStatement corresponding to Configuration file in mybatis Configuration object Configuration according to Statement Id
      MappedStatement ms = configuration.getMappedStatement(statement);
      //2. Delegate the query task to the Executor of MyBatis
      List<E> result = executor.query(ms, wrapCollection(parameter), rowBounds, Executor.NO_RESULT_HANDLER);
      return result;
    } catch (Exception e) {
      throw ExceptionFactory.wrapException("Error querying database.  Cause: " + e, e);
    } finally {

Here we get the MappedStatement in the first step of the map through statementId. Here is a quote from the reference blog:

SqlSession gets the corresponding MappedStatement object in mybatis configuration object Configuration according to Statement ID, then invokes the mybatis executor to perform the specific operation.

Go on to query() and queryFromDatabase()

  public <E> List<E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, CacheKey key, BoundSql boundSql) throws SQLException {
    ErrorContext.instance().resource(ms.getResource()).activity("executing a query").object(ms.getId());
    if (closed) throw new ExecutorException("Executor was closed.");
    if (queryStack == 0 && ms.isFlushCacheRequired()) {
    List<E> list;
    try {
      list = resultHandler == null ? (List<E>) localCache.getObject(key) : null;
      if (list != null) {
        handleLocallyCachedOutputParameters(ms, key, parameter, boundSql);
      } else {
        list = queryFromDatabase(ms, parameter, rowBounds, resultHandler, key, boundSql);
    } finally {
    if (queryStack == 0) {
      for (DeferredLoad deferredLoad : deferredLoads) {
      deferredLoads.clear(); // issue #601
      if (configuration.getLocalCacheScope() == LocalCacheScope.STATEMENT) {
        clearLocalCache(); // issue #482
    return list;

private <E> List<E> queryFromDatabase(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, CacheKey key, BoundSql boundSql) throws SQLException {
    List<E> list;
    localCache.putObject(key, EXECUTION_PLACEHOLDER);
    try {
      list = doQuery(ms, parameter, rowBounds, resultHandler, boundSql);
    } finally {
    localCache.putObject(key, list);
    if (ms.getStatementType() == StatementType.CALLABLE) {
      localOutputParameterCache.putObject(key, parameter);
    return list;

In these two methods, a cache key will be created for the current query. If there is no value in the cache, it will be read directly from the database. After the query is executed, the list result will be put into the cache.

Then look at the method that doQuery() rewrites in the simpleexecutior class

public <E> List<E> doQuery(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) throws SQLException {
    Statement stmt = null;
    try {
      Configuration configuration = ms.getConfiguration();
      StatementHandler handler = configuration.newStatementHandler(wrapper, ms, parameter, rowBounds, resultHandler, boundSql);
      stmt = prepareStatement(handler, ms.getStatementLog());
      return handler.<E>query(stmt, resultHandler);
    } finally {

The Statement connection object is created here. Therefore, one of the functions of the Executor is to create a Statement. After the Statement is created, it is thrown to the StatementHandler to return the List query result.

Let's take a look at the implementation of prepareStatement() and query()

private Statement prepareStatement(StatementHandler handler, Log statementLog) throws SQLException {
    Statement stmt;
    Connection connection = getConnection(statementLog);
    stmt = handler.prepare(connection);
    return stmt;

public <E> List<E> query(Statement statement, ResultHandler resultHandler) throws SQLException {
    PreparedStatement ps = (PreparedStatement) statement;
    return resultSetHandler.<E> handleResultSets(ps);

prepareStatement() is the specific implementation method for creating a Statement. Call parameterize() to set parameters for the created Statement object, that is, assign the specified parameters to the places we set as placeholders. The parameterize() method goes further and calls the setParameters() method of ParameterHandler to assign specific values. Welcome everyone to pay attention to my public number.

query() here is the handleResultSets(Statement) method that calls the ResultSetHandler. The function is to convert the ResultSet result set object to a List type collection.

To summarize the above steps:

  1. According to the specific parameters passed in, dynamically generate the SQL statement to be executed, which is represented by the BoundSql object

  2. Create a cache Key for the current query

  3. No value in cache, read data directly from database

  4. Execute the query, return the List result, and then put the query result into the cache

  5. Create StatementHandler object to perform query operation according to existing parameters

  6. Pass the created Statement to the StatementHandler object and call the parameterize() method to assign a value

  7. Call StatementHandler.query() method to return List result set


All the above three steps can be summarized in one diagram


Welcome to exchange, like the article remember to like yo, thank you for your support!

Posted by neridaj on Fri, 08 Nov 2019 04:12:39 -0800