StatementHandler组件 及ParameterHandler组件

docs/Mybatis/核心处理层/4、StatementHandler.md

@@ -226,13 +226,259 @@ public abstract class BaseStatementHandler implements StatementHandler {
 }
 ```
 BaseStatementHandler主要实现了StatementHandler接口中的prepare()方法，BaseStatementHandler依赖两个重要的组件，ParameterHandler和ResultSetHandler。
-## ParameterHandler
+## ParameterHandler系列组件
+我们要执行的SQL语句中可能包含占位符"?"，而每个"?"都对应了BoundSql中parameterMappings集合中的一个元素，在该ParameterMapping对象中记录了对应的参数名称以及该参数的相关属性。ParameterHandler接口定义了一个非常重要的方法setParameters()，该方法主要负责调用PreparedStatement的set＊()系列方法，为SQL语句绑定实参。MyBatis只为ParameterHandler接口提供了唯一一个实现类DefaultParameterHandler。
+```java
+public interface ParameterHandler {
+
+  // 获取用户传入的实参对象
+  Object getParameterObject();
+
+  // 本方法主要负责调用PreparedStatement.set*()方法，为SQL语句绑定实参。
+  void setParameters(PreparedStatement ps)
+      throws SQLException;
+
+}
 
 
+public class DefaultParameterHandler implements ParameterHandler {
+
+  // 管理mybatis中所有的TypeHandler对象
+  private final TypeHandlerRegistry typeHandlerRegistry;
+
+  // 其中记录了SQL节点相应的配置信息
+  private final MappedStatement mappedStatement;
+  // 用户传入的实参对象
+  private final Object parameterObject;
+  // 其中记录了要执行的SQL语句，及参数信息
+  private final BoundSql boundSql;
+  private final Configuration configuration;
+
+  // 构造方法主要为持有的属性 进行初始化
+  public DefaultParameterHandler(MappedStatement mappedStatement, Object parameterObject, BoundSql boundSql) {
+    this.mappedStatement = mappedStatement;
+    this.configuration = mappedStatement.getConfiguration();
+    this.typeHandlerRegistry = mappedStatement.getConfiguration().getTypeHandlerRegistry();
+    this.parameterObject = parameterObject;
+    this.boundSql = boundSql;
+  }
+
+  @Override
+  public Object getParameterObject() {
+    return parameterObject;
+  }
+
+  // 为PreparedStatement对象要执行的SQL语句中的占位符 设置对应的参数值
+  @Override
+  public void setParameters(PreparedStatement ps) {
+    ErrorContext.instance().activity("setting parameters").object(mappedStatement.getParameterMap().getId());
+    // 获取参数列表
+    List<ParameterMapping> parameterMappings = boundSql.getParameterMappings();
+    if (parameterMappings != null) {
+      for (int i = 0; i < parameterMappings.size(); i++) {
+        ParameterMapping parameterMapping = parameterMappings.get(i);
+        // 过滤掉存储过程中的输出参数
+        if (parameterMapping.getMode() != ParameterMode.OUT) {
+          // 记录绑定的实参
+          Object value;
+          // 获取参数对应的属性名
+          String propertyName = parameterMapping.getProperty();
+          // 根据属性名 获取 实参值
+          if (boundSql.hasAdditionalParameter(propertyName)) { // issue #448 ask first for additional params
+            value = boundSql.getAdditionalParameter(propertyName);
+          // 整个实参为空
+          } else if (parameterObject == null) {
+            value = null;
+          // 如果实参可以直接通过TypeHandler转换成JdbcType
+          } else if (typeHandlerRegistry.hasTypeHandler(parameterObject.getClass())) {
+            value = parameterObject;
+          } else {
+            // 获取对象中相应的属性值 或查找Map对象中的值
+            MetaObject metaObject = configuration.newMetaObject(parameterObject);
+            value = metaObject.getValue(propertyName);
+          }
+          // 获取当前parameterMapping中的TypeHandler对象 及JdbcType对象
+          TypeHandler typeHandler = parameterMapping.getTypeHandler();
+          JdbcType jdbcType = parameterMapping.getJdbcType();
+          if (value == null && jdbcType == null) {
+            jdbcType = configuration.getJdbcTypeForNull();
+          }
+          try {
+            // TypeHandler的setParameter()方法会调用PreparedStatement对象的
+            // set*()系列方法，为SQL语句绑定相应的实参
+            typeHandler.setParameter(ps, i + 1, value, jdbcType);
+          } catch (TypeException | SQLException e) {
+            throw new TypeException("Could not set parameters for mapping: " + parameterMapping + ". Cause: " + e, e);
+          }
+        }
+      }
+    }
+  }
 
+}
+```
+为SQL语句绑定完实参之后，就可以调用Statement对象 相应的execute方法，将SQL语句交给数据库执行了。
 ## SimpleStatementHandler
+SimpleStatementHandler继承了BaseStatementHandler抽象类。其底层使用java.sql.Statement来完成数据库的相关操作，所以SQL语句中不存在占位符，所以SimpleStatementHandler的parameterize()方法是空实现。SimpleStatementHandler的instantiateStatement()方法直接通过JDBC Connection创建Statement对象。
+```java
+public class SimpleStatementHandler extends BaseStatementHandler {
 
+  // 构造方法主要用于属性的初始化
+  public SimpleStatementHandler(Executor executor, MappedStatement mappedStatement, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) {
+    super(executor, mappedStatement, parameter, rowBounds, resultHandler, boundSql);
+  }
 
+  // 直接通过Connection创建Statement对象
+  @Override
+  protected Statement instantiateStatement(Connection connection) throws SQLException {
+    if (mappedStatement.getResultSetType() == ResultSetType.DEFAULT) {
+      // 如果结果集类型是DEFAULT默认的，则直接用connection创建Statement对象
+      return connection.createStatement();
+    } else {
+      // 否则，设置结果集类型，设置结果集 只读
+      return connection.createStatement(mappedStatement.getResultSetType().getValue(), ResultSet.CONCUR_READ_ONLY);
+    }
+  }
+
+  // 上面创建的Statement对象会被本方法用于完成数据库查询操作
+  @Override
+  public <E> List<E> query(Statement statement, ResultHandler resultHandler) throws SQLException {
+    // 获取SQL语句
+    String sql = boundSql.getSql();
+    // 发送请求 执行SQL语句
+    statement.execute(sql);
+    // 从statement中获取结果集，并进行映射处理
+    return resultSetHandler.handleResultSets(statement);
+  }
 
+  // 下面的batch()及queryCursor()方法的实现与上面的query()方法非常类似
+  @Override
+  public void batch(Statement statement) throws SQLException {
+    String sql = boundSql.getSql();
+    statement.addBatch(sql);
+  }
+
+  @Override
+  public <E> Cursor<E> queryCursor(Statement statement) throws SQLException {
+    String sql = boundSql.getSql();
+    statement.execute(sql);
+    return resultSetHandler.handleCursorResultSets(statement);
+  }
+
+  // 本方法用于执行insert、delete、update等类型的SQL语句，并且会根据配置的
+  // KeyGenerator获取数据库生成的主键
+  @Override
+  public int update(Statement statement) throws SQLException {
+    // 获取SQL语句 及parameterObject
+    String sql = boundSql.getSql();
+    Object parameterObject = boundSql.getParameterObject();
+    // 获取配置的KeyGenerator 数据库主键生成器
+    KeyGenerator keyGenerator = mappedStatement.getKeyGenerator();
+    int rows;
+    if (keyGenerator instanceof Jdbc3KeyGenerator) {
+      // 执行SQL语句
+      statement.execute(sql, Statement.RETURN_GENERATED_KEYS);
+      // 获取更新的条数
+      rows = statement.getUpdateCount();
+      // 将数据库生成的主键添加到parameterObject中
+      keyGenerator.processAfter(executor, mappedStatement, statement, parameterObject);
+    } else if (keyGenerator instanceof SelectKeyGenerator) {
+      // 执行SQL语句
+      statement.execute(sql);
+      // 获取更新的条数
+      rows = statement.getUpdateCount();
+      // 执行<selectKey>节点中配置的SQL语句，将从数据库获取到的主键 添加到parameterObject中
+      keyGenerator.processAfter(executor, mappedStatement, statement, parameterObject);
+    } else {
+      statement.execute(sql);
+      rows = statement.getUpdateCount();
+    }
+    return rows;
+  }
+
+  @Override
+  public void parameterize(Statement statement) {
+    // N/A
+  }
+
+}
+```
 ## PreparedStatementHandler
+PreparedStatementHandler底层依赖于java.sql.PreparedStatement来完成数据库的相关操作。其中的parameterize()方法中，会调用前面介绍的ParameterHandler的setParameters()方法 完成 SQL语句的参数绑定。instantiateStatement()方法直接调用JDBC Connection的prepareStatement()方法创建PreparedStatement对象。
+```java
+public class PreparedStatementHandler extends BaseStatementHandler {
+
+  // 构造方法主要用于属性的初始化
+  public PreparedStatementHandler(Executor executor, MappedStatement mappedStatement, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) {
+    super(executor, mappedStatement, parameter, rowBounds, resultHandler, boundSql);
+  }
+
+  @Override
+  protected Statement instantiateStatement(Connection connection) throws SQLException {
+    // 获取SQL语句
+    String sql = boundSql.getSql();
+    // 根据mappedStatement持有的KeyGenerator的类型进行不同的处理
+    if (mappedStatement.getKeyGenerator() instanceof Jdbc3KeyGenerator) {
+      // 获取主键列
+      String[] keyColumnNames = mappedStatement.getKeyColumns();
+      if (keyColumnNames == null) {
+        // 返回数据库生成的主键
+        return connection.prepareStatement(sql, PreparedStatement.RETURN_GENERATED_KEYS);
+      } else {
+        // 在insert语句执行完后，会将keyColumnNames指定的列返回
+        return connection.prepareStatement(sql, keyColumnNames);
+      }
+    } else if (mappedStatement.getResultSetType() == ResultSetType.DEFAULT) {
+      // 如果结果集类型是DEFAULT默认的，则直接通过connection获取PreparedStatement对象
+      return connection.prepareStatement(sql);
+    } else {
+      // 否则，设置结果集类型，设置结果集为只读
+      return connection.prepareStatement(sql, mappedStatement.getResultSetType().getValue(), ResultSet.CONCUR_READ_ONLY);
+    }
+  }
+
+  // 因为是PrepareStatement对象，所以需要处理占位符"?"
+  // 使用了前面介绍的ParameterHandler组件完成
+  @Override
+  public void parameterize(Statement statement) throws SQLException {
+    parameterHandler.setParameters((PreparedStatement) statement);
+  }
+
+  // 下面的这些方法，除了多了一步 将Statement对象强转成PreparedStatement对象
+  // 其它的几乎与SimpleStatementHandler一样
+  @Override
+  public <E> List<E> query(Statement statement, ResultHandler resultHandler) throws SQLException {
+    PreparedStatement ps = (PreparedStatement) statement;
+    ps.execute();
+    return resultSetHandler.handleResultSets(ps);
+  }
+
+  @Override
+  public void batch(Statement statement) throws SQLException {
+    PreparedStatement ps = (PreparedStatement) statement;
+    ps.addBatch();
+  }
+
+  @Override
+  public <E> Cursor<E> queryCursor(Statement statement) throws SQLException {
+    PreparedStatement ps = (PreparedStatement) statement;
+    ps.execute();
+    return resultSetHandler.handleCursorResultSets(ps);
+  }
+
+  @Override
+  public int update(Statement statement) throws SQLException {
+    PreparedStatement ps = (PreparedStatement) statement;
+    ps.execute();
+    int rows = ps.getUpdateCount();
+    Object parameterObject = boundSql.getParameterObject();
+    KeyGenerator keyGenerator = mappedStatement.getKeyGenerator();
+    keyGenerator.processAfter(executor, mappedStatement, ps, parameterObject);
+    return rows;
+  }
+
+}
+```
+另外，StatementHandler接口还有一个CallableStatementHandler的实现。其底层依赖于java.sql.CallableStatement调用指定的存储过程，其parameterize()方法也会调用ParameterHandler的setParameters()方法完成SQL语句的参数绑定，并指定输出参数的索引位置和JDBC类型。其余方法与前面介绍的ResultSetHandler实现类似，唯一区别是会调用ResultSetHandler的handleOutputParameters()方法 处理输出参数。
 
+看到这里，我们可以发现StatementHandler组件依赖ParameterHandler组件 和 ResultSetHandler组件 完成了MyBatis的核心功能，它控制着参数绑定、SQL语句执行、结果集映射等一系列核心流程。