Java API

既然你已經(jīng)知道如何配置 MyBatis 和創(chuàng)建映射文件,你就已經(jīng)準(zhǔn)備好來(lái)提升技能了。 MyBatis 的 Java API 就是你收獲你所做的努力的地方。正如你即將看到的,和 JDBC 相比, MyBatis 很大程度簡(jiǎn)化了你的代碼而且保持簡(jiǎn)潔,很容易理解和維護(hù)。MyBatis 3 已經(jīng)引入 了很多重要的改進(jìn)來(lái)使得 SQL 映射更加優(yōu)秀。

應(yīng)用目錄結(jié)構(gòu)

在我們深入 Java API 之前,理解關(guān)于目錄結(jié)構(gòu)的最佳實(shí)踐是很重要的。MyBatis 非常靈 活, 你可以用你自己的文件來(lái)做幾乎所有的事情。 但是對(duì)于任一框架, 都有一些最佳的方式。

讓我們看一下典型應(yīng)用的目錄結(jié)構(gòu):

/my_application
  /bin
  /devlib
  /lib                <-- MyBatis *.jar文件在這里。
  /src
    /org/myapp/
      /action
      /data           <-- MyBatis配置文件在這里, 包括映射器類, XML配置, XML映射文件。
        /mybatis-config.xml
        /BlogMapper.java
        /BlogMapper.xml
      /model
      /service
      /view
    /properties       <-- 在你XML中配置的屬性 文件在這里。
  /test
    /org/myapp/
      /action
      /data
      /model
      /service
      /view
    /properties
  /web
    /WEB-INF
      /web.xml

Remember, these are preferences, not requirements, but others will thank you for using a common directory structure.

這部分內(nèi)容剩余的示例將假設(shè)你使用了這種目錄結(jié)構(gòu)。

SqlSessions

使用 MyBatis 的主要 Java 接口就是 SqlSession。盡管你可以使用這個(gè)接口執(zhí)行命令,獲 取映射器和管理事務(wù)。我們會(huì)討論 SqlSession 本身更多,但是首先我們還是要了解如果獲取 一個(gè) SqlSession 實(shí)例。SqlSessions 是由 SqlSessionFactory 實(shí)例創(chuàng)建的。SqlSessionFactory 對(duì) 象 包 含 創(chuàng) 建 SqlSession 實(shí) 例 的 所 有 方 法 。 而 SqlSessionFactory 本 身 是 由 SqlSessionFactoryBuilder 創(chuàng)建的,它可以從 XML 配置,注解或手動(dòng)配置 Java 來(lái)創(chuàng)建 SqlSessionFactory。

NOTE When using MyBatis with a dependency injection framework like Spring or Guice, SqlSessions are created and injected by the DI framework so you don't need to use the SqlSessionFactoryBuilder or SqlSessionFactory and can go directly to the SqlSession section. Please refer to the MyBatis-Spring or MyBatis-Guice manuals for further info.

SqlSessionFactoryBuilder

SqlSessionFactoryBuilder 有五個(gè) build()方法,每一種都允許你從不同的資源中創(chuàng)建一個(gè) SqlSession 實(shí)例。

    SqlSessionFactory build(InputStream inputStream)
    SqlSessionFactory build(InputStream inputStream, String environment)
    SqlSessionFactory build(InputStream inputStream, Properties properties)
    SqlSessionFactory build(InputStream inputStream, String env, Properties props)
    SqlSessionFactory build(Configuration config)

第一種方法是最常用的,它使用了一個(gè)參照了 XML 文檔或上面討論過(guò)的更特定的 mybatis-config.xml 文件的 Reader 實(shí)例。 可選的參數(shù)是 environment 和 properties。 Environment 決定加載哪種環(huán)境,包括數(shù)據(jù)源和事務(wù)管理器。比如:

<environments default="development">
  <environment id="development">
    <transactionManager type="JDBC">
        ...
    <dataSource type="POOLED">
        ...
  </environment>
  <environment id="production">
    <transactionManager type="MANAGED">
        ...
    <dataSource type="JNDI">
        ...
  </environment>
</environments>

如果你調(diào)用了 一個(gè)使用 environment 參數(shù) 方 式的 build 方法, 那么 MyBatis 將會(huì)使用 configuration 對(duì)象來(lái)配置這個(gè) environment。 當(dāng)然, 如果你指定了一個(gè)不合法的 environment, 你會(huì)得到錯(cuò)誤提示。 如果你調(diào)用了其中之一沒(méi)有 environment 參數(shù)的 build 方法, 那么就使用 默認(rèn)的 environment(在上面的示例中就會(huì)指定為 default="development")。

如果你調(diào)用了使用 properties 實(shí)例的方法,那么 MyBatis 就會(huì)加載那些 properties(屬性 配置文件) ,并你在你配置中可使用它們。那些屬性可以用${propName}語(yǔ)法形式多次用在 配置文件中。

回想一下,屬性可以從 mybatis-config.xml 中被引用,或者直接指定它。因此理解優(yōu)先 級(jí)是很重要的。我們?cè)谖臋n前面已經(jīng)提及它了,但是這里要再次重申:

如果一個(gè)屬性存在于這些位置,那么 MyBatis 將會(huì)按找下面的順序來(lái)加載它們:

• 在 properties 元素體中指定的屬性首先被讀取,
• 從 properties 元素的類路徑 resource 或 url 指定的屬性第二個(gè)被讀取, 可以覆蓋已經(jīng) 指定的重復(fù)屬性,
• 作為方法參 數(shù)傳遞 的屬性最 后被讀 取,可以 覆蓋已 經(jīng)從 properties 元 素體和 resource/url 屬性中加載的任意重復(fù)屬性。

因此,最高優(yōu)先級(jí)的屬性是通過(guò)方法參數(shù)傳遞的,之后是 resource/url 屬性指定的,最 后是在 properties 元素體中指定的屬性。

總結(jié)一下,前四個(gè)方法很大程度上是相同的,但是由于可以覆蓋,就允許你可選地指定 environment 和/或 properties。 這里給出一個(gè)從 mybatis-config.xml 文件創(chuàng)建 SqlSessionFactory 的示例:

    String **resource** = "org/mybatis/builder/mybatis-config.xml";
    InputStream **inputStream** = Resources.getResourceAsStream(resource);
    SqlSessionFactoryBuilder **builder** = new SqlSessionFactoryBuilder();
    SqlSessionFactory **factory** = builder.build(inputStream);

注意這里我們使用了 Resources 工具類,這個(gè)類在 org.mybatis.io 包中。Resources 類正 如其名,會(huì)幫助你從類路徑下,文件系統(tǒng)或一個(gè) web URL 加載資源文件?？匆幌逻@個(gè)類的 源代碼或者通過(guò)你的 IDE 來(lái)查看,就會(huì)看到一整套有用的方法。這里給出一個(gè)簡(jiǎn)表:

    URL getResourceURL(String resource)
    URL getResourceURL(ClassLoader loader, String resource)
    InputStream getResourceAsStream(String resource)
    InputStream getResourceAsStream(ClassLoader loader, String resource)
    Properties getResourceAsProperties(String resource)
    Properties getResourceAsProperties(ClassLoader loader, String resource)
    Reader getResourceAsReader(String resource)
    Reader getResourceAsReader(ClassLoader loader, String resource)
    File getResourceAsFile(String resource)
    File getResourceAsFile(ClassLoader loader, String resource)
    InputStream getUrlAsStream(String urlString)
    Reader getUrlAsReader(String urlString)
    Properties getUrlAsProperties(String urlString)
    Class classForName(String className)

最后一個(gè) build 方法使用了一個(gè) Configuration 實(shí)例。configuration 類包含你可能需要了 解 SqlSessionFactory 實(shí)例的所有內(nèi)容。Configuration 類對(duì)于配置的自查很有用,包含查找和 操作 SQL 映射(不推薦使用,因?yàn)閼?yīng)用正接收請(qǐng)求) 。configuration 類有所有配置的開(kāi)關(guān), 這些你已經(jīng)了解了,只在 Java API 中露出來(lái)。這里有一個(gè)簡(jiǎn)單的示例,如何手動(dòng)配置 configuration 實(shí)例,然后將它傳遞給 build()方法來(lái)創(chuàng)建 SqlSessionFactory。

    DataSource dataSource = BaseDataTest.createBlogDataSource();
    TransactionFactory transactionFactory = new JdbcTransactionFactory();

    Environment environment = new Environment("development", transactionFactory, dataSource);

    Configuration configuration = new Configuration(environment);
    configuration.setLazyLoadingEnabled(true);
    configuration.setEnhancementEnabled(true);
    configuration.getTypeAliasRegistry().registerAlias(Blog.class);
    configuration.getTypeAliasRegistry().registerAlias(Post.class);
    configuration.getTypeAliasRegistry().registerAlias(Author.class);
    configuration.addMapper(BoundBlogMapper.class);
    configuration.addMapper(BoundAuthorMapper.class);

    SqlSessionFactoryBuilder builder = new SqlSessionFactoryBuilder();
    SqlSessionFactory factory = builder.build(configuration);

現(xiàn)在你有一個(gè) SqlSessionFactory,可以用來(lái)創(chuàng)建 SqlSession 實(shí)例。

SqlSessionFactory

SqlSessionFactory 有六個(gè)方法可以用來(lái)創(chuàng)建 SqlSession 實(shí)例。通常來(lái)說(shuō),如何決定是你 選擇下面這些方法時(shí):

• Transaction (事務(wù)): 你想為 session 使用事務(wù)或者使用自動(dòng)提交(通常意味著很多 數(shù)據(jù)庫(kù)和/或 JDBC 驅(qū)動(dòng)沒(méi)有事務(wù))?
• Connection (連接): 你想 MyBatis 獲得來(lái)自配置的數(shù)據(jù)源的連接還是提供你自己
• Execution (執(zhí)行): 你想 MyBatis 復(fù)用預(yù)處理語(yǔ)句和/或批量更新語(yǔ)句(包括插入和 刪除)?

重載的 openSession()方法簽名設(shè)置允許你選擇這些可選中的任何一個(gè)組合。

    SqlSession openSession()
    SqlSession openSession(boolean autoCommit)
    SqlSession openSession(Connection connection)
    SqlSession openSession(TransactionIsolationLevel level)
    SqlSession openSession(ExecutorType execType,TransactionIsolationLevel level)
    SqlSession openSession(ExecutorType execType)
    SqlSession openSession(ExecutorType execType, boolean autoCommit)
    SqlSession openSession(ExecutorType execType, Connection connection)
    Configuration getConfiguration();

默認(rèn)的 openSession()方法沒(méi)有參數(shù),它會(huì)創(chuàng)建有如下特性的 SqlSession:

• 會(huì)開(kāi)啟一個(gè)事務(wù)(也就是不自動(dòng)提交)
• 連接對(duì)象會(huì)從由活動(dòng)環(huán)境配置的數(shù)據(jù)源實(shí)例中得到。
• 事務(wù)隔離級(jí)別將會(huì)使用驅(qū)動(dòng)或數(shù)據(jù)源的默認(rèn)設(shè)置。
• 預(yù)處理語(yǔ)句不會(huì)被復(fù)用,也不會(huì)批量處理更新。

這些方法大都可以自我解釋的。 開(kāi)啟自動(dòng)提交, "true" 傳遞 給可選的 autoCommit 參數(shù)。 提供自定義的連接,傳遞一個(gè) Connection 實(shí)例給 connection 參數(shù)。注意沒(méi)有覆蓋同時(shí)設(shè)置 Connection 和 autoCommit 兩者的方法,因?yàn)?MyBatis 會(huì)使用當(dāng)前 connection 對(duì)象提供的設(shè) 置。 MyBatis 為事務(wù)隔離級(jí)別調(diào)用使用一個(gè) Java 枚舉包裝器, 稱為 TransactionIsolationLevel, 否則它們按預(yù)期的方式來(lái)工作,并有 JDBC 支持的 5 級(jí) ( NONE,READ_UNCOMMITTED,READ_COMMITTED,REPEA TABLE_READ,SERIALIZA BLE)

還有一個(gè)可能對(duì)你來(lái)說(shuō)是新見(jiàn)到的參數(shù),就是 ExecutorType。這個(gè)枚舉類型定義了 3 個(gè) 值:

• ExecutorType.SIMPLE: 這個(gè)執(zhí)行器類型不做特殊的事情。它為每個(gè)語(yǔ)句的執(zhí)行創(chuàng)建一個(gè)新的預(yù)處理語(yǔ)句。
• ExecutorType.REUSE: 這個(gè)執(zhí)行器類型會(huì)復(fù)用預(yù)處理語(yǔ)句。
• ExecutorType.BATCH: 這個(gè)執(zhí)行器會(huì)批量執(zhí)行所有更新語(yǔ)句,如果 SELECT 在它們中間執(zhí)行還會(huì)標(biāo)定它們是 必須的,來(lái)保證一個(gè)簡(jiǎn)單并易于理解的行為。

注意 在 SqlSessionFactory 中還有一個(gè)方法我們沒(méi)有提及,就是 getConfiguration()。這 個(gè)方法會(huì)返回一個(gè) Configuration 實(shí)例,在運(yùn)行時(shí)你可以使用它來(lái)自檢 MyBatis 的配置。

注意 如果你已經(jīng)使用之前版本 MyBatis,你要回憶那些 session,transaction 和 batch 都是分離的。現(xiàn)在和以往不同了,這些都包含在 session 的范圍內(nèi)了。你需要處理分開(kāi)處理 事務(wù)或批量操作來(lái)得到它們的效果。

SqlSession

如上面所提到的,SqlSession 實(shí)例在 MyBatis 中是非常強(qiáng)大的一個(gè)類。在這里你會(huì)發(fā)現(xiàn) 所有執(zhí)行語(yǔ)句的方法,提交或回滾事務(wù),還有獲取映射器實(shí)例。

在 SqlSession 類中有超過(guò) 20 個(gè)方法,所以將它們分開(kāi)成易于理解的組合。

語(yǔ)句執(zhí)行方法

這些方法被用來(lái)執(zhí)行定義在 SQL 映射的 XML 文件中的 SELECT,INSERT,UPDA E T 和 DELETE 語(yǔ)句。它們都會(huì)自行解釋,每一句都使用語(yǔ)句的 ID 屬性和參數(shù)對(duì)象,參數(shù)可以 是原生類型(自動(dòng)裝箱或包裝類) ,JavaBean,POJO 或 Map。

     T selectOne(String statement, Object parameter)
     List selectList(String statement, Object parameter)
     Map 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 必須返回一個(gè)對(duì)象。 如果多余一個(gè), 或者 沒(méi)有返回 (或返回了 null) 那么就會(huì)拋出異常。 , 如果你不知道需要多少對(duì)象, 使用 selectList。

如果你想檢查一個(gè)對(duì)象是否存在,那么最好返回統(tǒng)計(jì)數(shù)(0 或 1) 。因?yàn)椴⒉皇撬姓Z(yǔ)句都需 要參數(shù),這些方法都是有不同重載版本的,它們可以不需要參數(shù)對(duì)象。

     T selectOne(String statement)
     List selectList(String statement)
     Map selectMap(String statement, String mapKey)
    int insert(String statement)
    int update(String statement)
    int delete(String statement)

最后,還有查詢方法的三個(gè)高級(jí)版本,它們?cè)试S你限制返回行數(shù)的范圍,或者提供自定 義結(jié)果控制邏輯,這通常用于大量的數(shù)據(jù)集合。

<E> List<E> selectList (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 參數(shù)會(huì)告訴 MyBatis 略過(guò)指定數(shù)量的記錄,還有限制返回結(jié)果的數(shù)量。 RowBounds 類有一個(gè)構(gòu)造方法來(lái)接收 offset 和 limit,否則是不可改變的。

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

不同的驅(qū)動(dòng)會(huì)實(shí)現(xiàn)這方面的不同級(jí)別的效率。對(duì)于最佳的表現(xiàn),使用結(jié)果集類型的 SCROLL_SENSITIVE 或 SCROLL_INSENSITIVE(或句話說(shuō):不是 FORWARD_ONLY)。

ResultHandler 參數(shù)允許你按你喜歡的方式處理每一行。你可以將它添加到 List 中,創(chuàng) 建 Map, 或拋出每個(gè)結(jié)果而不是只保留總計(jì)。 Set 你可以使用 ResultHandler 做很多漂亮的事, 那就是 MyBatis 內(nèi)部創(chuàng)建結(jié)果集列表。

它的接口很簡(jiǎn)單。

    package org.apache.ibatis.session;
    public interface ResultHandler {
      void handleResult(ResultContext context);
    }

ResultContext 參數(shù)給你訪問(wèn)結(jié)果對(duì)象本身的方法, 大量結(jié)果對(duì)象被創(chuàng)建, 你可以使用布 爾返回值的 stop()方法來(lái)停止 MyBatis 加載更多的結(jié)果。

事務(wù)控制方法

控制事務(wù)范圍有四個(gè)方法。 當(dāng)然, 如果你已經(jīng)選擇了自動(dòng)提交或你正在使用外部事務(wù)管 理器,這就沒(méi)有任何效果了。然而,如果你正在使用 JDBC 事務(wù)管理員,由 Connection 實(shí) 例來(lái)控制,那么這四個(gè)方法就會(huì)派上用場(chǎng):

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

默認(rèn)情況下 MyBatis 不會(huì)自動(dòng)提交事務(wù), 除非它偵測(cè)到有插入, 更新或刪除操作改變了 數(shù)據(jù)庫(kù)。如果你已經(jīng)做出了一些改變而沒(méi)有使用這些方法,那么你可以傳遞 true 到 commit 和 rollback 方法來(lái)保證它會(huì)被提交(注意,你不能在自動(dòng)提交模式下強(qiáng)制 session,或者使用 了外部事務(wù)管理器時(shí)) 。很多時(shí)候你不用調(diào)用 rollback(),因?yàn)槿绻銢](méi)有調(diào)用 commit 時(shí) MyBatis 會(huì)替你完成。然而,如果你需要更多對(duì)多提交和回滾都可能的 session 的細(xì)粒度控 制,你可以使用回滾選擇來(lái)使它成為可能。

NOTE MyBatis-Spring and MyBatis-Guice provide declarative transaction handling. So if you are using MyBatis with Spring or Guice please refer to their specific manuals.

清理 Session 級(jí)的緩存

void clearCache()

SqlSession 實(shí)例有一個(gè)本地緩存在執(zhí)行 update,commit,rollback 和 close 時(shí)被清理。要 明確地關(guān)閉它(獲取打算做更多的工作) ,你可以調(diào)用 clearCache()。

確保 SqlSession 被關(guān)閉

void close()

你必須保證的最重要的事情是你要關(guān)閉所打開(kāi)的任何 session。保證做到這點(diǎn)的最佳方 式是下面的工作模式:

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

Or, If you are using jdk 1.7+ and MyBatis 3.2+, you can use the try-with-resources statement:

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

注意 就像 SqlSessionFactory,你可以通過(guò)調(diào)用 getConfiguration()方法獲得 SqlSession 使用的 Configuration 實(shí)例

    Configuration getConfiguration()

使用映射器

     T getMapper(Class type)

上述的各個(gè) insert,update,delete 和 select 方法都很強(qiáng)大,但也有些繁瑣,沒(méi)有類型安 全,對(duì)于你的 IDE 也沒(méi)有幫助,還有可能的單元測(cè)試。在上面的入門章節(jié)中我們已經(jīng)看到 了一個(gè)使用映射器的示例。

因此, 一個(gè)更通用的方式來(lái)執(zhí)行映射語(yǔ)句是使用映射器類。 一個(gè)映射器類就是一個(gè)簡(jiǎn)單 的接口,其中的方法定義匹配于 SqlSession 方法。下面的示例展示了一些方法簽名和它們是 如何映射到 SqlSession 的。

    public interface AuthorMapper {
      // (Author) selectOne("selectAuthor",5);
      Author selectAuthor(int id);
      // (List) selectList("selectAuthors")
      List selectAuthors();
      // (Map) selectMap("selectAuthors", "id")
      @MapKey("id")
      Map selectAuthors();
      // insert("insertAuthor", author)
      int insertAuthor(Author author);
      // updateAuthor("updateAuthor", author)
      int updateAuthor(Author author);
      // delete("deleteAuthor",5)
      int deleteAuthor(int id);
    }

總之, 每個(gè)映射器方法簽名應(yīng)該匹配相關(guān)聯(lián)的 SqlSession 方法, 而沒(méi)有字符串參數(shù) ID。 相反,方法名必須匹配映射語(yǔ)句的 ID。

此外,返回類型必須匹配期望的結(jié)果類型。所有常用的類型都是支持的,包括:原生類 型,Map,POJO 和 JavaBean。

映射器接口不需要去實(shí)現(xiàn)任何接口或擴(kuò)展任何類。 只要方法前面可以被用來(lái)唯一標(biāo)識(shí)對(duì) 應(yīng)的映射語(yǔ)句就可以了。

映射器接口可以擴(kuò)展其他接口。當(dāng)使用 XML 來(lái)構(gòu)建映射器接口時(shí)要保證在合適的命名 空間中有語(yǔ)句。 而且, 唯一的限制就是你不能在兩個(gè)繼承關(guān)系的接口中有相同的方法簽名 (這 也是不好的想法)。

你可以傳遞多個(gè)參數(shù)給一個(gè)映射器方法。 如果你這樣做了, 默認(rèn)情況下它們將會(huì)以它們 在參數(shù)列表中的位置來(lái)命名,比如:#{param1},#{param2}等。如果你想改變參數(shù)的名稱(只在多參數(shù) 情況下) ,那么你可以在參數(shù)上使用@Param("paramName")注解。

你也可以給方法傳遞一個(gè) RowBounds 實(shí)例來(lái)限制查詢結(jié)果。

映射器注解

因?yàn)樽畛踉O(shè)計(jì)時(shí),MyBatis 是一個(gè) XML 驅(qū)動(dòng)的框架。配置信息是基于 XML 的,而且 映射語(yǔ)句也是定義在 XML 中的。而到了 MyBatis 3,有新的可用的選擇了。MyBatis 3 構(gòu)建 在基于全面而且強(qiáng)大的 Java 配置 API 之上。這個(gè)配置 API 是基于 XML 的 MyBatis 配置的 基礎(chǔ),也是新的基于注解配置的基礎(chǔ)。注解提供了一種簡(jiǎn)單的方式來(lái)實(shí)現(xiàn)簡(jiǎn)單映射語(yǔ)句,而 不會(huì)引入大量的開(kāi)銷。

注意 不幸的是,Java 注解限制了它們的表現(xiàn)和靈活。盡管很多時(shí)間都花調(diào)查,設(shè)計(jì)和 實(shí)驗(yàn)上,最強(qiáng)大的 MyBatis 映射不能用注解來(lái)構(gòu)建,那并不可笑。C#屬性(做示例)就沒(méi) 有這些限制,因此 MyBatis.NET 將會(huì)比 XML 有更豐富的選擇。也就是說(shuō),基于 Java 注解 的配置離不開(kāi)它的特性。

注解有下面這些:

映射申明樣例

這個(gè)例子展示了如何使用 @SelectKey 注解來(lái)在插入前讀取數(shù)據(jù)庫(kù)序列的值：

@Insert("insert into table3 (id, name) values(#{nameId}, #{name})")
@SelectKey(statement="call next value for TestSequence", keyProperty="nameId", before=true, resultType=int.class)
int insertTable3(Name name);

這個(gè)例子展示了如何使用 @SelectKey 注解來(lái)在插入后讀取數(shù)據(jù)庫(kù)識(shí)別列的值：

@Insert("insert into table2 (name) values(#{name})")
@SelectKey(statement="call identity()", keyProperty="nameId", before=false, resultType=int.class)
int insertTable2(Name name);