README.md

form-binder-java

Form-binder-java is java port of 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:

<dependency>
  <groupId>com.github.tminglei</groupId>
  <artifactId>form-binder-java</artifactId>
  <version>0.13.5</version>
</dependency>

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 for framework details.

binder bind method signature (return an BindObject and let user to continue processing):

//bind mappings to data, and return an either, holding validation errors or converted value
public BindObject bind(Framework.Mapping<?> mapping, Map<String, String> data, String root)

binder validate method signature (validate only and not consume converted data):

//return (maybe processed) errors
public <Err> Optional<Err> validate(Framework.Mapping<?> mapping, Map<String, String> data, String root)

Check here for built-in mappings.

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 for built-in PreProcessor/ErrProcessor.
**Check here 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, you can do it like this:

Mapping<BindObject> 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, 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 and test cases.

Build & Test

To hack it and make your contribution, you can setup it like this:

 $ git clone https://github.com/tminglei/form-binder-java.git
 $ cd form-binder-java
 $ mvn compile
...

To run the tests, pls execute:

 $ mvn test

License

The BSD License, Minglei Tu <[email protected]>