Overview

This project is a simple wrapper for com.fasterxml.jackson JSON parser. It enables fluent building, reading, and mapping of JSON objects and arrays.

Status

Getting started

Maven

<dependency>
    <groupId>com.yupzip.json</groupId>
    <artifactId>yupzip-json</artifactId>
    <version>3.0.0</version>
</dependency>

Gradle

implementation group: 'com.yupzip.json', name: 'yupzip-json', version: '3.0.0'

Prerequisites

This library requires JDK 21+ (yupzip-json with JDK 17 support is 2.4.0) (yupzip-json with JDK 1.8 support is 1.8.5)

Usage

1. Building

Fluent JSON object creation:

Json person = Json.create()
                .put("id", 1)
                .put("name", "John Citizen")
                .add("gender", personEntity.getGender()) //adds property only if value is not null
                .put("weight", 90.1)
                .put("verified", true)
                .put("contactNumbers", List.of("0400000000", "0400000001"))
                .put("address", Json.create()
                        .put("addressLine", "100 George Street")
                        .put("postCode", "2000")
                        .put("state", "NSW")
                        .put("country", "Australia"))
                .put("dob", "1990-01-01");

2. Reading

Json person = Json.create();

int id = person.integer("id");
String name = person.string("name");
String gender = person.stringOr("gender", "unknown"); //returns property value or default value if null
Double weight = person.decimal("weight");
List<String> contactNumbers = person.strings("contactNumbers");
Json address = person.object("address");
Date dob = person.date("dob", "yyyy-MM-dd");

Company company = loadCompany();
List<String> employeeNames = Json.parse(company)
                      .stream("employees")
                      .map(employee -> employee.string("fullName"))
                      .collect(Collectors.toList());

3. Mapping

Fluent mapping of JSON properties:

Json response = Json.create(); //response payload
Person person = new Person();
Address address = new Address();

response.map("name", person::setName) // generic mapping of property value (type is defined by consumer)
        .integer("id", person::setId) // or mapping explicit types
        .decimal("weight", person::setWeight)
        .bool("verified", person::setVerified)
        .strings("contactNumbers", person::setContactNumbers)
        .integers("numbers", person::setNumbers)
        .decimals("scores", person::setScores)
        .object("address", addressJson -> addressJson // or mapping child json object
                .map("addressLine", address::setAddressLine)
                .map("postCode", address::setPostCode)
                .map("state", address::setState)
                .map("country", address::setCountry));

4. Parsing/Converting

Parsing JSON string:

String personString = """
            {
               "id": 1,
               "name": "John Citizen"
            }
            """;
Json person = Json.parse(personString);

Converting from/to Java POJOs:

Person person = new Person(1, "John Citizen");
Json json = Json.parse(person);

Person person = Json.create()
                  .put("id", 1)
                  .put("name", "John Citizen")
                  .convertTo(Person.class);

5. Spring REST

As RestController request body:

@PutMapping("/v1/customers")
public void createCustomer(@RequestBody Json request) {
    customerService.createCustomer(request);
}

As RestTemplate HttpEntity:

public List<Product> getProducts(String url) {
    ResponseEntity<Json> responseEntity = restTemplate.getForEntity(url, Json.class);
    Json response = Objects.requireNonNull(responseEntity.getBody());
    return response.stream("data")
                .map(item -> Product.of(item.integer("id")
                                .withName(item.string("name")
                                .withPrice(item.decimal("price")))))
                .collect(Collectors.toList());
}

Configuration

Jackson serialization/deserialization

Configuration via application.properties:

jackson.property-naming-strategy=UPPER_CAMEL_CASE
jackson.deserialization.fail-on-unknown-properties=false
jackson.serialization.fail-on-empty-beans=false
jackson.default-property-inclusion=ALWAYS
jackson.visibility.field=ANY
jackson.visibility.getter=NONE
jackson.visibility.is-getter=NONE
jackson.visibility.setter=NONE
jackson.disabled-features=WRITE_DATES_AS_TIMESTAMPS,FAIL_ON_EMPTY_BEANS

yupzip.Json collection type

JSON properties (keys/values) are stored in a java.util.Map Map<String, Object> properties. This map is a HashMap by default, however this can be changed to LinkedHashMap if required via property:

yupzip.json.map-type=LINKED_HASH_MAP

Contributing

License

This project is licensed under Apache License Version 2.0 - LICENSE.md