Skip to content

Commit bdbd44e

Browse files
jeffgbutlerjeffgbutler
authored
Merge pull request #136 from jeffgbutler/master
Simplify the readme
2 parents e21f1ae + 5dab1a8 commit bdbd44e

File tree

1 file changed

+9
-247
lines changed

1 file changed

+9
-247
lines changed

‎README.md

Lines changed: 9 additions & 247 deletions
Original file line numberDiff line numberDiff line change
@@ -18,256 +18,18 @@ templates.
1818
The library works by implementing an SQL-like DSL that creates an object containing a full SQL statement and any
1919
parameters required for that statement. The SQL statement object can be used directly by MyBatis as a parameter to a mapper method.
2020

21-
The library will generate these types of SQL statements:
21+
The library also contains extensions for Kotlin that enable an idiomatic Kotlin DSL.
2222

23-
- DELETE statements with flexible WHERE clauses
24-
- INSERT statements of several types:
25-
- A statement that inserts a single record and will insert null values into columns (a "full" insert)
26-
- A statement that inserts a single record that will ignore null input values and their associated columns (a "selective" insert)
27-
- A statement that inserts into a table using the results of a SELECT statement
28-
- A parameter object is designed for inserting multiple objects with a JDBC batch
29-
- SELECT statements with a flexible column list, a flexible WHERE clause, and support for distinct, "group by", joins, unions, "order by", etc.
30-
- UPDATE statements with a flexible WHERE clause. Like the INSERT statement, there are two varieties of UPDATE statements:
31-
- A "full" update that will set null values
32-
- A "selective" update that will ignore null input values
23+
See the following pages for further information:
3324

34-
The primary goals of the library are:
35-
36-
1. Typesafe - to the extent possible, the library will ensure that parameter types match
37-
the database column types
38-
2. Expressive - statements are built in a way that clearly communicates their meaning
39-
(thanks to Hamcrest for some inspiration)
40-
3. Flexible - where clauses can be built using any combination of and, or, and nested conditions
41-
4. Extensible - the library will render statements for MyBatis3, Spring JDBC templates or plain JDBC.
42-
It can be extended to generate clauses for other frameworks as well. Custom where conditions can
43-
be added easily if none of the built in conditions are sufficient for your needs.
44-
5. Small - the library is a small dependency to add. It has no transitive dependencies.
45-
46-
This library grew out of a desire to create a utility that could be used to improve the code
47-
generated by MyBatis Generator, but the library can be used on it's own with very little setup required.
25+
| Page | Comments|
26+
|------|---------|
27+
|[Quick Start](src/site/markdown/docs/quickStart.md) | Shows a complete example of building code for this library |
28+
|[MyBatis3 Support](src/site/markdown/docs/mybatis3.md) | Information about specialized support for [MyBatis3](https://github.com/mybatis/mybatis-3). The examples on this page are similar to the code generated by [MyBatis Generator](https://github.com/mybatis/generator) |
29+
|[Spring Support](src/site/markdown/docs/spring.md) | Information about specialized support for Spring JDBC Templates |
30+
|[Spring Batch Support](src/site/markdown/docs/springBatch.md) | Information about specialized support for Spring Batch using the [MyBatis Spring Integration](https://github.com/mybatis/spring) |
31+
|[Kotlin Support](src/site/markdown/docs/kotlin.md) | Information about the Kotlin extensions and Kotlin DSL |
4832

4933
## Requirements
5034

5135
The library has no dependencies. Java 8 or higher is required.
52-
53-
## Show Me an Example
54-
One capability is that very expressive dynamic queries can be generated. Here's an example of what's possible:
55-
56-
```java
57-
@Test
58-
public void testComplexCondition() {
59-
try(SqlSession sqlSession = sqlSessionFactory.openSession()) {
60-
AnimalDataMapper mapper = sqlSession.getMapper(AnimalDataMapper.class);
61-
62-
SelectStatementProvider selectStatement = select(id, animalName, bodyWeight, brainWeight)
63-
.from(animalData)
64-
.where(id, isIn(1, 5, 7))
65-
.or(id, isIn(2, 6, 8), and(animalName, isLike("%bat")))
66-
.or(id, isGreaterThan(60))
67-
.and(bodyWeight, isBetween(1.0).and(3.0))
68-
.orderBy(id.descending(), bodyWeight)
69-
.build()
70-
.render(RenderingStrategies.MYBATIS3);
71-
72-
List<AnimalData> animals = mapper.selectMany(selectStatement);
73-
assertThat(animals.size()).isEqualTo(4);
74-
}
75-
}
76-
```
77-
78-
## How Do I Use It?
79-
The following discussion will walk through an example of using the library to generate a dynamic
80-
SELECT or DELETE statement. The full source code
81-
for this example is in `src/test/java/examples/simple` in this repo.
82-
83-
The database table used in the example is defined as follows:
84-
85-
```sql
86-
create table SimpleTable (
87-
id int not null,
88-
first_name varchar(30) not null,
89-
last_name varchar(30) not null,
90-
birth_date date not null,
91-
employed varchar(3) not null,
92-
occupation varchar(30) null,
93-
primary key(id)
94-
);
95-
```
96-
97-
### First - Define database table and columns
98-
The class `org.mybatis.dynamic.sql.SqlTable` is used to define a table. A table definition includes
99-
the actual name of the table (including schema or catalog if appropriate). A table alias can be applied in a
100-
select statement if desired. Your table should be defined by extending the `SqlTable` class.
101-
102-
The class `org.mybatis.dynamic.sql.SqlColumn` is used to define columns for use in the library.
103-
SqlColumns should be created using the builder methods in SqlTable.
104-
A column definition includes:
105-
106-
1. The Java type
107-
2. The actual column name (an alias can be applied in a select statement)
108-
3. The JDBC type
109-
4. (optional) The name of a type handler to use in MyBatis if the default type handler is not desired
110-
111-
We suggest the following usage pattern to give maximum flexibility. This pattern will allow you to use your
112-
table and columns in a "qualified" or "un-qualified" manner that looks like natural SQL. For example, in the
113-
following a column could be referred to as `firstName` or `simpleTable.firstName`.
114-
115-
```java
116-
package examples.simple;
117-
118-
import java.sql.JDBCType;
119-
import java.util.Date;
120-
121-
import org.mybatis.dynamic.sql.SqlColumn;
122-
import org.mybatis.dynamic.sql.SqlTable;
123-
124-
public final class SimpleTableDynamicSqlSupport {
125-
public static final SimpleTable simpleTable = new SimpleTable();
126-
public static final SqlColumn<Integer> id = simpleTable.id;
127-
public static final SqlColumn<String> firstName = simpleTable.firstName;
128-
public static final SqlColumn<String> lastName = simpleTable.lastName;
129-
public static final SqlColumn<Date> birthDate = simpleTable.birthDate;
130-
public static final SqlColumn<Boolean> employed = simpleTable.employed;
131-
public static final SqlColumn<String> occupation = simpleTable.occupation;
132-
133-
public static final class SimpleTable extends SqlTable {
134-
public final SqlColumn<Integer> id = column("id", JDBCType.INTEGER);
135-
public final SqlColumn<String> firstName = column("first_name", JDBCType.VARCHAR);
136-
public final SqlColumn<String> lastName = column("last_name", JDBCType.VARCHAR);
137-
public final SqlColumn<Date> birthDate = column("birth_date", JDBCType.DATE);
138-
public final SqlColumn<Boolean> employed = column("employed", JDBCType.VARCHAR, "examples.simple.YesNoTypeHandler");
139-
public final SqlColumn<String> occupation = column("occupation", JDBCType.VARCHAR);
140-
141-
public SimpleTable() {
142-
super("SimpleTable");
143-
}
144-
}
145-
}
146-
```
147-
148-
### Second - Write MyBatis mappers that will use the generated statement
149-
The library will create classes that will be used as input to a MyBatis mapper. These classes include the generated SQL, as well as a parameter set that will match the generated SQL. Both are required by MyBatis. It is intended that these objects be the one and only parameter to a MyBatis mapper method.
150-
151-
The library can be used with both XML and annotated mappers, but we recommend using MyBatis' annotated mapper support in all cases. The only case where XML is required is when you code a JOIN statement - in that case you will need to define your result map in XML due to limitations of the MyBatis annotations in supporting joins.
152-
153-
For example, a mapper might look like this:
154-
155-
```java
156-
package examples.simple;
157-
158-
import org.apache.ibatis.annotations.DeleteProvider;
159-
import org.apache.ibatis.annotations.Result;
160-
import org.apache.ibatis.annotations.Results;
161-
import org.apache.ibatis.annotations.SelectProvider;
162-
import org.mybatis.dynamic.sql.delete.render.DeleteStatementProvider;
163-
import org.mybatis.dynamic.sql.select.render.SelectStatementProvider;
164-
import org.mybatis.dynamic.sql.util.SqlProviderAdapter;
165-
166-
public class SimpleTableAnnotatedMapper {
167-
168-
@SelectProvider(type=SqlProviderAdapter.class, method="select")
169-
@Results(id="SimpleTableResult", value= {
170-
@Result(column="A_ID", property="id", jdbcType=JdbcType.INTEGER, id=true),
171-
@Result(column="first_name", property="firstName", jdbcType=JdbcType.VARCHAR),
172-
@Result(column="last_name", property="lastName", jdbcType=JdbcType.VARCHAR),
173-
@Result(column="birth_date", property="birthDate", jdbcType=JdbcType.DATE),
174-
@Result(column="employed", property="employed", jdbcType=JdbcType.VARCHAR, typeHandler=YesNoTypeHandler.class),
175-
@Result(column="occupation", property="occupation", jdbcType=JdbcType.VARCHAR)
176-
})
177-
List<SimpleTableRecord> selectMany(SelectStatementProvider selectStatement);
178-
179-
@DeleteProvider(type=SqlProviderAdapter.class, method="delete")
180-
int delete(DeleteStatementProvider deleteStatement);
181-
}
182-
```
183-
### Third - Create dynamic statements
184-
Select statements are created by combining your column and table definitions (from the first step above) with
185-
condition for the column. This library includes a large number of type safe conditions.
186-
All SQL construction methods can be accessed through expressive static methods in the ```org.mybatis.dynamic.sql.SqlBuilder``` interface.
187-
188-
For example, a very simple select statement can be defined like this:
189-
190-
```java
191-
SelectStatementProvider selectStatement = select(count())
192-
.from(simpleTable)
193-
.where(id, isEqualTo(3))
194-
.build()
195-
.render(RenderingStrategies.MYBATIS3);
196-
```
197-
198-
Or this (also note that you can give a table an alias):
199-
200-
```java
201-
SelectStatementProvider selectStatement = select(count())
202-
.from(simpleTable, "a")
203-
.where(id, isNull())
204-
.build()
205-
.render(RenderingStrategies.MYBATIS3);
206-
```
207-
A delete statement looks like this:
208-
209-
```java
210-
DeleteStatementProvider deleteStatement = deleteFrom(simpleTable)
211-
.where(occupation, isNull())
212-
.build()
213-
.render(RenderingStrategies.MYBATIS3);
214-
```
215-
216-
The "between" condition is also expressive:
217-
218-
```java
219-
SelectStatementProvider selectStatement = select(count())
220-
.from(simpleTable)
221-
.where(id, isBetween(1).and(4))
222-
.build()
223-
.render(RenderingStrategies.MYBATIS3);
224-
```
225-
226-
More complex expressions can be built using the "and" and "or" conditions as follows:
227-
228-
```java
229-
SelectStatementProvider selectStatement = select(count())
230-
.from(simpleTable)
231-
.where(id, isGreaterThan(2))
232-
.or(occupation, isNull(), and(id, isLessThan(6)))
233-
.build()
234-
.render(RenderingStrategies.MYBATIS3);
235-
```
236-
237-
All of these statements rely on a set of expressive static methods. It is typical to import the following:
238-
239-
```java
240-
// import all column definitions for your table
241-
import static examples.simple.SimpleTableDynamicSqlSupport.*;
242-
243-
// import the SQL builder
244-
import static org.mybatis.dynamic.sql.SqlBuilder.*;
245-
```
246-
247-
### Fourth - Use your statements
248-
In a DAO or service class, you can use the generated statement as input to your mapper methods. Here's
249-
an example from `examples.simple.SimpleTableAnnotatedMapperTest`:
250-
251-
```java
252-
@Test
253-
public void testSelectByExample() {
254-
try (SqlSession session = sqlSessionFactory.openSession()) {
255-
SimpleTableAnnotatedMapper mapper = session.getMapper(SimpleTableAnnotatedMapper.class);
256-
257-
SelectStatementProvider selectStatement = select(id.as("A_ID"), firstName, lastName, birthDate, employed, occupation)
258-
.from(simpleTable)
259-
.where(id, isEqualTo(1))
260-
.or(occupation, isNull())
261-
.build()
262-
.render(RenderingStrategies.MYBATIS3);
263-
264-
List<SimpleTableRecord> rows = mapper.selectMany(selectStatement);
265-
266-
assertThat(rows.size()).isEqualTo(3);
267-
}
268-
}
269-
```
270-
The code in the folder ```src/test/java/examples/simple``` shows how to use the library for INSERT and
271-
UPDATE statements in addition to the examples shown here. It shows a suggested usage of the library
272-
to enable a complete range of CRUD operations on a database table. Lastly, it is an example of the code that
273-
could be created by a future version of MyBatis Generator.

0 commit comments

Comments
 (0)