配置環境(environments)
MyBatis 可以配置成適應多種環境,這種機制有助於將 SQL 映射應用於多種數據庫之中, 現實情況下有多種理由需要這麼做。例如,開發、測試和生產環境需要有不同的配置;或者共享相同 Schema 的多個生產數據庫, 想使用相同的 SQL 映射。許多類似的用例。
不過要記住:儘管可以配置多個環境,每個 SqlSessionFactory 實例只能選擇其一。
所以,如果你想連接兩個數據庫,就需要創建兩個 SqlSessionFactory 實例,每個數據庫對應一個。而如果是三個數據庫,就需要三個實例,依此類推,記起來很簡單:
- 每個數據庫對應一個 SqlSessionFactory 實例
爲了指定創建哪種環境,只要將它作爲可選的參數傳遞給 SqlSessionFactoryBuilder 即可。可以接受環境配置的兩個方法簽名是:
SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader, environment); SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader, environment,properties);
如果忽略了環境參數,那麼默認環境將會被加載,如下所示:
SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader); SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader,properties);
環境元素定義瞭如何配置環境。
<environments default="development"> <environment id="development"> <transactionManager type="JDBC"> <property name="..." value="..."/> </transactionManager> <dataSource type="POOLED"> <property name="driver" value="${driver}"/> <property name="url" value="${url}"/> <property name="username" value="${username}"/> <property name="password" value="${password}"/> </dataSource> </environment> </environments>
注意這裏的關鍵點:
- 默認的環境 ID(比如:default=”development”)。
- 每個 environment 元素定義的環境 ID(比如:id=”development”)。
- 事務管理器的配置(比如:type=”JDBC”)。
- 數據源的配置(比如:type=”POOLED”)。
默認的環境和環境 ID 是一目瞭然的。隨你怎麼命名,只要保證默認環境要匹配其中一個環境ID。
事務管理器(transactionManager)
在 MyBatis 中有兩種類型的事務管理器(也就是 type=”[JDBC|MANAGED]”):
- JDBC – 這個配置就是直接使用了 JDBC 的提交和回滾設置,它依賴於從數據源得到的連接來管理事務作用域。
- MANAGED – 這個配置幾乎沒做什麼。它從來不提交或回滾一個連接,而是讓容器來管理事務的整個生命週期(比如 JEE 應用服務器的上下文)。 默認情況下它會關閉連接,然而一些容器並不希望這樣,因此需要將 closeConnection 屬性設置爲 false 來阻止它默認的關閉行爲。例如:
<transactionManager type="MANAGED"> <property name="closeConnection" value="false"/> </transactionManager>
NOTE如果你正在使用 Spring + MyBatis,則沒有必要配置事務管理器, 因爲 Spring 模塊會使用自帶的管理器來覆蓋前面的配置。
這兩種事務管理器類型都不需要任何屬性。它們不過是類型別名,換句話說,你可以使用 TransactionFactory 接口的實現類的完全限定名或類型別名代替它們。
public interface TransactionFactory { void setProperties(Properties props); Transaction newTransaction(Connection conn); Transaction newTransaction(DataSource dataSource, TransactionIsolationLevel level, boolean autoCommit); }
任何在 XML 中配置的屬性在實例化之後將會被傳遞給 setProperties() 方法。你也需要創建一個 Transaction 接口的實現類,這個接口也很簡單:
public interface Transaction { Connection getConnection() throws SQLException; void commit() throws SQLException; void rollback() throws SQLException; void close() throws SQLException; Integer getTimeout() throws SQLException; }
使用這兩個接口,你可以完全自定義 MyBatis 對事務的處理。
數據源(dataSource)
dataSource 元素使用標準的 JDBC 數據源接口來配置 JDBC 連接對象的資源。
- 許多 MyBatis 的應用程序將會按示例中的例子來配置數據源。然而它並不是必須的。要知道爲了方便使用延遲加載,數據源纔是必須的。
有三種內建的數據源類型(也就是 type=”[UNPOOLED|POOLED|JNDI]”):
UNPOOLED– 這個數據源的實現只是每次被請求時打開和關閉連接。雖然一點慢,它對在及時可用連接方面沒有性能要求的簡單應用程序是一個很好的選擇。 不同的數據庫在這方面表現也是不一樣的,所以對某些數據庫來說使用連接池並不重要,這個配置也是理想的。UNPOOLED 類型的數據源僅僅需要配置以下 5 種屬性:
- driver – 這是 JDBC 驅動的 Java 類的完全限定名(並不是JDBC驅動中可能包含的數據源類)。
- url – 這是數據庫的 JDBC URL 地址。
- username – 登錄數據庫的用戶名。
- password – 登錄數據庫的密碼。
- defaultTransactionIsolationLevel – 默認的連接事務隔離級別。
作爲可選項,你也可以傳遞屬性給數據庫驅動。要這樣做,屬性的前綴爲“driver.”,例如:
- driver.encoding=UTF8
這將通過DriverManager.getConnection(url,driverProperties)方法傳遞值爲 UTF8 的 encoding 屬性給數據庫驅動。
POOLED– 這種數據源的實現利用“池”的概念將 JDBC 連接對象組織起來,避免了創建新的連接實例時所必需的初始化和認證時間。 這是一種使得併發 Web 應用快速響應請求的流行處理方式。
除了上述提到 UNPOOLED 下的屬性外,會有更多屬性用來配置 POOLED 的數據源:
- poolMaximumActiveConnections – 在任意時間可以存在的活動(也就是正在使用)連接數量,默認值:10
- poolMaximumIdleConnections – 任意時間可能存在的空閒連接數。
- poolMaximumCheckoutTime – 在被強制返回之前,池中連接被檢出(checked out)時間,默認值:20000 毫秒(即 20 秒)
- poolTimeToWait – 這是一個底層設置,如果獲取連接花費的相當長的時間,它會給連接池打印狀態日誌並重新嘗試獲取一個連接(避免在誤配置的情況下一直安靜的失敗),默認值:20000 毫秒(即 20 秒)。
- poolMaximumLocalBadConnectionTolerance – 這是一個關於壞連接容忍度的底層設置, 作用於每一個嘗試從緩存池獲取連接的線程. 如果這個線程獲取到的是一個壞的連接,那麼這個數據源允許這 個線程嘗試重新獲取一個新的連接,但是這個重新嘗試的次數不應該超過 poolMaximumIdleConnections 與 poolMaximumLocalBadConnectionTolerance 之和。 默認值:3 (Since: 3.4.5)
- poolPingQuery – 發送到數據庫的偵測查詢,用來檢驗連接是否處在正常工作秩序中並準備接受請求。默認是“NO PING QUERY SET”,這會導致多數數據庫驅動失敗時帶有一個恰當的錯誤消息。
- poolPingEnabled – 是否啓用偵測查詢。若開啓,也必須使用一個可執行的 SQL 語句設置 poolPingQuery 屬性(最好是一個非常快的 SQL),默認值:false。
- poolPingConnectionsNotUsedFor – 配置 poolPingQuery 的使用頻度。這可以被設置成匹配具體的數據庫連接超時時間,來避免不必要的偵測,默認值:0(即所有連接每一時刻都被偵測 — 當然僅當 poolPingEnabled 爲 true 時適用)。
JNDI– 這個數據源的實現是爲了能在如 EJB 或應用服務器這類容器中使用,容器可以集中或在外部配置數據源,然後放置一個 JNDI 上下文的引用。這種數據源配置只需要兩個屬性:
- initial_context – 這個屬性用來在 InitialContext 中尋找上下文(即,initialContext.lookup(initial_context))。這是個可選屬性,如果忽略,那麼 data_source 屬性將會直接從 InitialContext 中尋找。
- data_source – 這是引用數據源實例位置的上下文的路徑。提供了 initial_context 配置時會在其返回的上下文中進行查找,沒有提供時則直接在 InitialContext 中查找。
和其他數據源配置類似,可以通過添加前綴“env.”直接把屬性傳遞給初始上下文。比如:
- env.encoding=UTF8
這就會在初始上下文(InitialContext)實例化時往它的構造方法傳遞值爲 UTF8 的 encoding 屬性。
通過需要實現接口 org.apache.ibatis.datasource.DataSourceFactory , 也可使用任何第三方數據源,:
public interface DataSourceFactory { void setProperties(Properties props); DataSource getDataSource(); }
org.apache.ibatis.datasource.unpooled.UnpooledDataSourceFactory 可被用作父類來構建新的數據源適配器,比如下面這段插入 C3P0 數據源所必需的代碼:
import org.apache.ibatis.datasource.unpooled.UnpooledDataSourceFactory; import com.mchange.v2.c3p0.ComboPooledDataSource; public class C3P0DataSourceFactory extends UnpooledDataSourceFactory { public C3P0DataSourceFactory() { this.dataSource = new ComboPooledDataSource(); } }
爲了令其工作,爲每個需要 MyBatis 調用的 setter 方法中增加一個屬性。下面是一個可以連接至 PostgreSQL 數據庫的例子:
<dataSource type="org.myproject.C3P0DataSourceFactory"> <property name="driver" value="org.postgresql.Driver"/> <property name="url" value="jdbc:postgresql:mydb"/> <property name="username" value="postgres"/> <property name="password" value="root"/> </dataSource>
databaseIdProvider
MyBatis 可以根據不同的數據庫廠商執行不同的語句,這種多廠商的支持是基於映射語句中的 databaseId 屬性。 MyBatis 會加載不帶 databaseId 屬性和帶有匹配當前數據庫 databaseId 屬性的所有語句。 如果同時找到帶有 databaseId 和不帶 databaseId 的相同語句,則後者會被捨棄。 爲支持多廠商特性只要像下面這樣在 mybatis-config.xml 文件中加入 databaseIdProvider 即可:
<databaseIdProvider type="DB_VENDOR" />
這裏的 DB_VENDOR 會通過 DatabaseMetaData#getDatabaseProductName() 返回的字符串進行設置。 由於通常情況下這個字符串都非常長而且相同產品的不同版本會返回不同的值,所以最好通過設置屬性別名來使其變短,如下:
<databaseIdProvider type="DB_VENDOR"> <property name="SQL Server" value="sqlserver"/> <property name="DB2" value="db2"/> <property name="Oracle" value="oracle" /> </databaseIdProvider>
在有 properties 時,DB_VENDOR databaseIdProvider 的將被設置爲第一個能匹配數據庫產品名稱的屬性鍵對應的值,如果沒有匹配的屬性將會設置爲 “null”。 在這個例子中,如果 getDatabaseProductName() 返回“Oracle (DataDirect)”,databaseId 將被設置爲“oracle”。
你可以通過實現接口 org.apache.ibatis.mapping.DatabaseIdProvider 並在 mybatis-config.xml 中註冊來構建自己的 DatabaseIdProvider:
public interface DatabaseIdProvider { void setProperties(Properties p); String getDatabaseId(DataSource dataSource) throws SQLException; }
映射器(mappers)
既然 MyBatis 的行爲已經由上述元素配置完了,我們現在就要定義 SQL 映射語句了。但是首先我們需要告訴 MyBatis 到哪裏去找到這些語句。 Java 在自動查找這方面沒有提供一個很好的方法,所以最佳的方式是告訴 MyBatis 到哪裏去找映射文件。你可以使用相對於類路徑的資源引用, 或完全限定資源定位符(包括 file:/// 的 URL),或類名和包名等。例如:
<!-- Using classpath relative resources --> <mappers> <mapper resource="org/mybatis/builder/AuthorMapper.xml"/> <mapper resource="org/mybatis/builder/BlogMapper.xml"/> <mapper resource="org/mybatis/builder/PostMapper.xml"/> </mappers>
<!-- Using url fully qualified paths --> <mappers> <mapper url="file:///var/mappers/AuthorMapper.xml"/> <mapper url="file:///var/mappers/BlogMapper.xml"/> <mapper url="file:///var/mappers/PostMapper.xml"/> </mappers>
<!-- Using mapper interface classes --> <mappers> <mapper class="org.mybatis.builder.AuthorMapper"/> <mapper class="org.mybatis.builder.BlogMapper"/> <mapper class="org.mybatis.builder.PostMapper"/> </mappers>
<!-- Register all interfaces in a package as mappers --> <mappers> <package name="org.mybatis.builder"/> </mappers>
這些配置會告訴了 MyBatis 去哪裏找映射文件,剩下的細節就應該是每個 SQL 映射文件了,也就是接下來我們要討論的。