Skip to content

Commit 171ed00

Browse files
HectorBstHectorBst
committed
Added documentation
1 parent 225136c commit 171ed00

File tree

9 files changed

+350
-2
lines changed

9 files changed

+350
-2
lines changed

‎README.md‎

Lines changed: 344 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,349 @@
11
# jsonschema2pojo-spring-data-couchbase
22

3+
This project is a [*jsonschema2pojo*](https://github.com/joelittlejohn/jsonschema2pojo) extension dedicated to
4+
[*Spring Data Couchbase*](https://docs.spring.io/spring-data/couchbase/docs/current/reference/html) entities generation.
5+
6+
## Features
7+
8+
### Couchbase document
9+
10+
At the schema of an object level, it is possible to define a POJO as being a Couchbase document using the custom JSON
11+
property `x-cb-document`.
12+
13+
* If missing, the value of this property is `false`.
14+
* The `true` value is equivalent to `{}`.
15+
* The schema of the content of this custom property is available [here](src/main/resources/schema/document.json).
16+
17+
This property is responsible for generating the [`Document`](https://docs.spring.io/spring-data/couchbase/docs/current/api/org/springframework/data/couchbase/core/mapping/Document.html)
18+
annotation.
19+
20+
E.g., this schema:
21+
```json
22+
{
23+
"title": "Sample entity",
24+
"type": "object",
25+
"x-cb-document": true,
26+
"properties": {
27+
"..."
28+
}
29+
}
30+
```
31+
Will produce:
32+
```java
33+
@Document
34+
public class Entity {
35+
...
36+
}
37+
```
38+
39+
Some sub-properties are available to manage the annotation parameters (detailed in the annotation's documentation).
40+
41+
E.g., this schema:
42+
```json
43+
{
44+
"title": "Sample entity",
45+
"type": "object",
46+
"x-cb-document": {
47+
"expiry": 2,
48+
"expiryUnit": "MINUTES",
49+
"touchOnRead": true
50+
},
51+
"properties": {
52+
"..."
53+
}
54+
}
55+
```
56+
Will produce:
57+
```java
58+
@Document(expiry = 2, expiryUnit = TimeUnit.MINUTES, touchOnRead = true)
59+
public class Entity {
60+
...
61+
}
62+
```
63+
64+
### Document id
65+
66+
At the property of an object level, it is possible to define a field as being a document id using the custom JSON
67+
property `x-cb-id`.
68+
69+
* If missing, the value of this property is `false`.
70+
* The `true` value is equivalent to `{}`.
71+
* The schema of the content of this custom property is available [here](src/main/resources/schema/id.json).
72+
73+
This property is responsible for generating the [`Id`](https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/annotation/Id.html)
74+
annotation.
75+
76+
E.g., this schema:
77+
```json
78+
{
79+
"..."
80+
"properties": {
81+
"..."
82+
"id": {
83+
"title": "Entity id",
84+
"type": "string",
85+
"format": "uuid",
86+
"x-cb-id": true
87+
},
88+
"..."
89+
}
90+
}
91+
```
92+
Will produce:
93+
```java
94+
@Id
95+
private UUID id;
96+
```
97+
98+
A sub-property `generated` is available to manage the generating of the [`GeneratedValue`](https://docs.spring.io/spring-data/couchbase/docs/current/api/org/springframework/data/couchbase/core/mapping/id/GeneratedValue.html)
99+
annotation and its parameters (detailed in the annotation's documentation).
100+
101+
E.g., this schema:
102+
```json
103+
{
104+
"..."
105+
"properties": {
106+
"..."
107+
"id": {
108+
"title": "Entity id",
109+
"type": "string",
110+
"format": "uuid",
111+
"x-cb-id": {
112+
"generated": true
113+
}
114+
},
115+
"..."
116+
}
117+
}
118+
```
119+
Will produce:
120+
```java
121+
@Id
122+
@GeneratedValue
123+
private UUID id;
124+
```
125+
126+
And this schema:
127+
```json
128+
{
129+
"..."
130+
"properties": {
131+
"..."
132+
"id": {
133+
"title": "Entity id",
134+
"type": "string",
135+
"format": "uuid",
136+
"x-cb-id": {
137+
"generated": {
138+
"delimiter": "::",
139+
"strategy": "USE_ATTRIBUTES"
140+
}
141+
}
142+
},
143+
"..."
144+
}
145+
}
146+
```
147+
Will produce:
148+
```java
149+
@Id
150+
@GeneratedValue(delimiter = "::", strategy = GenerationStrategy.USE_ATTRIBUTES)
151+
private String id;
152+
```
153+
154+
### Document CAS
155+
156+
At the property of an object level, it is possible to define a field as being a document CAS (Compare And Swap) using
157+
the custom JSON property `x-cb-cas`.
158+
159+
If missing, the value of this property is `false`.
160+
161+
This property is responsible for generating the [`Version`](https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/annotation/Version.html)
162+
annotation.
163+
164+
Note that the type of a CAS field must be `Long` or `long`. This can be achieved through a `formatTypeMapping` or the
165+
`useLongIntegers` option.
166+
167+
E.g., this schema:
168+
```json
169+
{
170+
"..."
171+
"properties": {
172+
"..."
173+
"cas": {
174+
"title": "Couchbase CAS",
175+
"type": "integer",
176+
"format": "int64",
177+
"x-cb-cas": true
178+
},
179+
"..."
180+
}
181+
}
182+
```
183+
Will produce:
184+
```java
185+
@Version
186+
private Long cas;
187+
```
188+
189+
### Document field
190+
191+
At the property of an object level, it is possible to define a field as being a document id using the custom JSON
192+
property `x-cb-field`.
193+
194+
* If missing and if the field is not already marked as being an id, a cas or a join, the value of this property is
195+
`true`.
196+
* If missing and if the field is already marked as being an id, a cas or a join, the value of this property is
197+
`false`.
198+
* The `true` value is equivalent to `{}`.
199+
* The schema of the content of this custom property is available [here](src/main/resources/schema/field.json).
200+
201+
This property is responsible for generating the [`Field`](https://docs.spring.io/spring-data/couchbase/docs/current/api/org/springframework/data/couchbase/core/mapping/Field.html)
202+
annotation.
203+
204+
E.g., this schema:
205+
```json
206+
{
207+
"..."
208+
"properties": {
209+
"..."
210+
"field": {
211+
"title": "A field",
212+
"type": "string"
213+
},
214+
"..."
215+
}
216+
}
217+
```
218+
Will produce:
219+
```java
220+
@Field
221+
private String field;
222+
```
223+
224+
Some sub-properties are available to manage the annotation parameters (detailed in the annotation's documentation).
225+
226+
E.g., this schema:
227+
```json
228+
{
229+
"..."
230+
"properties": {
231+
"..."
232+
"field": {
233+
"title": "A field",
234+
"type": "string",
235+
"x-cb-field": {
236+
"name": "field_",
237+
"order": 5
238+
}
239+
},
240+
"..."
241+
}
242+
}
243+
```
244+
Will produce:
245+
```java
246+
@Field(name = "field_", order = 5)
247+
private String field;
248+
```
249+
250+
Some sub-properties are available to manage the generating of the annotations targeted at building the document id using the field value, and their parameters (detailed in the annotation's documentation).
251+
* `idPrefix` for the [`IdPrefix`](https://docs.spring.io/spring-data/couchbase/docs/current/api/org/springframework/data/couchbase/core/mapping/id/IdPrefix.html)
252+
annotation.
253+
* `idAttribute` for the [`IdAttribute`](https://docs.spring.io/spring-data/couchbase/docs/current/api/org/springframework/data/couchbase/core/mapping/id/IdAttribute.html)
254+
annotation.
255+
* `idSuffix` for the [`IdSuffix`](https://docs.spring.io/spring-data/couchbase/docs/current/api/org/springframework/data/couchbase/core/mapping/id/IdSuffix.html)
256+
annotation.
257+
258+
E.g., this schema:
259+
```json
260+
{
261+
"..."
262+
"properties": {
263+
"..."
264+
"field": {
265+
"title": "A field",
266+
"type": "string",
267+
"x-cb-field": {
268+
"idPrefix": true
269+
}
270+
},
271+
"..."
272+
}
273+
}
274+
```
275+
Will produce:
276+
```java
277+
@Field
278+
@IdPrefix
279+
private String field;
280+
```
281+
And this schema:
282+
```json
283+
{
284+
"..."
285+
"properties": {
286+
"..."
287+
"field": {
288+
"title": "A field",
289+
"type": "string",
290+
"x-cb-field": {
291+
"idAttribute": {
292+
"order": 2
293+
}
294+
}
295+
},
296+
"..."
297+
}
298+
}
299+
```
300+
Will produce:
301+
```java
302+
@Field
303+
@IdAttribute(order = 2)
304+
private String field;
305+
```
306+
307+
## Maven configuration
308+
309+
Here is an example of how the extension can be added to the jsonschema2pojo Maven plugin.
310+
311+
```xml
312+
<plugin>
313+
<groupId>org.jsonschema2pojo</groupId>
314+
<artifactId>jsonschema2pojo-maven-plugin</artifactId>
315+
<version>${jsonschema2pojo.version}</version>
316+
<executions>
317+
<execution>
318+
<goals>
319+
<goal>generate</goal>
320+
</goals>
321+
<configuration>
322+
...
323+
<!-- Extension RuleFactory -->
324+
<customRuleFactory>
325+
org.jsonschema2pojo.springframework.data.couchbase.rules.SpringDataCouchbaseRuleFactory
326+
</customRuleFactory>
327+
</configuration>
328+
</execution>
329+
</executions>
330+
<dependencies>
331+
<!-- Extension dependency -->
332+
<dependency>
333+
<groupId>com.github.hectorbst.jsonschema2pojo</groupId>
334+
<artifactId>jsonschema2pojo-spring-data-couchbase</artifactId>
335+
<version>${jsonschema2pojo-spring-data-couchbase.version}</version>
336+
</dependency>
337+
<!-- Spring Data Couchbase dependency -->
338+
<dependency>
339+
<groupId>org.springframework.boot</groupId>
340+
<artifactId>spring-boot-starter-data-couchbase</artifactId>
341+
<version>${spring-boot.version}</version>
342+
</dependency>
343+
</dependencies>
344+
</plugin>
345+
```
346+
3347
## License
4348

5349
This project is released under version 2.0 of the [Apache License](https://www.apache.org/licenses/LICENSE-2.0).

‎example/pom.xml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,6 @@
3535
<goals>
3636
<goal>generate</goal>
3737
</goals>
38-
<phase>generate-sources</phase>
3938
<configuration>
4039
<sourceDirectory>${basedir}/src/main/schema</sourceDirectory>
4140
<targetPackage>org.jsonschema2pojo.springframework.data.couchbase.example</targetPackage>

‎example/src/main/schema/entity1.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"$schema": "https://json-schema.org/draft-07/schema#",
33
"title": "Sample entity",
4+
"type": "object",
45
"x-cb-document": true,
56
"properties": {
67
"id": {

‎example/src/main/schema/entity2.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"$schema": "https://json-schema.org/draft-07/schema#",
33
"title": "Sample entity",
4+
"type": "object",
45
"x-cb-document": {
56
"expiry": 2,
67
"expiryUnit": "MINUTES",

‎example/src/main/schema/entity3.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"$schema": "https://json-schema.org/draft-07/schema#",
33
"title": "Sample entity",
4+
"type": "object",
45
"x-cb-document": true,
56
"properties": {
67
"id": {

‎example/src/main/schema/entity4.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"$schema": "https://json-schema.org/draft-07/schema#",
33
"title": "Sample entity",
4+
"type": "object",
45
"x-cb-document": {
56
"compositeIndexes": [
67
{

‎example/src/main/schema/entity5.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"$schema": "https://json-schema.org/draft-07/schema#",
33
"title": "Sample entity",
4+
"type": "object",
45
"x-cb-document": true,
56
"properties": {
67
"id": {

0 commit comments

Comments
 (0)