Marshalling

To support multiple data interchange formats like JSON, XML, YAML, etc., MapMaid does not work directly on strings. Instead, objects are serialized and deserialized to and from nested maps (Map<String, Object>). This Map<String, Object can then be easily converted into any data interchange format of choice. This map is respectively deserialized from a specific format or serialized into that format. The process of serializing that map into a format is what we call Marshalling and the reverse operation Unmarshalling. Examples of frameworks that can perform this operation include Gson, Jackson and X-Stream.

MapMaid is unaware of the format you chose to represent the string value of your objects. Upon reception of the string input, MapMaid first asks the configured (un-)marshaller to parse the String into a Map<String, Object>. From now on, it operates with that Map<String, Object> by mapping its structure onto the pre-calculated object hierarchy of the class to be deserialized.

Vice versa, the process is reversed on serialization. MapMaid will take the object to be serialized and deconstructs its object hierarchy into a Map<String, Object>. This map is then passed on to the configured marshaller which will transform it into a String of the chosen format (JSON, XML, etc.).

Common marshallers

MapMaid ships with integrated marshallers for the common formats JSON and YAML as well as the so-called x-www-form-urlencoded (url-encoded) format used in the HTTP protocol. It also ships with a marshaller that is specific to the AWS DynamoDB database (see below).

Pre-configured marshaller

MapMaid comes pre-configured with a marshaller for JSON. They will be automatically deregistered once you manually register a marshaller. Alternatively, you can deactivate the pre-configured marshaller like this:

final MapMaid mapMaid = MapMaid.aMapMaid()
        .withAdvancedSettings(AdvancedBuilder::doNotAutoloadMarshallers)
        .build();

You can manually configure the default JSON marshaller like this:

final MapMaid mapMaid = aMapMaid()
        .withAdvancedSettings(advancedBuilder ->
                advancedBuilder.usingMarshaller(MinimalJsonMarshallerAndUnmarshaller.minimalJsonMarshallerAndUnmarshaller()))
        .withAdvancedSettings(AdvancedBuilder::doNotAutoloadMarshallers)
        .build();

YAML

In order to support YAML, you need to add this dependency to your project:

<dependency>
    <groupId>de.quantummaid.mapmaid.integrations</groupId>
    <artifactId>mapmaid-snakeyaml</artifactId>
    <version>0.10.18</version>
</dependency>

YAML marshalling and unmarshalling can then be configured like this:

final MapMaid mapMaid = aMapMaid()
        .withAdvancedSettings(advancedBuilder ->
                advancedBuilder.usingMarshaller(SnakeYamlMarshallerAndUnmarshaller.snakeYamlMarshallerAndUnmarshaller()))
        .withAdvancedSettings(AdvancedBuilder::doNotAutoloadMarshallers)
        .build();

application/x-www-form-urlencoded

MapMaid’s url-encoded marshaller can be added to your configuration like this:

final MapMaid mapMaid = MapMaid.aMapMaid()
        .usingRecipe(UrlEncodedMarshallerRecipe.urlEncodedMarshaller())
        .build();

In order to use it, you need to use the corresponding MarshallingType:

final String urlEncoded = mapMaid.serializeTo(object, urlEncoded());

AWS DynamoDB AttributeValue

MapMaid is able to marshal and unmarshal software.amazon.awssdk.services.dynamodb.model.AttributeValue data structures that are used in the AWS DynamoDB SDK. To use it, add the following dependency:

<dependency>
    <groupId>de.quantummaid.mapmaid.integrations</groupId>
    <artifactId>mapmaid-dynamodb</artifactId>
    <version>0.10.18</version>
</dependency>

Configuration:

final MapMaid mapMaid = MapMaid.aMapMaid()
        .serializingAndDeserializing(ComplexPerson.class)
        .withAdvancedSettings(advancedBuilder -> advancedBuilder.usingMarshaller(AttributeValueMarshallerAndUnmarshaller.attributeValueMarshallerAndUnmarshaller()))
        .build();

Serialization:

final AttributeValue attributeValue = mapMaid.serializeTo(object, AttributeValueMarshallerAndUnmarshaller.DYNAMODB_ATTRIBUTEVALUE);

Deserialization:

final ComplexPerson deserialized = mapMaid.deserialize(attributeValue, ComplexPerson.class, AttributeValueMarshallerAndUnmarshaller.DYNAMODB_ATTRIBUTEVALUE);

Registering your own marshaller

If these marshallers do not fit your needs, you can easily provide your own by implementing the Marshaller and Unmarshaller interfaces. In this section, we show the registration of some commonly used marshalling libraries.

JSON with GSON

Assuming you have a configured instance of Gson class, adding it as a JSON marshaller for MapMaid looks like:

final Gson gson = new Gson(); // can be further configured depending on your needs.
final MapMaid mapMaid = MapMaid.aMapMaid()
        .serializingAndDeserializing(ComplexPerson.class)
        .withAdvancedSettings(advancedBuilder -> advancedBuilder.usingJsonMarshaller(gson::toJson, input -> gson.fromJson(input, Object.class)))
        .build();

JSON with ObjectMapper

final ObjectMapper objectMapper = new ObjectMapper();
final MapMaid mapMaid = MapMaid.aMapMaid()
        .serializingAndDeserializing(ComplexPerson.class)
        .withAdvancedSettings(advancedBuilder -> advancedBuilder.usingJsonMarshaller(objectMapper::writeValueAsString, input -> objectMapper.readValue(input, Object.class)))
        .build();

XML with X-Stream

final XStream xStream = new XStream(new DomDriver());
xStream.alias("root", Map.class);

final MapMaid mapMaid = MapMaid.aMapMaid()
        .serializingAndDeserializing(ComplexPerson.class)
        .withAdvancedSettings(advancedBuilder -> advancedBuilder.usingXmlMarshaller(xStream::toXML, xStream::fromXML))
        .build();

Note: If you wish to marshall in/from XML, don’t forget to add the appropriate dependency:

<dependency>
    <groupId>xstream</groupId>
    <artifactId>xstream</artifactId>
    <version>${xstream.version}</version>
</dependency>

YAML with ObjectMapper

final ObjectMapper objectMapper = new ObjectMapper(new YAMLFactory());

final MapMaid mapMaid = MapMaid.aMapMaid()
        .serializingAndDeserializing(ComplexPerson.class)
        .withAdvancedSettings(advancedBuilder -> advancedBuilder.usingYamlMarshaller(objectMapper::writeValueAsString, input -> {
            return objectMapper.readValue(input, Object.class);
        }))
        .build();

Note: Don’t forget to add the appropriate dependency to use the YAMLFactory with the ObjectMapper.

<dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-yaml</artifactId>
    <version>${jackson.version}</version>
</dependency>

MapMaid does not ship with these libraries, so you need to configure the marshaller of your choice also in the dependencies of your project.

Exception Handling
Primitive inlining