Apache Johnzon is a project providing an implementation of JsonProcessing (aka JSR-353) and a set of useful extension for this specification like an Object mapper, some JAX-RS providers and a WebSocket module provides a basic integration with Java WebSocket API (JSR-356).
Apache Johnzon is a Top Level Project at the Apache Software Foundation (ASF). It fully implements the JSON-P_1.1 (JSR-353) and JSON-B_1.0 (JSR-367) specifications.
Johnzon comes with four main modules.
This is the implementation of the JSON-P 1.1 specification. You'll surely want to add the API as dependency too:
The mapper module allows you to use the implementation you want of Json Processing specification to map Json to Object and the opposite.
The mapper uses a direct java to json representation.
For instance this java bean:
will be mapped to:
Note that Johnzon supports several customization either directly on the MapperBuilder of through annotations.
@JohnzonIgnore is used to ignore a field. You can optionally say you ignore the field until some version if the mapper has a version:
Or to support name for version 3, 4, ... but ignore it for 1 and 2:
Converters are used for advanced mapping between java and json.
There are several converter types:
The most common is to customize date format but they all take. For that simple case we often use a Converter:
If you need a more advanced use case and modify the structure of the json (wrapping the value for instance) you will likely need Reader/Writer or a Codec.
Then once your converter developed you can either register globally on the MapperBuilder or simply decorate the field you want to convert with @JohnzonConverter:
Sometimes the json name is not java friendly (_foo or foo-bar or even 200 for instance). For that cases @JohnzonProperty allows to customize the name used:
If you don't fully know your model but want to handle all keys you can use @JohnzonAny to capture/serialize them all:
On MapperBuilder you have several AccessMode available by default but you can also create your own one.
The default available names are:
You can use these names with setAccessModeName().
JAX-RS module provides two providers (and underlying MessageBodyReaders and MessageBodyWriters):
Note: Wildcard providers are basically the same as other provider but instead of application/json they support */json, /+json, */x-json, */javascript, */x-javascript. This split makes it easier to mix json and other MediaType in the same resource (like text/plain, xml etc since JAX-RS API always matches as true wildcard type in some version whatever the subtype is).
Tip: ConfigurableJohnzonProvider maps most of MapperBuilder configuration letting you configure it through any IoC including not programming language based formats.
IMPORTANT: when used with johnzon-core, NoContentException is not thrown in case of an empty incoming input stream by these providers except JsrProvider to limit the breaking changes.
TomEE uses by default Johnzon as JAX-RS provider for versions 7.x. If you want however to customize it you need to follow this procedure:
Note: as you can see you mainly just need to define a service with the id johnzon (same as in openejb-jar.xml) and you can reference other instances using $id for services and @id for resources.
Johnzon provides a module johnzon-jsonb implementing JSON-B standard based on Johnzon Mapper.
It fully reuses the JSON-B as API.
However it supports some specific properties to wire to the native johnzon configuration - see JohnzonBuilder for details. One example is johnzon.interfaceImplementationMapping which will support a Map<Class,Class> to map interfaces to implementations to use for deserialization.
JsonbConfig specific properties:
TIP: more in JohnzonBuilder class.
A JAX-RS provider based on JSON-B is provided in the module as well. It is org.apache.johnzon.jaxrs.jsonb.jaxrs.JsonbJaxrsProvider.
IMPORTANT: in JAX-RS 1.0 the provider can throw any exception he wants for an empty incoming stream on reader side. This had been broken in JAX-RS 2.x where it must throw a javax.ws.rs.core.NoContentException. To ensure you can pick the implementation you can and limit the breaking changes, you can set ̀throwNoContentExceptionOnEmptyStreamson the provider to switch between both behaviors. Default will be picked from the current available API. Finally, this behavior only works withjohnzon-core`.
JsonValueYou can use some optimization to map a JsonObject to a POJO using Johnzon JsonValueReader and JsonValueWriter:
These two example will not use any IO and directly map the JsonValue to/from a POJO.
Also note that, as an experimental extension and pre-available feature of the next specification version, org.apache.johnzon.jsonb.api.experimental.JsonbExtension enables to map POJO to JsonValue and the opposite.
WebSocket module provides a basic integration with Java WebSocket API (JSR 356).
Integration is at codec level (encoder/decoder). There are two families of codecs:
Encoders:
org.apache.johnzon.websocket.jsr.JsrObjectEncoderorg.apache.johnzon.websocket.jsr.JsrArrayEncoderorg.apache.johnzon.websocket.jsr.JsrStructureEncoderDecoders:
org.apache.johnzon.websocket.jsr.JsrObjectDecoderorg.apache.johnzon.websocket.jsr.JsrArrayDecoderorg.apache.johnzon.websocket.jsr.JsrStructureDecoderEncoder:
org.apache.johnzon.websocket.mapper.JohnzonTextEncoderDecoder:
org.apache.johnzon.websocket.mapper.JohnzonTextDecoderOn server and client side configuration is easy: just provide the encoders and decoders parameters to @[Server|Client]Endpoint (or EndpointConfig if you use programmatic API)):
@ClientEndpoint(encoders = JsrObjectEncoder.class, decoders = JsrObjectDecoder.class)
public class JsrClientEndpointImpl {
@OnMessage
public void on(final JsonObject message) {
// ...
}
}
@ServerEndpoint(value = "/my-server", encoders = JsrObjectEncoder.class, decoders = JsrObjectDecoder.class)
public class JsrClientEndpointImpl {
@OnMessage
public void on(final JsonObject message) {
// ...
}
}
Server configuration is as simple as providing encoders and decoders parameters to @ServerEndpoint:
@ServerEndpoint(value = "/server", encoders = JohnzonTextEncoder.class, decoders = JohnzonTextDecoder.class)
public class ServerEndpointImpl {
@OnMessage
public void on(final Session session, final Message message) {
// ...
}
}
Client configuration is almost the same excepted in this case it is not possible for Johnzon to guess the type you expect so you'll need to provide it. In next sample it is done just extending JohnzonTextDecoder in MessageDecoder.
@ClientEndpoint(encoders = JohnzonTextEncoder.class, decoders = ClientEndpointImpl.MessageDecoder.class)
public class ClientEndpointImpl {
@OnMessage
public void on(final Message message) {
// ...
}
public static class MessageDecoder extends JohnzonTextDecoder {
public MessageDecoder() {
super(Message.class);
}
}
}
This module provides some extension to JSON-B.
This extension provides a way to handle polymorphism:
For the deserialization side you have to list the potential children on the root class:
@Polymorphic.JsonChildren({
Child1.class,
Child2.class
})
public abstract class Root {
public String name;
}
Then on children you bind an “id” for each of them (note that if you don't give one, the simple name is used):
@Polymorphic.JsonId("first")
public class Child1 extends Root {
public String type;
}
Finally on the field using the root type (polymorphic type) you can bind the corresponding serializer and/or deserializer:
public class Wrapper {
@JsonbTypeSerializer(Polymorphic.Serializer.class)
@JsonbTypeDeserializer(Polymorphic.DeSerializer.class)
public Root root;
@JsonbTypeSerializer(Polymorphic.Serializer.class)
@JsonbTypeDeserializer(Polymorphic.DeSerializer.class)
public List<Root> roots;
}
Binding the polymophic serializer and/or deserializer must not be done using JsonbConfig.withSerializers / JsonbConfig.withDeserializers, as it is designed to work only with binding performed using annotations.
This module provides a way to validate an instance against a JSON Schema.
Known limitations are (feel free to do a PR on github to add these missing features):