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.0 specification (JSR-353). Johnzon also targets the upcoming JSON-P_1.1 and JSON-B_1.0 specifications.
Johnzon comes with four main modules.
This is the implementation of the 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 you 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.
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 and jsonb-api implementing JSON-B standard based on Johnzon Mapper.
It fully reuses the JSON-B as API.
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.JsrObjectEncoder
org.apache.johnzon.websocket.jsr.JsrArrayEncoder
org.apache.johnzon.websocket.jsr.JsrStructureEncoder
Decoders:
org.apache.johnzon.websocket.jsr.JsrObjectDecoder
org.apache.johnzon.websocket.jsr.JsrArrayDecoder
org.apache.johnzon.websocket.jsr.JsrStructureDecoder
Encoder:
org.apache.johnzon.websocket.mapper.JohnzonTextEncoder
Decoder:
org.apache.johnzon.websocket.mapper.JohnzonTextDecoder
On 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); } } }
We would like to thank ej-technologies for their Java profiler JProfiler which helped us a lot optimizing memory footprint and speed.