mmm-marshall

API for marshalling and unmarshalling data.

License

License

GroupId

GroupId

io.github.m-m-m
ArtifactId

ArtifactId

mmm-marshall
Last Version

Last Version

0.2.0
Release Date

Release Date

Type

Type

jar
Description

Description

mmm-marshall
API for marshalling and unmarshalling data.
Project URL

Project URL

https://m-m-m.github.io/
Project Organization

Project Organization

mmm-team
Source Code Management

Source Code Management

https://github.com/m-m-m/marshal/tree/master

Download mmm-marshall

How to add to project

<!-- https://jarcasting.com/artifacts/io.github.m-m-m/mmm-marshall/ -->
<dependency>
    <groupId>io.github.m-m-m</groupId>
    <artifactId>mmm-marshall</artifactId>
    <version>0.2.0</version>
</dependency>
// https://jarcasting.com/artifacts/io.github.m-m-m/mmm-marshall/
implementation 'io.github.m-m-m:mmm-marshall:0.2.0'
// https://jarcasting.com/artifacts/io.github.m-m-m/mmm-marshall/
implementation ("io.github.m-m-m:mmm-marshall:0.2.0")
'io.github.m-m-m:mmm-marshall:jar:0.2.0'
<dependency org="io.github.m-m-m" name="mmm-marshall" rev="0.2.0">
  <artifact name="mmm-marshall" type="jar" />
</dependency>
@Grapes(
@Grab(group='io.github.m-m-m', module='mmm-marshall', version='0.2.0')
)
libraryDependencies += "io.github.m-m-m" % "mmm-marshall" % "0.2.0"
[io.github.m-m-m/mmm-marshall "0.2.0"]

Dependencies

compile (1)

Group / Artifact Type Version
io.github.m-m-m : mmm-base jar 0.2.0

Project Modules

There are no modules declared in this project.

logo

Apache License, Version 2.0 Build Status

mmm-marshall

Maven Central base JavaDoc

The module io.github.mmm.marshall (artifactId mmm-marshall) provides the API to marshall (serialize) and unmarshall (deserialize) data from/to structured formats such as JSON, XML, YAML, or even ProtoBuf (gRPC) without implementing your mapping code for multiple formats.

Problem

When you want to do (un)marshalling with Java EE standards the current state is:

As a result you implement your marshalling and unmarshalling code for a single format. If you want to support a different format, you have to start from scratch. Further, the reference implementation for JSON-P is lacking obvious features. E.g. the indentation is hardcoded as you can see here. You can also not configure to include or omit null values. Also, there is no build in support to skip a value and doing so requires an awful lot of code (in case the value might contain nested arrays and/or objects).

Solution

So instead we define a universal API for (un)marshalling. You can write your mapping code once and then you can benefit from all formats supported by this project or even add custom formats as plugin yourself.

Features

  • Simple but powerful API to marshall and unmarshall your data in a format agnostic way.

  • Configurable indendation

  • Configuration to omit null values

  • Works in JVM as well as in the browser using TeaVM or as cloud-native binary using GraalVM.

  • You can even use mmm-bean to get the entire marshalling and unmarshalling for free with many other cool features.

  • You can furhter use mmm-rpc to implement client and/or server for RCP communication with minimum code but maximum benefits (support for different formats, sync/async/reactive support, etc.).

We provide the following implementations:

Usage

Maven Dependency:

<dependency>
  <groupId>io.github.m-m-m</groupId>
  <artifactId>mmm-marshall</artifactId>
  <!-- <version>${mmmVersion}</version> -->
</dependency>

Gradle Dependency:

implementation 'io.github.m-m-m:mmm-marshall:${mmmVersion}'

For ${mmmVersion} please fill in the latest version that you can find in the badge above.

Module Dependency:

  requires transitive io.github.mmm.marshall;

Example

To get started we use a very simple example based on a stupid POJO that every vanilla Java developer will immediately understand. Please note that we provide much better beans with build-in marshalling support via mmm-bean. However, here comes our stupid example:

public class Person {
  private String name;
  private int age;
  public String getName() { return this.name; }
  public void setName(String name) { this.name = name; }
  public int getAge() { return this.age; }
  public void setAge(int age) { this.age = age; }
}

Now, we can marshall a Person like this:

public void marshall(StructuredWriter writer, Person person) {
  writer.writeStartObject();
  writer.writeName("name", 1);
  writer.writeValue(person.getName());
  writer.writeName("age", 2);
  writer.writeValue(person.getAge());
  writer.writeEnd();
}

Now we run the following code:

Person person = new Person();
person.setName("John Doe");
person.satAge(42);
StringBuilder sb = new StringBuilder();
StructuredWriter writer = JsonFormat.of().writer(sb);
marshall(writer, person);
System.out.println(sb.toString());

This will print the following output:

{
  "name": "John Doe",
  "age": 42
}

The interesting fact is that you can exchange JsonFormat.of() with something else to get a different format without changing your implementation of marshal. So you can also use XmlFormat.of() to produce XML or you can generate YAML or even gRPC/ProtoBuf.

To unmarhall a Person you can do something like this:

public void unmarshall(StructuredReader reader, Person person) {
  while (!reader.readEnd()) {
    if (reader.isName("name", 1)) {
      person.setName(reader.readValueAsString());
    } else if (reader.isName("age", 2)) {
      person.setAge(reader.readValueAsInteger());
    } else {
      // ignore unknown property for compatibility
      // we have dynamic properties support in mmm-bean
      // even much better than gRPC generated unknownFields
    }
  }
}
io.github.m-m-m

Marvelous-Micro-Modules

Versions

Version
0.2.0
0.1.1
0.1.0