Skip to content

Commit e9f22f9

Browse files
kazuki43zookazuki43zoo
authored
Add requirements and drop Getting started
1 parent 951f434 commit e9f22f9

File tree

1 file changed

+4
-170
lines changed

1 file changed

+4
-170
lines changed

‎README.md

Lines changed: 4 additions & 170 deletions
Original file line numberDiff line numberDiff line change
@@ -10,178 +10,12 @@ MyBatis FreeMarker Support
1010

1111
MyBatis FreeMarker Scripting Support.
1212

13-
Getting started
14-
===============
15-
16-
## Introduction
17-
18-
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.
19-
20-
If you are not familiar with FreeMarker syntax, you can view [Template Language Reference](http://freemarker.org/docs/ref.html)
21-
22-
## Install
23-
24-
mybatis-freemarker is available in Maven Central. So, if you are using maven, you can add this:
25-
26-
```xml
27-
<dependencies>
28-
<dependency>
29-
<groupId>org.mybatis.scripting</groupId>
30-
<artifactId>mybatis-freemarker</artifactId>
31-
<version>1.1.2</version>
32-
</dependency>
33-
</dependencies>
34-
```
35-
36-
If you are using gradle, you can use this snippet:
37-
38-
```groovy
39-
dependencies {
40-
compile("org.mybatis.scripting:mybatis-freemarker:1.1.2")
41-
}
42-
```
43-
44-
## Install from sources
45-
46-
- Checkout the source code
47-
- Run `mvn install` to build and to automatically install it to your local maven repo
48-
- Add maven dependency to your project
49-
50-
```xml
51-
<dependency>
52-
<groupId>org.mybatis.scripting</groupId>
53-
<artifactId>mybatis-freemarker</artifactId>
54-
<version>1.2.0-SNAPSHOT</version>
55-
</dependency>
56-
```
57-
58-
## Configuring
59-
60-
### Common
61-
62-
- (Optional) Create `mybatis-freemarker.properties` file in your classpath:
63-
64-
```
65-
basePackage=sql
66-
```
67-
68-
This will define base package to search FreeMarker templates. By default it is empty string, so you will need to provide full path to template every time.
69-
70-
### XML-driven mappers
71-
72-
If your are using annotations-driven mappers, you don't need to do anything more. If you are using XML-driven mappers too, you may need to do next steps:
73-
74-
- Register the language driver alias in your mybatis configuration file:
75-
76-
```xml
77-
<configuration>
78-
...
79-
<typeAliases>
80-
<typeAlias alias="freemarker" type="org.mybatis.scripting.freemarker.FreeMarkerLanguageDriver"/>
81-
</typeAliases>
82-
...
83-
</configuration>
84-
```
85-
86-
- (Optional) Set the freemarker as your default scripting language:
87-
88-
```xml
89-
<configuration>
90-
...
91-
<settings>
92-
<setting name="defaultScriptingLanguage" value="freemarker"/>
93-
</settings>
94-
...
95-
</configuration>
96-
```
97-
98-
## Usage in annotations-driven mappers
99-
100-
Just write your queries using FreeMarker syntax:
101-
102-
```java
103-
@Lang(FreeMarkerLanguageDriver.class)
104-
@Select("select * from names where id in (${ids?join(',')})")
105-
List<Name> findNamesByIds(@Param("ids") List<Integer> ids);
106-
```
107-
108-
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:
109-
110-
```java
111-
@Lang(FreeMarkerLanguageDriver.class)
112-
@Select("findName.ftl")
113-
Name findName(@Param("n") String name);
114-
```
115-
116-
Template will be searched in classpath using `basePackage` property that has already been described above.
117-
118-
`findName.ftl` content can be:
119-
120-
```
121-
SELECT *
122-
FROM names
123-
where firstName = <@p name="n"/>
124-
```
125-
126-
`<@p name="n"/>` is a custom directive to generate `#{n}` markup. This markup further will be passed into MyBatis engine, and it will replace this to `?`-parameter. You can't write `#{paramName}` directly, because FreeMarker supports this syntax natively (alghough it is deprecated). So, to get `?`-parameters to prepared statements works, you need to use `${r"#{paramName}"}` verbose syntax, or this directive. By the way, in XML files `${r"#{paramName}"}` is more preferrable because you don't need wrap it using `CDATA` statements. In annotations and in external templates `<@p/>` directive is more neat.
127-
128-
## Usage in XML-driven mappers
129-
130-
As in annotations, you can write inline scripts or template names.
131-
132-
```xml
133-
<!-- This is handled by FreeMarker too, because it is included into select nodes AS IS -->
134-
<sql id="cols">id, ${r"firstName"}, lastName</sql>
135-
136-
<select id="findName" resultType="org.mybatis.scripting.freemarker.Name" lang="freemarker">
137-
findName.ftl
138-
</select>
139-
140-
<select id="findNamesByIds" resultType="org.mybatis.scripting.freemarker.Name" lang="freemarker">
141-
select <include refid="cols"/> from names where id in (${ids?join(',')})
142-
</select>
143-
144-
<!-- It is not very convenient - to use CDATA blocks. Better is to create external template
145-
or use more verbose syntax: ${r"#{id}"}. -->
146-
<select id="find" resultType="org.mybatis.scripting.freemarker.Name" lang="freemarker">
147-
select * from names where id = <![CDATA[ <@p name='id'/> ]]> and id = ${id}
148-
</select>
149-
```
150-
151-
## Prepared statements parameters
152-
153-
`<@p/>` directive can be used in two scenarios:
154-
155-
- To pass parameters to prepared statements AS IS:
156-
157-
`<@p name='id'/>` (will be translated to `#{id}`, and value already presents in parameter object)
158-
159-
- To pass any value as prepared statements parameter
160-
161-
`<@p value=someValue/>` will be converted to `#{_p0}`, and `_p0` parameter will be automatically added to parameters map. It is convenient to use in loops like this:
162-
163-
```ftl
164-
select * from names where firstName in (
165-
<#list ids as id>
166-
<@p value=id/>
167-
<#if id_has_next>,</#if>
168-
</#list>
169-
)
170-
```
171-
172-
This markup will be translated to
173-
174-
```sql
175-
select * from names where firstName in (#{_p0}, #{_p1}, #{_p2})
176-
```
177-
178-
and there are no need to care about escaping. All this stuff will be done automatically by JDBC driver.
179-
180-
Unfortunately, you can't use this syntax if passing one object as parameter and without `@Param` annotation. The `UnsupportedOperationException` will be thrown. It is because appending additional parameters to some object in general is very hard. When you are using `@Param` annotated args, MyBatis will use `Map` to store parameters, and it is easy to add some generated params. So, if you want to use auto-generated prepared parameters, please don't forget about `@Param` annotation.
13+
Requirements
14+
----------
18115

182-
## Examples
16+
* master(under active development) : Version 1.2.x requires MyBatis 3.5+, FreeMarker 2.3.22+ and Java 8+
17+
* 1.1.x(latest released line) : Version 1.1.2 requires MyBatis 3.4+, FreeMarker 2.3.22+ and Java 7+
18318

184-
You can view full-featured example of configuring and of both XML-mapper and annotations-driven mapper usage in [test suite](https://github.com/elw00d/mybatis-freemarker/tree/master/src/test)
18519

18620
Essentials
18721
----------

0 commit comments

Comments
 (0)