Introduction

mybatis-velocity is an extension that allows you to use the Apache Velocity scripting language to generate your dynamic SQL queries on the fly.

If you are not familiar with apache velocity, you can learn it from its documentation site:

Velocity Template Language (VTL) Reference

Requirments

Java : Java 8+
MyBatis : 3.5+
Velocity : 2.1+

Install

If you are using maven, you can add this:


<dependency>
    <groupId>org.mybatis.scripting</groupId>
    <artifactId>mybatis-velocity</artifactId>
    <version>2.1.0</version>
</dependency>

If you are using gradle, you can use this snippet:


dependencies {
    compile("org.mybatis.scripting:mybatis-velocity:2.1.0")
}

Configuration

Common

By default, the mybatis-velocity.properties file create in your classpath.

You can specify user defined custom directives to use on the Velocity template engine using the Velocity standard property(runtime.custom_directives). For details see the "User Defined Directives".
```
velocitySettings.runtime.custom_directives = com.example.directives.MyDirective
# or
runtime.custom_directives = com.example.directives.MyDirective
```
The userdirective property supported for keeping backward compatibility with old versions(2.0 or under).
```
userdirective = com.example.directives.MyDirective
```

You can specify user defined additional context attribute values that passed to template engine. For details see the "Additional Context Attributes".


# additionalContextAttributes.{name} = {value}
# 'additional-context-attributes' (kebab-case) can be used too
additionalContextAttributes.likeEscape = com.example.helpers.LikeEscape
additionalContextAttributes.masterCacheFacade = com.example.helpers.MasterCacheFacade

The additional.context.attributes property supported for keeping backward compatibility with old versions(2.0 or under).


# Value format: {name}:{value}(,...)
additional.context.attributes = likeEscape:com.example.helpers.LikeEscape,masterCacheFacade:com.example.helpers.MasterCacheFacade

You can configure the Velocity configuration as follow: About available setting name, please refer to the reference documentation of Velocity.
```
# velocitySettings.{name} = {value}
# 'velocity-settings' (kebab-case) can be used too
velocitySettings.resource.default_encoding = Windows-31J
```
The {name} = {value} format(without prefixed 'velocitySettings') supported for keeping backward compatibility with old versions(2.0 or under).
```
# This setting is same with 'velocitySettings.resource.default_encoding'
resource.default_encoding = Windows-31J
```

Since 2.1.0, you can use an any properties file or encoding as follow:


$ java -Dmybatis-velocity.config.file=mybatis-velocity_production.properties -Dmybatis-velocity.config.encoding=Windows-31J ...

Scripting Language Driver

You may need to do next steps:


<configuration>
  ...
  <typeAliases>
    <typeAlias alias="velocity" type="org.mybatis.scripting.velocity.VelocityLanguageDriver"/>
  </typeAliases>
  ...
</configuration>

Set the velocity as your default scripting language:


<configuration>
  ...
  <settings>
      <setting name="defaultScriptingLanguage" value="velocity"/>
  </settings>
  ...
</configuration>

Usage

Just write your dynamic queries and use velocity:

Example:


<select id="findPerson" lang="velocity">
  #set( $pattern = $_parameter.name + '%' )
  SELECT *
  FROM person
  WHERE name LIKE @{pattern, jdbcType=VARCHAR}
</select>

Note:

#{...} syntax is replaced by @{...} syntax to avoid collisions with VTL

MyBatis