Holon platform JSON module

Latest release: 5.7.0

This is the JSON module of the Holon Platform, which provides support for the JSON data-interchange format using the must popular serialization and deserialization libraries:

• Jackson
• Gson

The module main features are:

• A simple JSON objects serialization and deserialization API, to use concrete JSON parsers implementation in a easier and abstract way, providing also useful helper methods for Collections and PropertyBox types serialization and deserialization.
• JSON serialization and deserialization support for the PropertyBox platform foundation data container class.
• JAX-RS configuration and auto-configuration support to enable Gson as default JSON type messages serialization and deserialization engine with PropertyBox support and to enable PropertyBox serialization and deserialization when using Jackson as default provider.
• Full support of the Java 8 date and time API: the java.time.* data types serialization and deserialization is supported and enabled out-of-the-box.
• The ISO-8601 format is used by default to serialize the java.util.Date data types.
• Spring support to configure PropertyBox serialization and deserialization in RestTemplate JSON message converters.
• Spring Boot support to auto-configure Gson and ObjectMapper instances with PropertyBox serialization and deserialization capabilities.

See the module documentation for details.

Just like any other platform module, this artifact is part of the Holon Platform ecosystem, but can be also used as a stand-alone library.

See Getting started and the platform documentation for further details.

At-a-glance overview

JSON API - serialization:

Json json = Json.require();

JsonWriter result = json.toJson(myObject);
String asString = result.asString(); 
byte[] asBytes = result.asBytes(); 
result.write(new StringWriter()); 
		
asString = json.toJsonString(myObject);

JSON API - deserialization:

Json json = Json.require();

MyObject result = json.fromJson("JSON string", MyObject.class);
		
result = json.fromJson(JsonReader.from(new StringReader("JSON string")), MyObject.class);

JSON API - Property model:

StringProperty NAME = StringProperty.create("name");
StringProperty SURNAME = StringProperty.create("surname");
PropertySet<?> PROPERTY_SET = PropertySet.of(NAME, SURNAME);
		
PropertyBox propertyBox = PropertyBox.builder(PROPERTY_SET).set(NAME, "John").set(SURNAME, "Doe").build();
		
Json json = Json.require();
		
String jsonValue = json.toJson(propertyBox).asString();
PropertyBox result = json.fromJson(jsonValue, PROPERTY_SET);

JSON API - Provider:

// Using Jackson
Json jsonApi = JacksonJson.create();
		
// Using Gson
Json jsonApi = GsonJson.create();

Jackson - Property model support:

ObjectMapper mapper = JacksonConfiguration.mapper();
// serialize
PropertyBox propertyBox = PropertyBox.builder(PROPERTY_SET).set(NAME, "John").set(SURNAME, "Doe").build();
String json = mapper.writer().writeValueAsString(propertyBox);
// deserialize
PropertyBox value = PROPERTY_SET.execute(() -> mapper.reader().forType(PropertyBox.class).readValue(json));

Gson - Property model support:

Gson gson = GsonConfiguration.builder().create();
// serialize
PropertyBox propertyBox = PropertyBox.builder(PROPERTY_SET).set(NAME, "John").set(SURNAME, "Doe").build();
String json = gson.toJson(propertyBox);
// deserialize
PropertyBox value = PROPERTY_SET.execute(() -> gson.fromJson(json, PropertyBox.class));

See the module documentation for the user guide and a full set of examples.

Code structure

See Holon Platform code structure and conventions to learn about the "real Java API" philosophy with which the project codebase is developed and organized.

Getting started

System requirements

The Holon Platform is built using Java 11, so you need a JRE/JDK version 11 or above to use the platform artifacts.

Releases

See releases for the available releases. Each release tag provides a link to the closed issues.

Obtain the artifacts

The Holon Platform is open source and licensed under the Apache 2.0 license. All the artifacts (including binaries, sources and javadocs) are available from the Maven Central repository.

The Maven group id for this module is com.holon-platform.json and a BOM (Bill of Materials) is provided to obtain the module artifacts:

Maven BOM:

<dependencyManagement>
    <dependency>
        <groupId>com.holon-platform.json</groupId>
        <artifactId>holon-json-bom</artifactId>
        <version>5.7.0</version>
        <type>pom</type>
        <scope>import</scope>
    </dependency>
</dependencyManagement>

See the Artifacts list for a list of the available artifacts of this module.

Using the Platform BOM

The Holon Platform provides an overall Maven BOM (Bill of Materials) to easily obtain all the available platform artifacts:

Platform Maven BOM:

<dependencyManagement>
    <dependency>
        <groupId>com.holon-platform</groupId>
        <artifactId>bom</artifactId>
        <version>${platform-version}</version>
        <type>pom</type>
        <scope>import</scope>
    </dependency>
</dependencyManagement>

See the Artifacts list for a list of the available artifacts of this module.

Build from sources

You can build the sources using Maven (version 3.3.x or above is recommended) like this:

mvn clean install

Getting help

• Check the platform documentation or the specific module documentation.

• Ask a question on Stack Overflow. We monitor the holon-platform tag.

• Report an issue.

• A commercial support is available too.

Examples

See the Holon Platform examples repository for a set of example projects.

Contribute

See Contributing to the Holon Platform.

Join the contribute Gitter room for any question and to contact us.

License

All the Holon Platform modules are Open Source software released under the Apache 2.0 license.

Artifacts list

Maven group id: com.holon-platform.json

Artifact id	Description
holon-json	Holon JSON objects serialization and deserialization core API
holon-gson	Base Gson configuration for PropertyBox serialization and deserialization support
holon-gson-jaxrs	JAX-RS configuration support to use Gson as JSON type messages serializer/deserializer
holon-gson-spring	Spring RestTemplate configuration and Gson Spring Boot auto-configuration
holon-jackson	Base Jackson configuration for PropertyBox serialization and deserialization support
holon-jackson-jaxrs	JAX-RS configuration support for Jackson to enable PropertyBox serialization and deserialization in JSON format
holon-jackson-spring	Spring RestTemplate configuration and ObjectMapper Spring Boot auto-configuration
holon-json-bom	Bill Of Materials
holon-json-bom-platform	Bill Of Materials with external dependencies
documentation-json	Documentation