Skip to content

Commit 520e1be

Browse files
zero88zero88
committed
Update README.md
1 parent b1aa3c6 commit 520e1be

File tree

1 file changed

+157
-0
lines changed

1 file changed

+157
-0
lines changed

‎README.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,161 @@
1111
[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=zero88_rsql&metric=duplicated_lines_density)](https://sonarcloud.io/dashboard?id=zero88_rsql)
1212
[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=zero88_rsql&metric=coverage)](https://sonarcloud.io/dashboard?id=zero88_rsql)
1313

14+
RESTful Service Query Language (RSQL) is a language, and a library designed for searching entries in RESTful services.
15+
16+
This library provides core functionality based on [rsql-parser](https://github.com/jirutka/rsql-parser) and make extension for [jOOQ](https://www.jooq.org/), which is translated to `jOOQ DSL`.
17+
1418
## Usage
19+
20+
### With jOOQ
21+
22+
#### Parse to jOOQ Condition
23+
24+
The core functionality in `rsql-jooq` is creating `jOOQ condition` from RESTful query. For example:
25+
26+
```bash
27+
> url
28+
http://localhost:8080/api/data?q=(F_DATE=between=('2020-04-05T08:00:00','2020-04-08T08:00:00'))
29+
> jooq
30+
"ALL_DATA_TYPE"."F_DATE" between timestamp '2020-04-05 08:00:00.0' and timestamp '2020-04-08 08:00:00.0'
31+
32+
# With AND condition. Use [;] or [and]
33+
> url
34+
http://localhost:8080/api/data?q=(F_STR=='abc';F_BOOL=='true')
35+
36+
> jooq
37+
( "ALL_DATA_TYPE"."F_STR" = 'abc' and "ALL_DATA_TYPE"."F_BOOL" = true )
38+
39+
# With OR condition. Use [,] or [or]
40+
> url
41+
http://localhost:8080/api/data?q=(F_DURATION=='abc',F_PERIOD=='xyz')
42+
> jooq
43+
( "ALL_DATA_TYPE"."F_DURATION" = 'abc' or "ALL_DATA_TYPE"."F_PERIOD" = 'xyz' )
44+
45+
46+
# With combination AND and OR condition
47+
> url
48+
http://localhost:8080/api/data?q=(F_STR=='abc';F_BOOL=='true';(F_DURATION=='def',F_PERIOD=='xyz'))
49+
> jooq
50+
(
51+
"ALL_DATA_TYPE"."F_STR" = 'abc'
52+
and "ALL_DATA_TYPE"."F_BOOL" = true
53+
and (
54+
"ALL_DATA_TYPE"."F_DURATION" = 'def'
55+
or "ALL_DATA_TYPE"."F_PERIOD" = 'xyz'
56+
)
57+
)
58+
```
59+
60+
The entrypoint for the above magic is [JooqRqlParser](jooq/src/main/java/io/zero88/rsql/jooq/JooqRqlParser.java)
61+
62+
```java
63+
String query = collectQueryPart(url);
64+
// With your table
65+
Condition condition = JooqRqlParser.DEFAULT.criteria(query, Tables.ALL_DATA_TYPE);
66+
```
67+
68+
Currently, `rsql-jooq` supports these comparison nodes
69+
70+
| Name | Symbols |
71+
| --------------------- | ---------------- |
72+
| EQUAL | [==] |
73+
| NOT_EQUAL | [!=] |
74+
| GREATER_THAN | [=gt=, >] |
75+
| GREATER_THAN_OR_EQUAL | [=ge=, >=] |
76+
| LESS_THAN | [=lt=, <] |
77+
| LESS_THAN_OR_EQUAL | [=le=, <=] |
78+
| IN | [=in=] |
79+
| NOT_IN | [=out=] |
80+
| BETWEEN | [=between=] |
81+
| EXISTS | [=exists=, =nn=] |
82+
| NON_EXISTS | [=null=, =isn=] |
83+
| NULLABLE | [=nullable=] |
84+
| LIKE | [=like=] |
85+
| UNLIKE | [=nk=, =unlike=] |
86+
87+
You can add more comparison operator by extends [ComparisonOperatorProxy](core/src/main/java/io/zero88/rsql/parser/ast/ComparisonOperatorProxy.java), also following these steps:
88+
89+
```java
90+
String query = "sth-here";
91+
Set<ComparisonOperatorProxy> yourCustom = new Set<>();
92+
new JooqRqlParser(yourCustom).criteria(query, JooqConditionRqlVisitor.create)
93+
```
94+
95+
#### Integrate with jOOQ Query
96+
97+
To make a life is easier, `rsql-jooq` provide some basic queries that can execute directly to achieve records. For example:
98+
99+
```java
100+
int count = JooqFetchCountQuery.builder()
101+
.parser(jooqRqlParser)
102+
.dsl(dsl)
103+
.table(Tables.TABLES)
104+
.build()
105+
.execute(query)
106+
.intValue()
107+
108+
boolean exists = JooqFetchExistQuery.builder()
109+
.parser(jooqRqlParser)
110+
.dsl(dsl)
111+
.table(Tables.TABLES)
112+
.build()
113+
.execute(query)
114+
```
115+
116+
117+
### RSQL syntax
118+
119+
RSQL syntax is described on [RSQL-parser's project page](https://github.com/jirutka/rsql-parser#grammar-and-semantic).
120+
121+
### Add to your project
122+
123+
To use `rsql` with `jooq` add the following [dependency](https://search.maven.org/artifact/io.github.zero88/rsql-jooq/1.0.0/jar) to the dependencies section of your build descriptor:
124+
125+
- `Maven` (in your `pom.xml`):
126+
```xml
127+
<dependency>
128+
<groupId>io.github.zero88</groupId>
129+
<artifactId>rsql-jooq</artifactId>
130+
<version>1.0.0</version>
131+
</dependency>
132+
```
133+
134+
- `Gradle` (in your `build.gradle`):
135+
```groovy
136+
dependencies {
137+
api("io.github.zero88:rsql-jooq:1.0.0")
138+
}
139+
```
140+
141+
**Hint**
142+
143+
`rsql-jooq` is only depended on 2 main libraries:
144+
- `org.jooq:jooq`
145+
- `org.slf4j:slf4j-api`
146+
147+
Then you need to add `jdbc driver` jar to your project.
148+
149+
#### Use core lib
150+
151+
Because, currently I'm busy with other project, so only one portable version for `jOOQ` was implemented.
152+
153+
To develop more portable lib to another database abstraction in Java such as `Hibernate`, `JPA`, `MyBatis`, you can use only core module
154+
155+
- `Maven`
156+
```xml
157+
<dependency>
158+
<groupId>io.github.zero88</groupId>
159+
<artifactId>rsql-core</artifactId>
160+
<version>1.0.0</version>
161+
</dependency>
162+
```
163+
164+
- `Gradle`
165+
```groovy
166+
dependencies {
167+
api("io.github.zero88:rsql-core:1.0.0")
168+
}
169+
```
170+
171+
Then make extend in API core interface.

0 commit comments

Comments
 (0)