Mybatis Java API - SqlSession

正如前面提到的，​SqlSession​实例是MyBatis中最重要、最强大的类。它是您将找到执行语句、提交或回滚事务以及获取映射器实例的所有方法的地方。

`SqlSession` 类上有超过二十个方法，让我们将它们分成更易理解的组别。

Statement Execution Methods-语句执行方法

这些方法用于执行在SQL映射XML文件中定义的SELECT、INSERT、UPDATE和DELETE语句。它们相当直观，每个方法都接受语句的ID和参数对象作为输入，参数对象可以是基本类型（自动装箱或包装类）、JavaBean、POJO或Map。

<T> T selectOne(String statement, Object parameter)
<E> List<E> selectList(String statement, Object parameter)
<T> Cursor<T> selectCursor(String statement, Object parameter)
<K,V> Map<K,V> selectMap(String statement, Object parameter, String mapKey)
int insert(String statement, Object parameter)
int update(String statement, Object parameter)
int delete(String statement, Object parameter)

selectOne和selectList之间的区别仅在于selectOne必须返回一个对象或null（没有结果）。如果返回多个对象，将抛出异常。如果不知道期望的对象数量，可以使用selectList。如果想要检查对象是否存在，最好返回一个计数（0或1）。selectMap是一个特殊情况，它被设计用于根据结果对象中的某个属性将结果列表转换为Map。由于并不是所有语句都需要参数，因此这些方法提供了无需参数对象的重载版本。

insert、update和delete方法返回的值表示受影响的行数。

<T> T selectOne(String statement)
<E> List<E> selectList(String statement)
<T> Cursor<T> selectCursor(String statement)
<K,V> Map<K,V> selectMap(String statement, String mapKey)
int insert(String statement)
int update(String statement)
int delete(String statement)

游标（Cursor）提供与列表（List）相同的结果，但它使用迭代器（Iterator）来惰性获取数据。

try (Cursor<MyEntity> entities = session.selectCursor(statement, param)) {
   for (MyEntity entity : entities) {
      // process one entity
   }
}

最后，还有三个高级版本的select方法，允许您限制要返回的行范围，或者提供自定义的结果处理逻辑，通常用于处理非常大的数据集。

<E> List<E> selectList (String statement, Object parameter, RowBounds rowBounds)
<T> Cursor<T> selectCursor(String statement, Object parameter, RowBounds rowBounds)
<K,V> Map<K,V> selectMap(String statement, Object parameter, String mapKey, RowBounds rowbounds)
void select (String statement, Object parameter, ResultHandler<T> handler)
void select (String statement, Object parameter, RowBounds rowBounds, ResultHandler<T> handler)

RowBounds参数会让MyBatis跳过指定数量的记录，并且限制返回结果的数量。RowBounds类有一个构造函数，可以同时接收偏移量（offset）和限制数（limit），并且是不可变的。

int offset = 100;
int limit = 25;
RowBounds rowBounds = new RowBounds(offset, limit);

不同的数据库驱动在这方面可以实现不同级别的效率。为了获得最佳性能，使用SCROLL_SENSITIVE或SCROLL_INSENSITIVE的结果集类型（换句话说，不要使用FORWARD_ONLY）。

ResultHandler参数允许您自定义处理每一行的结果。您可以将结果添加到列表中，创建一个Map、Set，或者完全忽略每个结果，只保留计算的汇总数据。您可以根据需要对ResultHandler执行几乎任何操作，MyBatis内部也使用它来构建结果集列表。

从MyBatis 3.4.6开始，如果使用了CALLABLE语句，并且存储过程中有输出参数的话，传递给ResultHandler的接口将在每个REFCURSOR输出参数上使用。

该接口非常简单。

package org.apache.ibatis.session;
public interface ResultHandler<T> {
  void handleResult(ResultContext<? extends T> context);
}

ResultContext参数提供了对结果对象本身的访问，以及已创建的结果对象数量的计数，还有一个Boolean型的stop()方法，您可以使用该方法停止MyBatis加载更多的结果。

使用ResultHandler有两个限制需要注意：

• 使用ResultHandler调用的方法获取的数据不会被缓存。
• 当使用高级结果映射（advanced resultMaps）时，MyBatis可能需要多行数据来构建一个对象。如果使用ResultHandler，可能会得到一个对象，其中关联或集合尚未填充。

Batch update statement Flush Method-立即批量更新方法 

在任何时候，可以使用JDBC驱动类中的方法来执行批量更新语句。当ExecutorType为ExecutorType.BATCH时，可以使用该方法。

List<BatchResult> flushStatements()

 Transaction Control Methods-事务控制方法

有四种方法可以控制事务的范围。当然，如果选择使用自动提交或者使用外部事务管理器，则这些方法没有效果。然而，如果使用由Connection实例管理的JDBC事务管理器，那么以下四种方法将会非常有用：

void commit()
void commit(boolean force)
void rollback()
void rollback(boolean force)

默认情况下，除非通过调用带有affectData参数的insert、update、delete或select方法来检测到数据库已被更改，MyBatis实际上不会执行提交操作。如果在没有调用这些方法的情况下进行了更改，您可以将true传递给commit和rollback方法，以确保它们将被提交（请注意，仍然无法强制处于自动提交模式或使用外部事务管理器的会话）。

大多数情况下，您不需要调用rollback()，因为如果不调用commit，MyBatis会自动执行回滚操作。然而，如果您需要对可能进行多次提交和回滚的会话进行更精细的控制，您可以使用rollback选项来实现。

注意：MyBatis-Spring和MyBatis-Guice提供了声明式的事务处理。因此，如果您正在使用MyBatis与Spring或Guice，请参考它们的具体手册。 

Ensuring that SqlSession is Closed-确保SqlSession被关闭

void close()

 最重要的一点是确保关闭您打开的任何会话（Session）。为了确保这一点，最好使用以下工作单元模式：

try (SqlSession session = sqlSessionFactory.openSession()) {
    // following 3 lines are pseudocode for "doing some work"
    session.insert(...);
    session.update(...);
    session.delete(...);
    session.commit();
}

 注意：就像SqlSessionFactory一样，您可以通过调用getConfiguration()方法来获取SqlSession正在使用的Configuration实例。

Configuration getConfiguration()