40 | *
41 | * 42 | *47 | *43 | * <@p name="paramName"/> 44 | *45 | * 46 | *
48 | * Also directive supports `value` attribute. If it is specified, param will take passed value and create the 49 | * corresponding #{}-parameter. This is useful in loops: 50 | *
51 | *52 | * 53 | *61 | *54 | * <#list ids as id> 55 | * <@p value=id/> 56 | * <#if id_has_next>,</#if> 57 | * </#list> 58 | *59 | * 60 | *
62 | * will be translated into 63 | *
64 | *
65 | *
66 | *
67 | * #{_p0},#{_p1},#{_p2}
68 | *
69 | *
70 | *
71 | * 72 | * And MyBatis engine will convert it to `?`-params finally. 73 | *
74 | * 75 | * @author elwood 76 | */ 77 | public class MyBatisParamDirective implements TemplateDirectiveModel { 78 | public static String DEFAULT_KEY = "p"; 79 | public static String DATABASE_ID_KEY = "_databaseId"; 80 | 81 | @Override 82 | public void execute(Environment env, Map params, TemplateModel[] loopVars, TemplateDirectiveBody body) 83 | throws TemplateException, IOException { 84 | SimpleScalar name = (SimpleScalar) params.get("name"); 85 | if (params.containsKey("value")) { 86 | Object valueObject = params.get("value"); 87 | Object value; 88 | if (valueObject == null) { 89 | value = null; 90 | } else if (valueObject instanceof WrapperTemplateModel) { 91 | value = ((WrapperTemplateModel) valueObject).getWrappedObject(); 92 | } else if (valueObject instanceof TemplateScalarModel) { 93 | value = ((TemplateScalarModel) valueObject).getAsString(); 94 | } else if (valueObject instanceof TemplateNumberModel) { 95 | value = ((TemplateNumberModel) valueObject).getAsNumber(); 96 | } else if (valueObject instanceof TemplateDateModel) { 97 | value = ((TemplateDateModel) valueObject).getAsDate(); 98 | } else if (valueObject instanceof TemplateBooleanModel) { 99 | value = ((TemplateBooleanModel) valueObject).getAsBoolean(); 100 | } else { 101 | throw new UnsupportedOperationException( 102 | String.format("Type %s is not supported yet in this context.", valueObject.getClass().getSimpleName())); 103 | } 104 | 105 | TemplateModel generatedParamsObject = env.getGlobalVariables().get(FreeMarkerSqlSource.GENERATED_PARAMS_KEY); 106 | List generatedParams; 107 | if (generatedParamsObject instanceof DefaultListAdapter) { 108 | generatedParams = (List) ((DefaultListAdapter) generatedParamsObject).getWrappedObject(); 109 | } else { 110 | generatedParams = ((GeneratedParamsTemplateModel) generatedParamsObject).getGeneratedParams(); 111 | } 112 | String generatedParamName = "_p" + generatedParams.size(); 113 | env.getOut().write(String.format("#{%s}", generatedParamName)); 114 | generatedParams.add(value); 115 | } else { 116 | env.getOut().write(String.format("#{%s}", name)); 117 | } 118 | } 119 | } 120 | -------------------------------------------------------------------------------- /pom.xml: -------------------------------------------------------------------------------- 1 | 2 | 19 |33 | * IMPORTANT: This class required to use with mybatis 3.5.1+ and need to use with SQL provider annotation (such 34 | * as {@link org.apache.ibatis.annotations.SelectProvider} as follow: 35 | *
36 | * 37 | *
38 | * package com.example.mapper;
39 | *
40 | * public interface BaseMapper<T> {
41 | *
42 | * @Options(useGeneratedKeys = true, keyProperty = "id")
43 | * @InsertProvider(type = TemplateFilePathProvider.class)
44 | * void insert(T entity);
45 | *
46 | * @UpdateProvider(type = TemplateFilePathProvider.class)
47 | * void update(T entity);
48 | *
49 | * @DeleteProvider(type = TemplateFilePathProvider.class)
50 | * void delete(T entity);
51 | *
52 | * @SelectProvider(type = TemplateFilePathProvider.class)
53 | * T findById(Integer id);
54 | *
55 | * }
56 | *
57 | *
58 | *
59 | * package com.example.mapper;
60 | *
61 | * public interface NameMapper extends BaseMapper {
62 | *
63 | * @SelectProvider(type = TemplateFilePathProvider.class)
64 | * List<Name> findByConditions(NameConditions conditions);
65 | *
66 | * }
67 | *
68 | *
69 | * @author Kazuki Shimizu
70 | *
71 | * @version 1.2.0
72 | */
73 | public class TemplateFilePathProvider {
74 |
75 | private static final PathGenerator DEFAULT_PATH_GENERATOR = TemplateFilePathProvider::generateTemplatePath;
76 | private static final FreeMarkerLanguageDriverConfig DEFAULT_LANGUAGE_DRIVER_CONFIG = FreeMarkerLanguageDriverConfig
77 | .newInstance();
78 |
79 | private static PathGenerator pathGenerator = DEFAULT_PATH_GENERATOR;
80 | private static FreeMarkerLanguageDriverConfig languageDriverConfig = DEFAULT_LANGUAGE_DRIVER_CONFIG;
81 |
82 | private static ConcurrentMap101 | * By default, {@link FreeMarkerLanguageDriverConfig#newInstance()} will used. 102 | *
103 | * If you applied an user define {@link FreeMarkerLanguageDriverConfig} for {@link FreeMarkerLanguageDriver}, please 104 | * same instance to the this class. 105 | * 106 | * @param languageDriverConfig 107 | * A user defined {@link FreeMarkerLanguageDriverConfig} 108 | */ 109 | public static void setLanguageDriverConfig(FreeMarkerLanguageDriverConfig languageDriverConfig) { 110 | TemplateFilePathProvider.languageDriverConfig = Optional.ofNullable(languageDriverConfig) 111 | .orElse(DEFAULT_LANGUAGE_DRIVER_CONFIG); 112 | } 113 | 114 | /** 115 | * Provide an SQL scripting string(template file path). 116 | *
117 | * By default implementation, a template file path resolve following format and priority order. If does not match all, 118 | * it throw an exception that indicate not found a template file. 119 | *
87 | * Default is none (just under classpath). 88 | *
89 | * 90 | * @return a base directory for reading template resources 91 | * 92 | * @deprecated Recommend to use the {@link TemplateFileConfig#getBaseDir()}} because this method defined for keeping 93 | * backward compatibility (There is possibility that this method removed at a future version) 94 | */ 95 | @Deprecated 96 | public String getBasePackage() { 97 | return templateFile.getBaseDir(); 98 | } 99 | 100 | /** 101 | * Set a base directory for reading template resources. 102 | * 103 | * @param basePackage 104 | * a base directory for reading template resources 105 | * 106 | * @deprecated Recommend to use the {@link TemplateFileConfig#setBaseDir(String)} because this method defined for 107 | * keeping backward compatibility (There is possibility that this method removed at a future version) 108 | */ 109 | @Deprecated 110 | public void setBasePackage(String basePackage) { 111 | log.warn("The 'basePackage' has been deprecated since 1.2.0. Please use the 'templateFile.baseDir'."); 112 | templateFile.setBaseDir(basePackage); 113 | } 114 | 115 | /** 116 | * Get a template file configuration. 117 | * 118 | * @return a template file configuration 119 | */ 120 | public TemplateFileConfig getTemplateFile() { 121 | return templateFile; 122 | } 123 | 124 | /** 125 | * Template file configuration. 126 | */ 127 | public static class TemplateFileConfig { 128 | 129 | /** 130 | * The base directory for reading template resources. 131 | */ 132 | private String baseDir = ""; 133 | 134 | /** 135 | * The template file path provider configuration. 136 | */ 137 | private final PathProviderConfig pathProvider = new PathProviderConfig(); 138 | 139 | /** 140 | * Get the base directory for reading template resource file. 141 | *142 | * Default is {@code ""}(none). 143 | *
144 | * 145 | * @return the base directory for reading template resource file 146 | */ 147 | public String getBaseDir() { 148 | return baseDir; 149 | } 150 | 151 | /** 152 | * Set the base directory for reading template resource file. 153 | * 154 | * @param baseDir 155 | * the base directory for reading template resource file 156 | */ 157 | public void setBaseDir(String baseDir) { 158 | this.baseDir = baseDir; 159 | } 160 | 161 | /** 162 | * Get the template file path provider configuration. 163 | * 164 | * @return the template file path provider configuration 165 | */ 166 | public PathProviderConfig getPathProvider() { 167 | return pathProvider; 168 | } 169 | 170 | /** 171 | * The template file path provider configuration. 172 | */ 173 | public static class PathProviderConfig { 174 | 175 | /** 176 | * The prefix for adding to template file path. 177 | */ 178 | private String prefix = ""; 179 | 180 | /** 181 | * Whether includes package path part. 182 | */ 183 | private boolean includesPackagePath = true; 184 | 185 | /** 186 | * Whether separate directory per mapper. 187 | */ 188 | private boolean separateDirectoryPerMapper = true; 189 | 190 | /** 191 | * Whether includes mapper name into file name when separate directory per mapper. 192 | */ 193 | private boolean includesMapperNameWhenSeparateDirectory = true; 194 | 195 | /** 196 | * Whether cache a resolved template file path. 197 | */ 198 | private boolean cacheEnabled = true; 199 | 200 | /** 201 | * Get a prefix for adding to template file path. 202 | *203 | * Default is {@code ""}. 204 | *
205 | * 206 | * @return a prefix for adding to template file path 207 | */ 208 | public String getPrefix() { 209 | return prefix; 210 | } 211 | 212 | /** 213 | * Set the prefix for adding to template file path. 214 | * 215 | * @param prefix 216 | * The prefix for adding to template file path 217 | */ 218 | public void setPrefix(String prefix) { 219 | this.prefix = prefix; 220 | } 221 | 222 | /** 223 | * Get whether includes package path part. 224 | *225 | * Default is {@code true}. 226 | *
227 | * 228 | * @return If includes package path, return {@code true} 229 | */ 230 | public boolean isIncludesPackagePath() { 231 | return includesPackagePath; 232 | } 233 | 234 | /** 235 | * Set whether includes package path part. 236 | * 237 | * @param includesPackagePath 238 | * If want to includes, set {@code true} 239 | */ 240 | public void setIncludesPackagePath(boolean includesPackagePath) { 241 | this.includesPackagePath = includesPackagePath; 242 | } 243 | 244 | /** 245 | * Get whether separate directory per mapper. 246 | * 247 | * @return If separate directory per mapper, return {@code true} 248 | */ 249 | public boolean isSeparateDirectoryPerMapper() { 250 | return separateDirectoryPerMapper; 251 | } 252 | 253 | /** 254 | * Set whether separate directory per mapper. 255 | *256 | * Default is {@code true}. 257 | *
258 | * 259 | * @param separateDirectoryPerMapper 260 | * If want to separate directory, set {@code true} 261 | */ 262 | public void setSeparateDirectoryPerMapper(boolean separateDirectoryPerMapper) { 263 | this.separateDirectoryPerMapper = separateDirectoryPerMapper; 264 | } 265 | 266 | /** 267 | * Get whether includes mapper name into file name when separate directory per mapper. 268 | *269 | * Default is {@code true}. 270 | *
271 | * 272 | * @return If includes mapper name, return {@code true} 273 | */ 274 | public boolean isIncludesMapperNameWhenSeparateDirectory() { 275 | return includesMapperNameWhenSeparateDirectory; 276 | } 277 | 278 | /** 279 | * Set whether includes mapper name into file name when separate directory per mapper. 280 | *281 | * Default is {@code true}. 282 | *
283 | * 284 | * @param includesMapperNameWhenSeparateDirectory 285 | * If want to includes, set {@code true} 286 | */ 287 | public void setIncludesMapperNameWhenSeparateDirectory(boolean includesMapperNameWhenSeparateDirectory) { 288 | this.includesMapperNameWhenSeparateDirectory = includesMapperNameWhenSeparateDirectory; 289 | } 290 | 291 | /** 292 | * Get whether cache a resolved template file path. 293 | *294 | * Default is {@code true}. 295 | *
296 | * 297 | * @return If cache a resolved template file path, return {@code true} 298 | */ 299 | public boolean isCacheEnabled() { 300 | return cacheEnabled; 301 | } 302 | 303 | /** 304 | * Set whether cache a resolved template file path. 305 | * 306 | * @param cacheEnabled 307 | * If want to cache, set {@code true} 308 | */ 309 | public void setCacheEnabled(boolean cacheEnabled) { 310 | this.cacheEnabled = cacheEnabled; 311 | } 312 | 313 | } 314 | 315 | } 316 | 317 | /** 318 | * Create an instance from default properties file.| Property Key | 327 | *Description | 328 | *Default | 329 | *
|---|---|---|
| General configuration | 332 | *||
| base-package | 335 | *The base directory for reading template resources | 336 | *None(just under classpath) | 337 | *
| freemarker-settings.* | 340 | *The settings of freemarker {@link freemarker.core.Configurable#setSetting(String, String)}). | 341 | *- | 342 | *
31 | The mybatis-freemarker is a plugin that helps creating big dynamic SQL queries. You can use it selectively, to only queries that need if statmenets or foreach-loops, for example. But it is possible to use this syntax by default too. 32 |
33 |34 | If you are not familiar with FreeMarker syntax, you can view 35 |
36 |45 | If you are using maven, you can add this: 46 |
47 |If you are using gradle, you can use this snippet:
56 | 57 |mvn install to build and to automatically install it to your local maven repo
82 | By default, the mybatis-freemarker.properties file create in your classpath.
83 |
basePackage property supported for keeping backward compatibility with old versions(1.1.x or under).
94 | 128 | You may need to do next steps: 129 |
130 |Just write your queries using FreeMarker syntax:
157 |If any whitespace found inside @Select text, it is interpreted as inline script, not template name. It is convenient to avoid creating templates when script is really small. If you have a large SQL script, you can place it in distinct template and write next code:
Template will be searched in classpath using basePackage property that has already been described above.
findName.ftl content can be:
]]> is a custom directive to generate #{n} markup.
173 | This markup further will be passed into MyBatis engine, and it will replace this to ?-parameter.
174 | You can't write #{paramName} directly, because FreeMarker supports this syntax natively
175 | (alghough it is deprecated). So, to get ?-parameters to prepared statements works, you need
176 | to use ${D}{r"#{paramName}"} verbose syntax, or this directive. By the way, in XML
177 | files ${D}{r"#{paramName}"} is more preferrable because you don't need wrap it using
178 | CDATA statements. In annotations and in external templates <@p/>
179 | directive is more neat.
As in annotations, you can write inline scripts or template names.
184 |<@p/> directive can be used in two scenarios:
<@p name='id'/> (will be translated to #{id}, and value already presents in parameter object)
208 | <@p value=someValue/> will be converted to #{_p0}, and
212 | _p0 parameter will be automatically added to parameters map.
213 | It is convenient to use in loops like this:
214 | @Param annotation. The UnsupportedOperationException will be thrown.
226 | It is because appending additional parameters to some object in general is very hard.
227 | When you are using @Param annotated args, MyBatis will use Map to store parameters,
228 | and it is easy to add some generated params. So, if you want to use auto-generated prepared
229 | parameters, please don't forget about @Param annotation.
230 |
237 | The TemplateFilePathProvider is SQL provider class that return the SQL template file path(Available since 1.2.0, and this class required to use on MyBatis 3.5.1+).
238 | This class use with SQL provider annotation(@InsertProvider, @UpdateProvider, @DeleteProvider and @SelectProvider) as follow:
239 |
274 | By default implementation, a template file path resolve following format and priority order. 275 | If does not match all, it throw an exception that indicate not found a template file. 276 |
277 |com/example/mapper/NameMapper/NameMapper-{methodName}-{databaseId}.ftl
280 | com/example/mapper/NameMapper/NameMapper-{methodName}.ftl (fallback using default database)
283 | com/example/mapper/BaseMapper/BaseMapper-{methodName}-{databaseId}.ftl (fallback using declaring class of mapper method)
286 | com/example/mapper/BaseMapper/BaseMapper-{methodName}.ftl (fallback using declaring class of mapper method and default database)
289 |
293 | If you want to customize the template file path format,
294 | you can customize using following configuration properties that start with templateFile.pathProvider.
295 |
true(= includes package path).
307 | true(= separate directory per mapper).
314 | true(= includes mapper name).
321 | true(= cache a resolved template file path).
328 |
336 | TIPS
337 | Since the MyBatis 3.5.6, you can omit the type attribute at each annotations when specify the default provider class as global configuration as follow:
338 | Mapper interface:
339 |
You can view full-featured example of configuring and of both XML-mapper and annotations-driven mapper usage 363 | in test suite
364 |