Skip to content

Commit a9721f0

Browse files
bvilelabvilela
authored
Add Documentation (#3)
1 parent 14fc6c7 commit a9721f0

File tree

1 file changed

+168
-8
lines changed

1 file changed

+168
-8
lines changed

‎README.md‎

Lines changed: 168 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,192 @@
11
# Java Util Validation Lib
22

3-
### Quality Status
3+
### :dart: Quality Status
44
[![build](https://github.com/bvilela/java-util-validation-lib/actions/workflows/maven_ci_cd.yml/badge.svg?branch=master)](https://github.com/bvilela/java-util-validation-lib/actions/workflows/maven_ci_cd.yml)
55
[![publish](https://github.com/bvilela/java-util-validation-lib/actions/workflows/maven_ci_cd_publish.yml/badge.svg)](https://github.com/bvilela/java-util-validation-lib/actions/workflows/maven_ci_cd_publish.yml)
66
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=bvilela_java-util-validation-lib&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=bvilela_java-util-validation-lib)
77
[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=bvilela_java-util-validation-lib&metric=coverage)](https://sonarcloud.io/summary/new_code?id=bvilela_java-util-validation-lib)
88

9-
### Repository Statistics
9+
### :bar_chart: Repository Statistics
1010
[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=bvilela_java-util-validation-lib&metric=ncloc)](https://sonarcloud.io/summary/new_code?id=bvilela_java-util-validation-lib)
1111
![GitHub repo size](https://img.shields.io/github/repo-size/bvilela/java-util-validation-lib)
1212
![GitHub language count](https://img.shields.io/github/languages/count/bvilela/java-util-validation-lib)
1313
![GitHub open issues](https://img.shields.io/github/issues-raw/bvilela/java-util-validation-lib)
1414
![GitHub open pull requests](https://img.shields.io/github/issues-pr/bvilela/java-util-validation-lib)
1515
<!--![GitHub forks](https://img.shields.io/github/forks/bvilela/java-util-validation-lib)-->
1616

17-
## Summary
17+
18+
## :mag_right: Summary
1819
Project with validations utils for Java based in javax and Gson.
1920

20-
## Technologies
21+
22+
## :computer: Technologies
2123
* Maven
22-
* Java 8
24+
* Java 11
2325
* [Lombok](https://projectlombok.org/)
2426
* Gson 2.9.0
2527
* Static Code Analysis: [SonarCloud](https://sonarcloud.io/)
2628

27-
## GitHub Action
28-
* Build and Test Java with Maven (branch master)
29-
* Analyze SonarCloud (branch master)
29+
30+
## :rocket: GitHub Actions
31+
* Unit Tests and Analyze SonarCloud
32+
* Build and run Unit Tests with Maven (branch master)
3033
* Publish on GitHub Packages (tag/release)
3134

35+
36+
## :hammer_and_wrench: Lib Features
37+
38+
### Annotation @ValidParseDate.
39+
40+
> :exclamation: Can use **only in String fields**.
41+
>
42+
> Annotation params:
43+
> - **message**: Error message. Default: `Value is a invalid date`.
44+
> - **pattern**: Pattern to valid/parse String Date. Default: `dd/MM/yyyy`.
45+
> - **locale**: Locale of Date input. Default: `pt_BR`.
46+
> - **parse**: Indicates whether the field will be converted to LocalDate. Default: `False`.
47+
48+
### Annotation @NotSerialized.
49+
50+
> The annotated element will **not be serialized** to gson.toJson(dto).
51+
>
52+
> :exclamation: You need to get the Gson() by the `com.bvilela.utils.GsonUtils.getGson()`.
53+
54+
55+
## :gear: Add dependency in your project
56+
To include this dependency in you project, you have to do three things.
57+
58+
1. Add as dependency in your `pom.xml`:
59+
```xml
60+
<dependency>
61+
<groupId>com.bvilela.lib</groupId>
62+
<artifactId>java-util-validation</artifactId>
63+
<version>0.0.1</version>
64+
</dependency>
65+
```
66+
67+
2. Add the GitHub repository in your `pom.xml`:
68+
```xml
69+
<repositories>
70+
<repository>
71+
<id>github</id>
72+
<name>GitHub</name>
73+
<url>https://maven.pkg.github.com/bvilela/java-util-validation-lib</url>
74+
<releases>
75+
<enabled>true</enabled>
76+
</releases>
77+
<snapshots>
78+
<enabled>true</enabled>
79+
</snapshots>
80+
</repository>
81+
</repositories>
82+
```
83+
84+
3. Add the authentication to the Package Registry in your global `settings.xml`: `USER_HOME\.m2\settings.xml`
85+
```xml
86+
<servers>
87+
<server>
88+
<id>github</id>
89+
<username>YOUR_USERNAME</username>
90+
<password>YOUR_AUTH_TOKEN</password>
91+
</server>
92+
</servers>
93+
```
94+
Replace the `YOUR_USERNAME` with your GitHub login name.
95+
96+
Replace the `YOUR_AUTH_TOKEN` with a generated GitHub Personal Access Token (PAT):
97+
98+
> *GitHub > Settings > Developer Settings > Personal access tokens > Generate new token*.
99+
>
100+
> The token needs at least the **`read:packages`** scope.
101+
>
102+
> :exclamation: Otherwise you will get a Not authorized exception.
103+
104+
105+
## :question: How to Use
106+
107+
### Case 1
108+
109+
Validate if a variable of type `String` is a **Valid date**.
110+
111+
For this, use the **`@ValidParseDate`** annotation, with the `parse` parameter as `false` or **omit** this param (default is `false`).
112+
113+
```java
114+
import com.bvilela.utils.annotation.javax.ValidParseDate;
115+
116+
public class MyExampleDTO {
117+
@ValidParseDate(message = "DateInit is a invalid date!", pattern = "dd-MM-yyyy")
118+
private String dateInit;
119+
}
120+
```
121+
122+
```java
123+
import com.bvilela.utils.annotation.javax.ValidParseDate;
124+
125+
public class MyExampleDTO {
126+
@ValidParseDate(parse = false, pattern = "dd MMMM yyyy", locale = "en")
127+
private String date; // example: 01 January 2022 (month name in English)
128+
}
129+
```
130+
131+
```java
132+
import com.bvilela.utils.annotation.javax.ValidParseDate;
133+
134+
public class MyExampleDTO {
135+
@ValidParseDate(pattern = "yyyy dd MMMM", locale = "de_DE")
136+
private String date; // example: 2022 15 Oktober (month name in German)
137+
}
138+
```
139+
140+
```java
141+
import com.bvilela.utils.annotation.javax.ValidParseDate;
142+
143+
public class MyExampleDTO {
144+
@ValidParseDate(pattern = "dd MMMM yyyy")
145+
private String date; // example: 01 janeiro 2022 (name month in Portuguese)
146+
}
147+
```
148+
149+
### Case 2
150+
151+
Validate if a variable of type `String` is a **Valid date and Convert** this value to a variable of type `LocalDate`.
152+
153+
For this, use the **`@ValidParseDate`** annotation, with the `parse` parameter as `true`.
154+
155+
In this case, you need to create a `LocalDate` variable with the same name of String variable, concatenating `Converted` in name.
156+
157+
```java
158+
import com.bvilela.utils.annotation.javax.ValidParseDate;
159+
160+
public class MyExampleDTO {
161+
@ValidParseDate(message = "DateInit is a invalid date!", pattern = "dd-MM-yyyy", parse = true)
162+
private String dateInit;
163+
164+
private LocalDate dateInitConverted;
165+
}
166+
```
167+
168+
### Case 3
169+
Use @NotSerialized annotation.
170+
171+
```java
172+
import com.bvilela.utils.annotation.gson.NotSerialized;
173+
174+
public class MyExampleDTO {
175+
private String name;
176+
177+
@NotSerialized
178+
private String nickName;
179+
180+
@NotSerialized
181+
private int age;
182+
}
183+
```
184+
185+
```java
186+
import com.bvilela.utils.GsonUtils;
187+
188+
var json = GsonUtils.getGson().toJson(dto);
189+
// json = {"name":"nameValue"}
190+
```
191+
32192
[⬆ Voltar ao topo](#java-util-validation-lib)<br>

0 commit comments

Comments
 (0)