MyBatis 的配置文件包含了會深深影響 MyBatis 行爲的設置和屬性信息。 配置文檔的頂層結構如下:
configuration 配置說明
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration
PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
"http://mybatis.org/dtd/mybatis-3-config.dtd">
<configuration>
<environments default="development">
<environment id="development">
<transactionManager type="JDBC"/>
<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>
<mappers>
<mapper resource="org/mybatis/example/BlogMapper.xml"/>
</mappers>
</configuration>
properties(屬性)
這些屬性都是可外部配置且可動態替換的,既可以在典型的 Java 屬性文件中配置,亦可通過 properties 元素的子元素來傳遞。例如:
<properties resource="org/mybatis/example/config.properties">
<property name="username" value="dev_user"/>
<property name="password" value="F2Fa3!33TYyg"/>
</properties>
然後其中的屬性就可以在整個配置文件中被用來替換需要動態配置的屬性值。比如:
<dataSource type="POOLED">
<property name="driver" value="${driver}"/>
<property name="url" value="${url}"/>
<property name="username" value="${username}"/>
<property name="password" value="${password}"/>
</dataSource>
這個例子中的 username 和 password 將會由 properties 元素中設置的相應值來替換。 driver 和 url 屬性將會由 config.properties 文件中對應的值來替換。這樣就爲配置提供了諸多靈活選擇。
屬性也可以被傳遞到 SqlSessionFactoryBuilder.build()方法中。例如:
SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader, props);
// ... 或者 ...
SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader, environment, props);
如果屬性在不只一個地方進行了配置,那麼 MyBatis 將按照下面的順序來加載:
- 在 properties 元素體內指定的屬性首先被讀取。
- 然後根據 properties 元素中的 resource屬性讀取類路徑下屬性文件或根據 url 屬性指定的路徑讀取屬性文件,並覆蓋已讀取的同名屬性。
- 最後讀取作爲方法參數傳遞的屬性,並覆蓋已讀取的同名屬性。
因此,通過方法參數傳遞的屬性具有最高優先級,resource/url 屬性中指定的配置文件次之,最低優先級的是 properties 屬性中指定的屬性。
從 MyBatis 3.4.2 開始,你可以爲佔位符指定一個默認值。例如:
<dataSource type="POOLED">
<!-- ... -->
<property name="username" value="${username:ut_user}"/> <!-- 如果屬性 'username' 沒有被配置,'username' 屬性的值將爲 'ut_user' -->
</dataSource>
注意: 這個特性默認是關閉的。如果你想爲佔位符指定一個默認值, 你應該添加一個指定的屬性來開啓這個特性。例如:
<properties resource="org/mybatis/example/config.properties">
<!-- ... -->
<property name="org.apache.ibatis.parsing.PropertyParser.enable-default-value" value="true"/> <!-- 啓用默認值特性 -->
</properties>
注意: 如果你已經使用 “:” 作爲屬性的鍵(如:db:username) ,或者你已經在 SQL 定義中使用 OGNL 表達式的三元運算符(如: ${tableName != null ? tableName : ‘global_constants’}),你應該通過設置特定的屬性來修改分隔鍵名和默認值的字符。例如:
<properties resource="org/mybatis/example/config.properties">
<!-- ... -->
<property name="org.apache.ibatis.parsing.PropertyParser.default-value-separator" value="?:"/> <!-- 修改默認值的分隔符 -->
</properties>
<dataSource type="POOLED">
<!-- ... -->
<property name="username" value="${db:username?:ut_user}"/>
</dataSource>
settings(設置)
這是 MyBatis 中極爲重要的調整設置,它們會改變 MyBatis 的運行時行爲。 下表描述了設置中各項的意圖、默認值等。
設置名 | 描述 | 有效值 | 默認值 |
---|---|---|---|
cacheEnabled | 全局地開啓或關閉配置文件中的所有映射器已經配置的任何緩存。 | true false | true |
lazyLoadingEnabled | 延遲加載的全局開關。當開啓時,所有關聯對象都會延遲加載。 特定關聯關係中可通過設置 fetchType 屬性來覆蓋該項的開關狀態。 | true false | false |
aggressiveLazyLoading | 當開啓時,任何方法的調用都會加載該對象的所有屬性。 否則,每個屬性會按需加載(參考 lazyLoadTriggerMethods)。 | true false | false (在 3.4.1 及之前的版本默認值爲 true) |
multipleResultSetsEnabled | 是否允許單一語句返回多結果集(需要驅動支持)。 | true false | true |
useColumnLabel | 使用列標籤代替列名。不同的驅動在這方面會有不同的表現,具體可參考相關驅動文檔或通過測試這兩種不同的模式來觀察所用驅動的結果。 | true false | true |
useGeneratedKeys | 允許 JDBC 支持自動生成主鍵,需要驅動支持。 如果設置爲 true 則這個設置強制使用自動生成主鍵,儘管一些驅動不能支持但仍可正常工作(比如 Derby)。 | true false | False |
autoMappingBehavior | 指定 MyBatis 應如何自動映射列到字段或屬性。 NONE 表示取消自動映射;PARTIAL 只會自動映射沒有定義嵌套結果集映射的結果集。 FULL 會自動映射任意複雜的結果集(無論是否嵌套)。 | NONE, PARTIAL, FULL | PARTIAL |
一個配置完整的 settings 元素的示例如下:
<settings>
<setting name="cacheEnabled" value="true"/>
<setting name="lazyLoadingEnabled" value="true"/>
<setting name="multipleResultSetsEnabled" value="true"/>
<setting name="useColumnLabel" value="true"/>
<setting name="useGeneratedKeys" value="false"/>
<setting name="autoMappingBehavior" value="PARTIAL"/>
<setting name="autoMappingUnknownColumnBehavior" value="WARNING"/>
<setting name="defaultExecutorType" value="SIMPLE"/>
<setting name="defaultStatementTimeout" value="25"/>
<setting name="defaultFetchSize" value="100"/>
<setting name="safeRowBoundsEnabled" value="false"/>
<setting name="mapUnderscoreToCamelCase" value="false"/>
<setting name="localCacheScope" value="SESSION"/>
<setting name="jdbcTypeForNull" value="OTHER"/>
<setting name="lazyLoadTriggerMethods" value="equals,clone,hashCode,toString"/>
</settings>
typeAliases(類型別名)
類型別名是爲 Java 類型設置一個短的名字。 它只和 XML 配置有關,存在的意義僅在於用來減少類完全限定名的冗餘。例如:
<typeAliases>
<typeAlias alias="Author" type="domain.blog.Author"/>
<typeAlias alias="Blog" type="domain.blog.Blog"/>
<typeAlias alias="Comment" type="domain.blog.Comment"/>
<typeAlias alias="Post" type="domain.blog.Post"/>
<typeAlias alias="Section" type="domain.blog.Section"/>
<typeAlias alias="Tag" type="domain.blog.Tag"/>
</typeAliases>
當這樣配置時,Blog 可以用在任何使用 domain.blog.Blog 的地方。
也可以指定一個包名,MyBatis 會在包名下面搜索需要的 Java Bean,比如:
<typeAliases>
<package name="domain.blog"/>
</typeAliases>
每一個在包 domain.blog 中的 Java Bean,在沒有註解的情況下,會使用 Bean 的首字母小寫的非限定類名來作爲它的別名。 比如 domain.blog.Author 的別名爲 author;若有註解,則別名爲其註解值。見下面的例子:
@Alias("author")
public class Author {
...
}
這是一些爲常見的 Java 類型內建的相應的類型別名。它們都是不區分大小寫的,注意對基本類型名稱重複採取的特殊命名風格。
別名 | 映射的類型 |
---|---|
_byte | byte |
_long | long |
_short | short |
_int | int |
_integer | int |
_double | double |
_float | float |
_boolean | boolean |
string | String |
byte | Byte |
long | Long |
short | Short |
int | Integer |
integer | Integer |
double | Double |
float | Float |
boolean | Boolean |
date | Date |
decimal | BigDecimal |
bigdecimal | BigDecimal |
object | Object |
map | Map |
hashmap | HashMap |
list | List |
arraylist | ArrayList |
collection | Collection |
iterator | Iterator |
typeHandlers(類型處理器)
無論是 MyBatis 在預處理語句(PreparedStatement)中設置一個參數時,還是從結果集中取出一個值時, 都會用類型處理器將獲取的值以合適的方式轉換成 Java 類型。下表描述了一些默認的類型處理器。
提示 從 3.4.5 開始,MyBatis 默認支持 JSR-310(日期和時間 API) 。
類型處理器 | Java 類型 | JDBC 類型 |
---|---|---|
BooleanTypeHandler | java.lang.Boolean, boolean | 數據庫兼容的 BOOLEAN |
ByteTypeHandler | java.lang.Byte, byte | 數據庫兼容的 NUMERIC 或 BYTE |
ShortTypeHandler | java.lang.Short, short | 數據庫兼容的 NUMERIC 或 SMALLINT |
IntegerTypeHandler | java.lang.Integer, int | 數據庫兼容的 NUMERIC 或 INTEGER |
LongTypeHandler | java.lang.Long, long | 數據庫兼容的 NUMERIC 或 BIGINT |
FloatTypeHandler | java.lang.Float, float | 數據庫兼容的 NUMERIC 或 FLOAT |
DoubleTypeHandler | java.lang.Double, double | 數據庫兼容的 NUMERIC 或 DOUBLE |
BigDecimalTypeHandler | java.math.BigDecimal | 數據庫兼容的 NUMERIC 或 DECIMAL |
StringTypeHandler | java.lang.String | CHAR, VARCHAR |
ClobReaderTypeHandler | java.io.Reader | - |
ClobTypeHandler | java.lang.String | CLOB, LONGVARCHAR |
NStringTypeHandler | java.lang.String | NVARCHAR, NCHAR |
NClobTypeHandler | java.lang.String | NCLOB |
BlobInputStreamTypeHandler | java.io.InputStream | - |
ByteArrayTypeHandler | byte[] | 數據庫兼容的字節流類型 |
BlobTypeHandler | byte[] | BLOB, LONGVARBINARY |
DateTypeHandler | java.util.Date | TIMESTAMP |
DateOnlyTypeHandler | java.util.Date | DATE |
TimeOnlyTypeHandler | java.util.Date | TIME |
SqlTimestampTypeHandler | java.sql.Timestamp | TIMESTAMP |
SqlDateTypeHandler | java.sql.Date | DATE |
SqlTimeTypeHandler | java.sql.Time | TIME |
ObjectTypeHandler | Any | OTHER 或未指定類型 |
EnumTypeHandler | Enumeration Type | VARCHAR 或任何兼容的字符串類型,用以存儲枚舉的名稱(而不是索引值) |
EnumOrdinalTypeHandler | Enumeration Type | 任何兼容的 NUMERIC 或 DOUBLE 類型,存儲枚舉的序數值(而不是名稱)。 |
SqlxmlTypeHandler | java.lang.String | SQLXML |
InstantTypeHandler | java.time.Instant | TIMESTAMP |
LocalDateTimeTypeHandler | java.time.LocalDateTime | TIMESTAMP |
LocalDateTypeHandler | java.time.LocalDate | DATE |
LocalTimeTypeHandler | java.time.LocalTime | TIME |
OffsetDateTimeTypeHandler | java.time.OffsetDateTime | TIMESTAMP |
OffsetTimeTypeHandler | java.time.OffsetTime | TIME |
ZonedDateTimeTypeHandler | java.time.ZonedDateTime | TIMESTAMP |
YearTypeHandler | java.time.Year | INTEGER |
MonthTypeHandler | java.time.Month | INTEGER |
YearMonthTypeHandler | java.time.YearMonth | VARCHAR 或 LONGVARCHAR |
JapaneseDateTypeHandler | java.time.chrono.JapaneseDate | DATE |
自定義類型處理器
你可以重寫類型處理器或創建你自己的類型處理器來處理不支持的或非標準的類型。 具體做法爲:實現 org.apache.ibatis.type.TypeHandler 接口, 或繼承一個很便利的類 org.apache.ibatis.type.BaseTypeHandler, 然後可以選擇性地將它映射到一個 JDBC 類型。比如:
// ExampleTypeHandler.java
@MappedJdbcTypes(JdbcType.VARCHAR)
public class ExampleTypeHandler extends BaseTypeHandler<String> {
@Override
public void setNonNullParameter(PreparedStatement ps, int i, String parameter, JdbcType jdbcType) throws SQLException {
ps.setString(i, parameter);
}
@Override
public String getNullableResult(ResultSet rs, String columnName) throws SQLException {
return rs.getString(columnName);
}
@Override
public String getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
return rs.getString(columnIndex);
}
@Override
public String getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
return cs.getString(columnIndex);
}
}
<!-- mybatis-config.xml -->
<typeHandlers>
<typeHandler handler="org.mybatis.example.ExampleTypeHandler"/>
</typeHandlers>
使用上述的類型處理器將會覆蓋已經存在的處理 Java 的 String 類型屬性和 VARCHAR 參數及結果的類型處理器。 要注意 MyBatis 不會通過窺探數據庫元信息來決定使用哪種類型,所以你必須在參數和結果映射中指明那是 VARCHAR 類型的字段, 以使其能夠綁定到正確的類型處理器上。這是因爲 MyBatis 直到語句被執行時才清楚數據類型。
通過類型處理器的泛型,MyBatis 可以得知該類型處理器處理的 Java 類型,不過這種行爲可以通過兩種方法改變:
-
在類型處理器的配置元素(typeHandler 元素)上增加一個 javaType 屬性(比如:javaType=“String”);
-
在類型處理器的類上(TypeHandler class)增加一個 @MappedTypes 註解來指定與其關聯的 Java 類型列表。如果在javaType 屬性中也同時指定,則註解方式將被忽略。
可以通過兩種方式來指定被關聯的 JDBC 類型:
- 在類型處理器的配置元素上增加一個 jdbcType 屬性(比如:jdbcType=“VARCHAR”);
- 在類型處理器的類上增加一個@MappedJdbcTypes 註解來指定與其關聯的 JDBC 類型列表。 如果在 jdbcType屬性中也同時指定,則註解方式將被忽略。
當在 ResultMap 中決定使用哪種類型處理器時,此時 Java 類型是已知的(從結果類型中獲得),但是 JDBC 類型是未知的。 因此 Mybatis 使用 javaType=[Java 類型], jdbcType=null 的組合來選擇一個類型處理器。 這意味着使用 @MappedJdbcTypes 註解可以限制類型處理器的範圍,同時除非顯式的設置,否則類型處理器在 ResultMap 中將是無效的。 如果希望在 ResultMap 中使用類型處理器,那麼設置 @MappedJdbcTypes 註解的 includeNullJdbcType=true 即可。 然而從 Mybatis 3.4.0 開始,如果只有一個註冊的類型處理器來處理 Java 類型,那麼它將是 ResultMap 使用 Java 類型時的默認值(即使沒有 includeNullJdbcType=true)。
最後,可以讓 MyBatis 爲你查找類型處理器:
<!-- mybatis-config.xml -->
<typeHandlers>
<package name="org.mybatis.example"/>
</typeHandlers>
注意在使用自動發現功能的時候,只能通過註解方式來指定 JDBC 的類型。
你可以創建一個能夠處理多個類的泛型類型處理器。爲了使用泛型類型處理器, 需要增加一個接受該類的 class 作爲參數的構造器,這樣在構造一個類型處理器的時候 MyBatis 就會傳入一個具體的類。
//GenericTypeHandler.java
public class GenericTypeHandler<E extends MyObject> extends BaseTypeHandler<E> {
private Class<E> type;
public GenericTypeHandler(Class<E> type) {
if (type == null) throw new IllegalArgumentException("Type argument cannot be null");
this.type = type;
}
EnumTypeHandler 和 EnumOrdinalTypeHandler 都是泛型類型處理器,我們將會在接下來的部分詳細探討。
處理枚舉類型
若想映射枚舉類型 Enum,則需要從 EnumTypeHandler 或者 EnumOrdinalTypeHandler 中選一個來使用。
比如說我們想存儲取近似值時用到的舍入模式。默認情況下,MyBatis 會利用 EnumTypeHandler 來把 Enum 值轉換成對應的名字。
注意 EnumTypeHandler 在某種意義上來說是比較特別的,其他的處理器只針對某個特定的類,而它不同,它會處理任意繼承了 Enum 的類。
不過,我們可能不想存儲名字,相反我們的 DBA 會堅持使用整形值代碼。那也一樣輕而易舉: 在配置文件中把 EnumOrdinalTypeHandler 加到 typeHandlers 中即可, 這樣每個 RoundingMode 將通過他們的序數值來映射成對應的整形數值。
<!-- mybatis-config.xml -->
<typeHandlers>
<typeHandler handler="org.apache.ibatis.type.EnumOrdinalTypeHandler" javaType="java.math.RoundingMode"/>
</typeHandlers>
但是怎樣能將同樣的 Enum 既映射成字符串又映射成整形呢?
自動映射器(auto-mapper)會自動地選用 EnumOrdinalTypeHandler 來處理, 所以如果我們想用普通的 EnumTypeHandler,就必須要顯式地爲那些 SQL 語句設置要使用的類型處理器。
(下一節纔開始介紹映射器文件,如果你是首次閱讀該文檔,你可能需要先跳過這裏,過會再來看。)
<!DOCTYPE mapper
PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
"http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="org.apache.ibatis.submitted.rounding.Mapper">
<resultMap type="org.apache.ibatis.submitted.rounding.User" id="usermap">
<id column="id" property="id"/>
<result column="name" property="name"/>
<result column="funkyNumber" property="funkyNumber"/>
<result column="roundingMode" property="roundingMode"/>
</resultMap>
<select id="getUser" resultMap="usermap">
select * from users
</select>
<insert id="insert">
insert into users (id, name, funkyNumber, roundingMode) values (
#{id}, #{name}, #{funkyNumber}, #{roundingMode}
)
</insert>
<resultMap type="org.apache.ibatis.submitted.rounding.User" id="usermap2">
<id column="id" property="id"/>
<result column="name" property="name"/>
<result column="funkyNumber" property="funkyNumber"/>
<result column="roundingMode" property="roundingMode" typeHandler="org.apache.ibatis.type.EnumTypeHandler"/>
</resultMap>
<select id="getUser2" resultMap="usermap2">
select * from users2
</select>
<insert id="insert2">
insert into users2 (id, name, funkyNumber, roundingMode) values (
#{id}, #{name}, #{funkyNumber}, #{roundingMode, typeHandler=org.apache.ibatis.type.EnumTypeHandler}
)
</insert>
</mapper>
注意,這裏的 select 語句強制使用 resultMap 來代替 resultType。
objectFactory(對象工廠)
MyBatis 每次創建結果對象的新實例時,它都會使用一個對象工廠(ObjectFactory)實例來完成。 默認的對象工廠需要做的僅僅是實例化目標類,要麼通過默認構造方法,要麼在參數映射存在的時候通過參數構造方法來實例化。 如果想覆蓋對象工廠的默認行爲,則可以通過創建自己的對象工廠來實現。比如:
// ExampleObjectFactory.java
public class ExampleObjectFactory extends DefaultObjectFactory {
public Object create(Class type) {
return super.create(type);
}
public Object create(Class type, List<Class> constructorArgTypes, List<Object> constructorArgs) {
return super.create(type, constructorArgTypes, constructorArgs);
}
public void setProperties(Properties properties) {
super.setProperties(properties);
}
public <T> boolean isCollection(Class<T> type) {
return Collection.class.isAssignableFrom(type);
}}
<!-- mybatis-config.xml -->
<objectFactory type="org.mybatis.example.ExampleObjectFactory">
<property name="someProperty" value="100"/>
</objectFactory>
ObjectFactory 接口很簡單,它包含兩個創建用的方法,一個是處理默認構造方法的,另外一個是處理帶參數的構造方法的。 最後,setProperties 方法可以被用來配置 ObjectFactory,在初始化你的 ObjectFactory 實例後, objectFactory 元素體中定義的屬性會被傳遞給 setProperties 方法。
plugins(插件)
MyBatis 允許你在已映射語句執行過程中的某一點進行攔截調用。默認情況下,MyBatis 允許使用插件來攔截的方法調用包括:
- Executor (update, query, flushStatements, commit, rollback,getTransaction, close, isClosed)
- ParameterHandler(getParameterObject, setParameters)
- ResultSetHandler(handleResultSets, handleOutputParameters)
- StatementHandler (prepare, parameterize, batch, update, query)
這些類中方法的細節可以通過查看每個方法的簽名來發現,或者直接查看 MyBatis 發行包中的源代碼。 如果你想做的不僅僅是監控方法的調用,那麼你最好相當瞭解要重寫的方法的行爲。 因爲如果在試圖修改或重寫已有方法的行爲的時候,你很可能在破壞 MyBatis 的核心模塊。 這些都是更低層的類和方法,所以使用插件的時候要特別當心。
通過 MyBatis 提供的強大機制,使用插件是非常簡單的,只需實現 Interceptor 接口,並指定想要攔截的方法簽名即可。
// ExamplePlugin.java
@Intercepts({@Signature(
type= Executor.class,
method = "update",
args = {MappedStatement.class,Object.class})})
public class ExamplePlugin implements Interceptor {
public Object intercept(Invocation invocation) throws Throwable {
return invocation.proceed();
}
public Object plugin(Object target) {
return Plugin.wrap(target, this);
}
public void setProperties(Properties properties) {
}
}
<!-- mybatis-config.xml -->
<plugins>
<plugin interceptor="org.mybatis.example.ExamplePlugin">
<property name="someProperty" value="100"/>
</plugin>
</plugins>
上面的插件將會攔截在 Executor 實例中所有的 “update” 方法調用, 這裏的 Executor 是負責執行低層映射語句的內部對象。
覆蓋配置類
除了用插件來修改 MyBatis 核心行爲之外,還可以通過完全覆蓋配置類來達到目的。只需繼承後覆蓋其中的每個方法,再把它傳遞到 SqlSessionFactoryBuilder.build(myConfig) 方法即可。再次重申,這可能會嚴重影響 MyBatis 的行爲,務請慎之又慎。
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);
environment(環境變量)
環境元素定義瞭如何配置環境。
<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 要匹配其中一個環境 ID。
transactionManager(事務管理器)
在 MyBatis 中有兩種類型的事務管理器(也就是 type=”[JDBC|MANAGED]”):
- JDBC – 這個配置就是直接使用了 JDBC 的提交和回滾設置,它依賴於從數據源得到的連接來管理事務作用域。
- MANAGED – 這個配置幾乎沒做什麼。它從來不提交或回滾一個連接,而是讓容器來管理事務的整個生命週期(比如 JavaEE
應用服務器的上下文)。 默認情況下它會關閉連接,然而一些容器並不希望這樣,因此需要將 closeConnection 屬性設置爲
false 來阻止它默認的關閉行爲。例如:
<transactionManager type="MANAGED">
<property name="closeConnection" value="false"/>
</transactionManager>
注意:如果你正在使用 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 (新增於3.4.5)
- poolPingQuery – 發送到數據庫的偵測查詢,用來檢驗連接是否正常工作並準備接受請求。默認是“NO PING QUERY SET”,這會導致多數數據庫驅動失敗時帶有一個恰當的錯誤消息。
- poolPingEnabled – 是否啓用偵測查詢。若開啓,需要設置 poolPingQuery 屬性爲一個可執行的 SQL語句(最好是一個速度非常快的 SQL 語句),默認值:false。
- poolPingConnectionsNotUsedFor – 配置 poolPingQuery的頻率。可以被設置爲和數據庫連接超時時間一樣,來避免不必要的偵測,默認值:0(即所有連接每一時刻都被偵測 — 當然僅當poolPingEnabled 爲 true 時適用)。
JNDI – 這個數據源的實現是爲了能在如 EJB 或應用服務器這類容器中使用,容器可以集中或在外部配置數據源,然後放置一個 JNDI 上下文的引用。這種數據源配置只需要兩個屬性:
- initial_context – 這個屬性用來在 InitialContext中尋找上下文(即,initialContext.lookup(initial_context))。這是個可選屬性,如果忽略,那麼將會直接從InitialContext 中尋找 data_source 屬性。
- 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 對應的 databaseIdProvider 實現會將 databaseId 設置爲 DatabaseMetaData#getDatabaseProductName() 返回的字符串。 由於通常情況下這些字符串都非常長而且相同產品的不同版本會返回不同的值,所以你可能想通過設置屬性別名來使其變短,如下:
<databaseIdProvider type="DB_VENDOR">
<property name="SQL Server" value="sqlserver"/>
<property name="DB2" value="db2"/>
<property name="Oracle" value="oracle" />
</databaseIdProvider>
在提供了屬性別名時,DB_VENDOR 的 databaseIdProvider 實現會將 databaseId 設置爲第一個數據庫產品名與屬性中的名稱相匹配的值,如果沒有匹配的屬性將會設置爲 “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),或類名和包名等。例如:
<!-- 使用相對於類路徑的資源引用 -->
<mappers>
<mapper resource="org/mybatis/builder/AuthorMapper.xml"/>
<mapper resource="org/mybatis/builder/BlogMapper.xml"/>
<mapper resource="org/mybatis/builder/PostMapper.xml"/>
</mappers>
<!-- 使用完全限定資源定位符(URL) -->
<mappers>
<mapper url="file:///var/mappers/AuthorMapper.xml"/>
<mapper url="file:///var/mappers/BlogMapper.xml"/>
<mapper url="file:///var/mappers/PostMapper.xml"/>
</mappers>
<!-- 使用映射器接口實現類的完全限定類名 -->
<mappers>
<mapper class="org.mybatis.builder.AuthorMapper"/>
<mapper class="org.mybatis.builder.BlogMapper"/>
<mapper class="org.mybatis.builder.PostMapper"/>
</mappers>
<!-- 將包內的映射器接口實現全部註冊爲映射器 -->
<mappers>
<package name="org.mybatis.builder"/>
</mappers>
這些配置會告訴了 MyBatis 去哪裏找映射文件,剩下的細節就應該是每個 SQL 映射文件了,也就是接下來我們要討論的。