Ibatis2.0使用說明——配置篇(1)

 

一、 SQL Map XML 配置文件
SQL Map 使用XML 配置文件集中的配置不同的設置屬性，包括DataSource 的詳細配置信息，SQL Map 和其他可選屬性，如線程管理等。以下是SQL Map 配置文件的一個例子：
SqlMapConfig.xml
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE sqlMapConfig
PUBLIC "-//iBATIS.com//DTD SQL Map Config 2.0//EN"
"http://www.ibatis.com/dtd/sql-map-config-2.dtd">
<!-- Always ensure to use the correct XML header as above! -->
<sqlMapConfig>
<!-- The properties (name=value) in the file specified here can be used placeholders in this config
file (e.g. "${driver}". The file is relative to the classpath and is completely optional. -->
<properties resource=" examples/sqlmap/maps/SqlMapConfigExample.properties " />
<!-- These settings control SqlMapClient configuration details, primarily to do with transaction
management. They are all optional (more detail later in this document). -->
<settings
cacheModelsEnabled="true"
enhancementEnabled="true"
lazyLoadingEnabled="true"
maxRequests="32"
maxSessions="10"
maxTransactions="5"
useStatementNamespaces="false"
/>
<!-- Type aliases allow you to use a shorter name for long fully qualified class names. -->
<typeAlias alias="order" type="testdomain.Order"/>
<!-- Configure a datasource to use with this SQL Map using SimpleDataSource.
Notice the use of the properties from the above resource -->
<transactionManager type="JDBC" >
<dataSource type="SIMPLE">
<property name="JDBC.Driver" value="${driver}"/>
<property name="JDBC.ConnectionURL" value="${url}"/>
<property name="JDBC.Username" value="${username}"/>
<property name="JDBC.Password" value="${password}"/>
<property name="JDBC.DefaultAutoCommit" value="true" />
<property name="Pool.MaximumActiveConnections" value="10"/>
<property name="Pool.MaximumIdleConnections" value="5"/>
<property name="Pool.MaximumCheckoutTime" value="120000"/>
<property name="Pool.TimeToWait" value="500"/>
<property name="Pool.PingQuery" value="select 1 from ACCOUNT"/>
<property name="Pool.PingEnabled" value="false"/>
<property name="Pool.PingConnectionsOlderThan" value="1"/>
<property name="Pool.PingConnectionsNotUsedFor" value="1"/>
</dataSource>
</transactionManager>
<!-- Identify all SQL Map XML files to be loaded by this SQL map. Notice the paths
are relative to the classpath. For now, we only have one... -->
<sqlMap resource="examples/sqlmap/maps/Person.xml" />
</sqlMapConfig>

下面詳細討論SQL Map 配置文件的各組成部分。
（一） <properties>元素
SQL Map 配置文件擁有唯一的<properties>元素，用於在配置文件中使用標準的Java屬性文件（name＝value）。在屬性文件中定義的屬性可以作爲變量在SQL Map 配置文件及其包含的所有SQL Map 映射文件中引用。
例如，如果屬性文件中包含屬性：driver=org.hsqldb.jdbcDriver

SQL Map 配置文件及其每個映射文件都可以使用佔位符${driver} 來代表值org.hsqldb.jdbcDriver。

例如：<property name="JDBC.Driver" value="${driver}"/>

這個元素在開發，測試和部署各階段都很有用。它可以使在多個不同的環境中重新配置應用和使用自動生成工具（如ANT）變得容易。

Java屬性文件可以通過類路徑導入，也可以通過有效的URL導入。

例如：<properties url="file:///c:/config/my.properties" />

（二） <setting>元素
<setting>元素用於配置和優化利用XML配置文件創建的SqlMapClient實例。<settings>元素及其所有的屬性都是可選的。下面列出了<setting>元素支持的屬性和功能：

1. maxExecute
同時執行一個Sql statement的最大線程數，大於這個值的線程將阻塞直到另一個線程退出。不同的DBMS 有不同的限制值。
例子：maxExecute="256"
缺省值：512

一般情況下，這個值要大於10，而且要同時比maxSessions和maxTransactions參數設定的值大。通常情況下，減少最大同時訪問次數可以提高執行的效率。

2. maxSessions
是指在一個給定時間內處於活動狀態的session（或客戶端）的數量。這個值一般要大於或等於maxTransactions的參數值，同時要小於maxRequests的參數值
例子： maxSessions="64"
缺省值：128

3. maxTransaction
同時進入SqlMapClient.startTransaction()的最大線程數。大於這個值的線程將阻塞直到另一個線程退出。不同的DBMS 有不同的限制值。這個值應該總是小於或等於maxSessions，而且要比maxRequests小的多。通常情況下，減少這個值可以提高執行的效率。
例子：maxTransaction="16"
缺省值：32

4. cacheModelsEnabled
啓用或禁用SqlMapClient所有的cache models。調試程序時有用。
例子：cacheModelsEnabled="true"
缺省值：true

5. lazyLoadingEnabled
啓用或禁用SqlMapClient所有的lazy loading。調試程序時有用。
例子：lazyLoadingEnabled="true"
缺省值：true

6. enhancementEnabled
This setting enables runtime bytecode enhancement to facilitate optimized JavaBean property access as well as enhanced lazy loading.
例子 enhancementEnabled="true"
缺省值： false (disabled)

7. useStatementNamespaces
這個選項如果啓用，你就必須使用全限定名來引用mapped statements，這個全名是由sqlMap的名字和statement的名字組成的。
例如：queryForObject("sqlMapName.statementName");

例子: useStatementNamespaces="false"
缺省值: false (disabled)

（三） <typeAlias>元素
<typeAlias>允許你指定別名。這樣你就可以通過你指定的短名字來代替冗長的名字了。
例如：<typeAlias alias="shortname" type="com.long.class.path.Class"/>
下面是在SqlMap中預定義的別名：
1. Transaction Manager Aliases
JDBC  com.ibatis.sqlmap.engine.transaction.jdbc.JdbcTransactionConfig
JTA  com.ibatis.sqlmap.engine.transaction.jta.JtaTransactionConfig
EXTERNAL com.ibatis.sqlmap.engine.transaction.external.ExternalTransactionConfig

2. Data Source Factory Aliases
SIMPLE  com.ibatis.sqlmap.engine.datasource.SimpleDataSourceFactory
DBCP  com.ibatis.sqlmap.engine.datasource.DbcpDataSourceFactory
JNDI  com.ibatis.sqlmap.engine.datasource.JndiDataSourceFactory

（四）<transactionManager>元素
注意：在Sql Map 1.0版本中，允許同時配置多個數據源，這樣會導致一些問題。所以從2.0的版本開始，只允許配置一個數據源，如果你有配置多個數據源的需求的話，建議你使用多個不同配置的屬性文件，或者在build Sql Map的時候，作爲一個參數傳進來。

<transactionManager>元素允許你爲SQL Map配置事務管理服務。type屬性用來指明使用哪種事務管理，值既可以是一個類名字，也可以是一個別名。

在框架中已經包含了三種事務管理：JDBC, JTA 和 EXTERNAL
 
1. JDBC
允許用JDBC通過Connection 的commit()和rollback()方法來控制事務。

2. JTA
這種事務管理使用一個JTA的全局事務將SQL Map的activities作爲一個wider scope事務的一部分而包含進來，這個事務可能包含其他的數據庫或事務
源。這個配置需要一個UserTransaction屬性來通過JNDI resource設置本地的user transaction。

3. EXTERNAL
允許你自己管理事務。你仍然可以配置一個數據源，但是事務不會在框架生命週期中被提交或回滾。這意味着你必須要用自己的程序來控制事務。這個設置對於非事務型數據庫是非常有用的。

（五） <datasource>元素
<datasource>標籤及其屬性是<transactionManager>的配置的一部分，它也是用於配置你的SQL Map所使用的數據源的。
目前本框架提供三種數據源工廠，但是你也可以自己寫一個。下面是每一種數據源工廠的配置舉例：

1. SimpleDataSourceFactory
SimpleDataSourceFactory 爲池化的DataSource提供了一個基本的實現，適用於在沒有容器提供數據源的情況。

<transactionManager type="JDBC">
 <dataSource type="SIMPLE">
  <property name="JDBC.Driver" value="org.postgresql.Driver"/>
  <property name="JDBC.ConnectionURL" value="jdbc:postgresql://server:5432/dbname"/>
  <property name="JDBC.Username" value="user"/>
  <property name="JDBC.Password" value="password"/>

  <!-- OPTIONAL PROPERTIES BELOW -->
  <property name="Pool.MaximumActiveConnections" value="10"/>
  <property name="Pool.MaximumIdleConnections" value="5"/>
  <property name="Pool.MaximumCheckoutTime" value="120000"/>
  <property name="Pool.TimeToWait" value="10000"/>
  <property name="Pool.PingQuery" value="select * from dual"/>
  <property name="Pool.PingEnabled" value="false"/>
  <property name="Pool.PingConnectionsOlderThan" value="0"/>
  <property name="Pool.PingConnectionsNotUsedFor" value="0"/>
 </dataSource>
</transactionManager>

2. DbcpDataSourceFactory
DbcpDataSourceFactory 實現使用Jakarta DBCP（Database Connection Pool）的DataSource
API 提供連接池服務。適用於Web 容器不提供DataSource 服務的情況，或執行一個單獨的
應用。DbcpDataSourceFactory 中必須要配置的參數例子如下：

<transactionManager type="JDBC">
 <dataSource type="DBCP">
  <property name="JDBC.Driver" value="${driver}"/>
  <property name="JDBC.ConnectionURL" value="${url}"/>
  <property name="JDBC.Username" value="${username}"/>
  <property name="JDBC.Password" value="${password}"/>
  <!-- OPTIONAL PROPERTIES BELOW -->
  <property name="Pool.MaximumActiveConnections" value="10"/>
  <property name="Pool.MaximumIdleConnections" value="5"/>
  <property name="Pool.MaximumWait" value="60000"/>
  <!-- Use of the validation query can be problematic.
  If you have difficulty, try without it. -->
  <property name="Pool.ValidationQuery" value="select * from ACCOUNT"/>
  <property name="Pool.LogAbandoned" value="false"/>
  <property name="Pool.RemoveAbandoned" value="false"/>
  <property name="Pool.RemoveAbandonedTimeout" value="50000"/>
 </datasource>
</transactionManager>

3. JndiDataSourceFactory
JndiDataSourceFactory 在應用服務器的容器中從JNDI Context 中查找DataSource 實現。當使用應用
服務器，並且服務器提供了容器管理的連接池和相關的DataSource 實現的情況下，可以使用
JndiDataSourceFactory。使用JDBC DataSource 的標準方法是通過JNDI 來查找。

JndiDataSourceFactory必須要配置的屬性如下：
<transactionManager type="JDBC" >
 <dataSource type="JNDI">
  <property name="DataSource" value="java:comp/env/jdbc/jpetstore"/>
 </dataSource>
</transactionManager>
注意：上面的配置是使用標準的JDBC事務管理。但是，在一個容器管理的數據源中，你也可能想爲全局的事務做如下配置：
<transactionManager type="JTA" >
 <property name="UserTransaction" value="java:/ctx/con/UserTransaction"/>
 <dataSource type="JNDI">
  <property name="DataSource" value="java:comp/env/jdbc/jpetstore"/>
 </dataSource>
</transactionManager>

注意：UserTransaction屬性指向一個JNDI的位置，你可以通過這個JNDI找到一個UserTransaction實例。這個在JTA的事務管理中是需要的，這樣可以使你的SQL MAP參與到包含有其他數據庫和事務源的事務中。

（六）<sql-map>元素
sqlMap元素用於包括SQL Map 映射文件和其他的SQL Map 配置文件。每個SqlMapClient
對象使用的SQL Map 映射文件都要在此聲明。映射文件作爲stream resource 從類路徑或URL中讀
入。您必須相對於類路徑或URL來指定所有的SQL Map 文件。
下面是幾個例子：

<!-- CLASSPATH RESOURCES -->
<sqlMap resource="com/ibatis/examples/sql/Customer.xml" />
<sqlMap resource="com/ibatis/examples/sql/Account.xml" />
<sqlMap resource="com/ibatis/examples/sql/Product.xml" />

<!-- URL RESOURCES -->
<sqlMap url="file:///c:/config/Customer.xml " />
<sqlMap url="file:///c:/config/Account.xml " />
<sqlMap url="file:///c:/config/Product.xml" />