properties

These are externalizable, substitutable properties that can be configured in a typical Java Properties file instance, or passed in through sub-elements of the properties element. For example:

  1. <properties resource="org/mybatis/example/config.properties">
  2.   <property name="username" value="dev_user"/>
  3.   <property name="password" value="F2Fa3!33TYyg"/>
  4. </properties>

The properties can then be used throughout the configuration files to substitute values that need to be dynamically configured. For example:

  1. <dataSource type="POOLED">
  2.   <property name="driver" value="${driver}"/>
  3.   <property name="url" value="${url}"/>
  4.   <property name="username" value="${username}"/>
  5.   <property name="password" value="${password}"/>
  6. </dataSource>

The username and password in this example will be replaced by the values set in the properties elements. The driver and url properties would be replaced with values contained from the config.properties file. This provides a lot of options for configuration.

Properties can also be passed into the SqlSessionFactoryBuilder.build() methods. For example:

  1. SqlSessionFactory factory =
  2.   sqlSessionFactoryBuilder.build(reader, props);
  4. // ... or ...
  6. SqlSessionFactory factory =
  7.   new SqlSessionFactoryBuilder.build(reader, environment, props);

If a property exists in more than one of these places, MyBatis loads them in the following order:

  • Properties specified in the body of the properties element are read first,
  • Properties loaded from the classpath resource or url attributes of the properties element are read second, and override any duplicate properties already specified,
  • Properties passed as a method parameter are read last, and override any duplicate properties that may have been loaded from the properties body and the resource/url attributes.

Thus, the highest priority properties are those passed in as a method parameter, followed by resource/url attributes and finally the properties specified in the body of the properties element.

Since the MyBatis 3.4.2, your can specify a default value into placeholder as follow:

  1. <dataSource type="POOLED">
  2.   <!-- ... -->
  3.   <property name="username" value="${username:ut_user}"/> <!-- If 'username' property not present, username become 'ut_user' -->
  4. </dataSource>

This feature is disabled by default. If you specify a default value into placeholder, you should enable this feature by adding a special property as follow:

  1. <properties resource="org/mybatis/example/config.properties">
  2.   <!-- ... -->
  3.   <property name="org.apache.ibatis.parsing.PropertyParser.enable-default-value" value="true"/> <!-- Enable this feature -->
  4. </properties>

NOTE This will conflict with the ":" character in property keys (e.g. db:username) or the ternary operator of OGNL expressions (e.g. ${tableName != null ? tableName : 'global_constants'}) on a SQL definition. If you use either and want default property values, you must change the default value separator by adding this special property:

  1. <properties resource="org/mybatis/example/config.properties">
  2.   <!-- ... -->
  3.   <property name="org.apache.ibatis.parsing.PropertyParser.default-value-separator" value="?:"/> <!-- Change default value of separator -->
  4. </properties>
  1. <dataSource type="POOLED">
  2.   <!-- ... -->
  3.   <property name="username" value="${db:username?:ut_user}"/>
  4. </dataSource>