Camel Components

TOON

Since Camel 4.23

The TOON data format marshals JSON-compatible Java values to TOON (Token-Oriented Object Notation) and unmarshals TOON text back to a Java object graph.

TOON is a compact, human-readable encoding of the JSON data model. It is designed as an alternative textual representation of JSON values rather than as a general-purpose serialization format. This Camel data format is a Preview component for Camel 4.23.x.

The implementation uses the official Java library JToon. Camel does not implement a TOON parser or encoder of its own.

TOON Options

The TOON dataformat supports the following options which are listed below.

Name Default Java Type Description

indent (common)

2

Integer

Number of spaces per indentation level.

delimiter (common)

COMMA

Enum

Delimiter used for tabular array rows and inline primitive arrays.

Enum values:

  • COMMA

  • TAB

  • PIPE

strict (common)

true

Boolean

Whether to enable strict validation when unmarshalling TOON. When false, the decoder applies the non-strict recoveries of the TOON specification, such as accepting an array whose length differs from the declared length; other malformed TOON still fails.

contentTypeHeader (common)

true

Boolean

Whether the data format should set the Content-Type header to text/toon when marshalling.

Message Body

The message body at each side of the TOON data format: Marshal input and Unmarshal input are the bodies marshal and unmarshal can take, and Marshal output and Unmarshal output the body after them.

Side Body Description

Marshal input

text, bytes, stream, file, value, map, list or pojo

A Map, a List, a POJO or a value to write as TOON. A String, bytes, a stream or a file must be JSON text, read in the charset of the exchange.

Marshal output

stream, as text

The TOON in the stream cache, or a byte array when stream caching is off.

Unmarshal input

text, bytes, stream or file, as text

Unmarshal output

map or list

A Map (LinkedHashMap) for an object, a List for an array; a document that is a single value gives that value.

The bodies are the ones with the default options. A side that is not listed is not known, and tooling does not guess it. The carriers are described in the Camel Catalog.

Marshal behavior

Marshalling converts a JSON-compatible message body to TOON text:

  • Map, List, POJOs, numbers, booleans, and null are encoded with JToon encode.

  • A Java String body is always treated as a JSON document and encoded with JToon encodeJson. This is the path to use when transforming existing JSON text to TOON.

  • A byte[], an InputStream or a file (java.io.File, or the file of a file consumer) holds JSON text as well: it is read in the exchange charset and encoded as a String body is.

A plain (non-JSON) String such as hello world is not encoded as a TOON string scalar. JToon rejects it with IllegalArgumentException. To marshal a Java string as a TOON scalar, wrap it in a List or Map, or use a typed Java value rather than a raw String body.

The output charset follows Camel’s exchange charset (ExchangeHelper.getCharsetName(exchange)). When contentTypeHeader is enabled (the default), marshalling sets the Content-Type header to text/toon. That media type is provisional in the TOON specification.

Unmarshal behavior

Unmarshalling decodes TOON text with JToon decode and returns a Java JSON-compatible object graph. Typical results are:

  • Map for objects

  • List for arrays

  • String, Long, Double, Boolean, or null for scalars

JToon may decode whole numbers as Long rather than Integer. Malformed TOON fails with the exception thrown by JToon; Camel does not swallow parse errors.

Usage

Marshalling (Java object to TOON)

  • Java

  • XML

  • YAML

from("direct:marshal")
    .marshal().toon()
    .to("mock:toon");
<route>
  <from uri="direct:marshal"/>
  <marshal>
    <toon/>
  </marshal>
  <to uri="mock:toon"/>
</route>
- route:
    from:
      uri: direct:marshal
      steps:
        - marshal:
            toon: {}
        - to:
            uri: mock:toon

Unmarshalling (TOON to Java object)

  • Java

  • XML

  • YAML

from("direct:unmarshal")
    .unmarshal().toon()
    .to("mock:json");
<route>
  <from uri="direct:unmarshal"/>
  <unmarshal>
    <toon/>
  </unmarshal>
  <to uri="mock:json"/>
</route>
- route:
    from:
      uri: direct:unmarshal
      steps:
        - unmarshal:
            toon: {}
        - to:
            uri: mock:json

JSON document to TOON

A String body that contains JSON is parsed as JSON and encoded as TOON:

from("direct:jsonToToon")
    .marshal().toon();

For example, the JSON document {"id":1,"name":"Ada"} is marshalled to TOON object syntax rather than being encoded as a quoted TOON string scalar. A String body that is not valid JSON fails rather than becoming a TOON scalar.

TOON to Java object

from("direct:toonToObject")
    .unmarshal().toon()
    .process(exchange -> {
        Object graph = exchange.getMessage().getBody();
        // typically a Map, List, or JSON scalar
    });

Dependencies

Maven users need to add the following dependency:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-toon</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>