Skip to content

Usage on framework

Jump to bottom
Kazuki Shimizu edited this page Dec 29, 2021 · 9 revisions

In this page, we explain ways that integrate with an application framework.

1. Spring Boot (with mybatis-spring-boot-starter 2.1+)

  • The mybatis-spring-boot-starter 2.1 will supports spring-boot 2.1, 2.2, 2.3 and 2.4.

  • The mybatis-spring-boot-starter 2.2 will supports spring-boot 2.2, 2.5+.

1.1. Basic configuration

Since the mybatis-spring-boot-starter 2.1+, it support the auto-configure for language driver. Therefore you can enable the this plugin on your application simply by adding this artifact under classpath. Furthermore if the LanguageDriver bean’s count is one, the auto-configure set to default scripting language driver.

1.2. Customizing a configuration

You can customize a configuration using mybatis-thymeleaf.properties. Furthermore since the mybatis-spring-boot-starter 2.1+, it support the configuration properties that prefixed mybatis.scripting-language-driver.thymeleaf for customizing this plugin feature as follow:

src/main/resources/application.properties
mybatis.scripting-language-driver.thymeleaf.use2way = false
mybatis.scripting-language-driver.thymeleaf.template-file.cache-ttl = 3600000
src/main/resources/application.yml
mybatis:
  scripting-language-driver:
    thymeleaf:
      use2way: false
      template-file:
        cache-ttl: 3600000

For more information on configurable properties, please refer to the reference documentation.

1.3. Full customizing a configuration

Also, you can fully customize a template engine by adding the ThymeleafLanguageDriver instance to the DI container using @Bean method.

Configuration class
@Bean
ThymeleafLanguageDriver thymeleafLanguageDriver() {
  TemplateEngine templateEngine = new TemplateEngine(); // (1)
  templateEngine.addDialect(new MyBatisDialect());
  templateEngine.setEngineContextFactory(new MyBatisIntegratingEngineContextFactory(
    templateEngine.getEngineContextFactory()));
  // ...
  return new ThymeleafLanguageDriver(templateEngine); // (2)
}

  1. Create an instance of class that implements org.thymeleaf.ITemplateEngine

  2. Create and return an instance of ThymeleafLanguageDriver that associate with user-defined template engine instance

2. Spring Boot (with mybatis-spring-boot-starter 2.0)

The mybatis-spring-boot-starter 2.0 supports spring-boot 2.0 and 2.1.

2.1. Basic configuration

If you are using the mybatis-spring-boot-starter(Spring Boot), you can configure using configuration properties(properties or yaml file) as follow:

src/main/resources/application.properties
mybatis.configuration.default-scripting-language=org.mybatis.scripting.thymeleaf.ThymeleafLanguageDriver

# Workaround for https://github.com/spring-projects/spring-boot/issues/16079
# Adding if need (If you use the Spring Boot 2.1.4+, this configuration not need)
spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.thymeleaf.ThymeleafAutoConfiguration
src/main/resources/application.yml
mybatis:
  configuration:
    default-scripting-language: org.mybatis.scripting.thymeleaf.ThymeleafLanguageDriver

# Workaround for https://github.com/spring-projects/spring-boot/issues/16079
# Adding if need (If you use the Spring Boot 2.1.4+, this configuration not need)
spring:
  autoconfigure:
    exclude: org.springframework.boot.autoconfigure.thymeleaf.ThymeleafAutoConfiguration

2.2. Customizing a configuration

You can customize a configuration using mybatis-thymeleaf.properties. Furthermore, you can customize using the Spring Boot configuration properties instead of mybatis-thymeleaf.properties as follow:

src/main/resources/application.properties
mybatis.configuration-properties.use-2way=false # (1)
mybatis.configuration-properties.template-file.cache-ttl=3600000
src/main/resources/application.yml
mybatis:
  configuration-properties:
    use-2way: false # (1)
    template-file.cache-ttl: 3600000
Configuration class
@Bean
ConfigurationCustomizer mybatisConfigurationCustomizer(MyBatisProperties properties) {
  return configuration -> {
    configuration.getLanguageRegistry().register(new ThymeleafLanguageDriver(
      ThymeleafLanguageDriverConfig.newInstance(properties.getConfigurationProperties()))); // (2)
    configuration.setDefaultScriptingLanguage(ThymeleafLanguageDriver.class); // (3)
  };
}

  1. Specify the configuration property of mybatis.configuration.configuration-properties.{property key} format

  2. Create a ThymeleafLanguageDriverConfig instance using Properties object that holds values of mybatis.configuration.configuration-properties.{property key} and register a ThymeleafLanguageDriver correspond with it.

  3. Set the ThymeleafLanguageDriver class as default scripting language driver at after registering a ThymeleafLanguageDriver instance instead of Spring Boot configuration properties (Very Important!!)

For more information on configurable properties, please refer to the reference documentation.

2.3. Full customizing a configuration

Also, you can fully customize a template engine using the ConfigurationCustomizer.

Configuration class
@Bean
ConfigurationCustomizer mybatisConfigurationCustomizer() {
  return configuration -> {
    TemplateEngine templateEngine = new TemplateEngine(); // (1)
    templateEngine.addDialect(new MyBatisDialect());
    templateEngine.setEngineContextFactory(new MyBatisIntegratingEngineContextFactory(
      templateEngine.getEngineContextFactory()));
    // ...
    configuration.getLanguageRegistry().register(new ThymeleafLanguageDriver(templateEngine)); // (2)
    configuration.setDefaultScriptingLanguage(ThymeleafLanguageDriver.class); // (3)
  };
}

  1. Create an instance of class that implements org.thymeleaf.ITemplateEngine

  2. Register an instance of ThymeleafLanguageDriver that associate with user-defined template engine instance

  3. Set the ThymeleafLanguageDriver class as default scripting language driver at after registering a ThymeleafLanguageDriver instance instead of Spring Boot configuration properties (Very Important!!)

Clone this wiki locally