https://github.com/tminglei/form-binder-java
Java port of form-binder, a micro data binding and validating framework
https://github.com/tminglei/form-binder-java
data-binding data-validation
Last synced: 9 months ago
JSON representation
Java port of form-binder, a micro data binding and validating framework
- Host: GitHub
- URL: https://github.com/tminglei/form-binder-java
- Owner: tminglei
- License: bsd-2-clause
- Created: 2015-06-22T00:58:42.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2021-05-23T08:46:20.000Z (over 4 years ago)
- Last Synced: 2025-04-08T12:22:57.723Z (10 months ago)
- Topics: data-binding, data-validation
- Language: Java
- Homepage:
- Size: 714 KB
- Stars: 28
- Watchers: 9
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
form-binder-java
=================
[](https://travis-ci.org/tminglei/form-binder-java)
Form-binder-java is java port of [form-binder](https://github.com/tminglei/form-binder), a micro data binding and validating framework.
Features
-------------
- very lightweight, only ~1500 lines codes (framework + built-in extensions)
- easy use, no verbose codes, and what you see is what you get
- high customizable, you can extend almost every executing point
- easily extensible, every extension interface is an alias of `FunctionN`
- immutable, you can share mapping definition object safely
Usage
-------------
To use `form-binder-java`, pls add the dependency to your `maven` project file:
```xml
com.github.tminglei
form-binder-java
0.13.5
```
Then you can use it in your codes like this:
1. define your binder
2. define your mappings
3. prepare your data
4. bind and consume
> _p.s. every points above (1)/(2)/(3)/(4)/ are all extendable and you can easily customize it._
How it works
--------------------
### Principle
The core of `form-binder` is `Mapping`, **tree structure** mappings. With **depth-first** algorithm, it was used to validate data and construct the result value object.
### Details
#### Major Components:
[1] **binder**: facade, used to bind and trigger processing, two major methods: `bind`, `validate`
[2] **messages**: used to provide error messages
[3] **mapping**: holding constraints, processors, and maybe child mapping, etc. used to validate/convert data, two types of mappings: `field` and `group`
[4] **data**: inputting data map
> _Check [here](https://github.com/tminglei/form-binder-java/blob/master/src/main/java/com/github/tminglei/bind/Framework.java) for framework details._
binder **bind** method signature (return an `BindObject` and let user to continue processing):
```java
//bind mappings to data, and return an either, holding validation errors or converted value
public BindObject bind(Framework.Mapping> mapping, Map data, String root)
```
binder **validate** method signature (_validate only_ and not consume converted data):
```java
//return (maybe processed) errors
public Optional validate(Framework.Mapping> mapping, Map data, String root)
```
> _Check [here](https://github.com/tminglei/form-binder-java/blob/master/src/main/java/com/github/tminglei/bind/Mappings.java) for built-in **mapping**s._
#### Extension Types:
(1) **ErrProcessor**: used to process error seq, like converting it to json
(2) **PreProcessor**: used to pre-process data, like omitting `$` and `,` from `$3,013`
(3) **Constraint**: used to validate raw string data
(4) **ExtraConstraint**: used to valdate converted value
> _* Check [here](https://github.com/tminglei/form-binder-java/blob/master/src/main/java/com/github/tminglei/bind/Processors.java) for built-in `PreProcessor`/`ErrProcessor`._
> _**Check [here](https://github.com/tminglei/form-binder-java/blob/master/src/main/java/com/github/tminglei/bind/Constraints.java) for built-in `Constraint`/`ExtraConstraint`._
#### Options/Features:
1) **label**: `feature`, readable name for current group/field
2) **map**: `feature`, map converted value to another type
3) **i18n**: `feature`, label starting with `@` will be used as a message key to fetch a i18n value from `messages`
4) **bean**: `feature`, transform converted values to a specified java bean
5) **eagerCheck**: `option`, check errors as more as possible; default `false`, return right after a validation error found
6) **skipUntouched**: `option`, whether skip checking untouched empty field/values; default `false`, won't skip untouched
7) **touchedChecker**: `function`, check whether a field was touched by user; if yes, required field can't be empty
#### Attachment object and meta info:
If you want to associate some extra data to a mapping, now, after some [preparing](https://github.com/tminglei/form-binder-java/blob/master/src/test/java/com/github/tminglei/bind/AttachmentTest.java#L34), you can do it like this:
```java
Mapping pet = $(mapping(
field("id", $(vLong()).desc("pet id").$$),
field("name", $(text(required())).desc("pet name").$$),
field("category", $(attach(required()).to(mapping(
field("id", vLong(required())),
field("name", text(required()))
))).desc("category belonged to").$$),
field("photoUrls", $(list(text())).desc("pet's photo urls").$$),
field("tags", $(list(text())).desc("tags for the pet").$$),
field("status", petStatus)
)).desc("pet info").$$;
```
> _With this and meta info, which can be fetched from a mapping / pre-processor / constraint / extra-constraint with `[instance].meta()`, `form-binder-java` allows third party tools, like [binder-swagger-java](https://github.com/tminglei/binder-swagger-java), to deeply know its structure and details, just like they got through java reflections, then based on it to do more._
_p.s. for more dev and usage details pls check the [source codes](https://github.com/tminglei/form-binder-java/tree/master/src/main/java/com/github/tminglei/bind) and [test cases](https://github.com/tminglei/form-binder-java/tree/master/src/test/java/com/github/tminglei/bind)._
Build & Test
-------------------
To hack it and make your contribution, you can setup it like this:
```bash
$ git clone https://github.com/tminglei/form-binder-java.git
$ cd form-binder-java
$ mvn compile
...
```
To run the tests, pls execute:
```bash
$ mvn test
```
License
---------
The BSD License, Minglei Tu <tmlneu@gmail.com>