Apache Johnzon

Core (stable)

<dependency>
  <groupId>org.apache.johnzon</groupId>
  <artifactId>johnzon-core</artifactId>
  <version>${johnzon.version}</version>
</dependency>

This is the implementation of the JSON-P 2.1 specification. You'll surely want to add the API as dependency too:

<dependency>
  <groupId>jakarta.json</groupId>
  <artifactId>jakarta.json-api</artifactId>
  <version>2.1.2</version>
  <scope>provided</scope> <!-- or compile if your environment doesn't provide it -->
</dependency>

Please note: The jakarta JSON-P API jar has hardcoded parsson as the default JSON-P implementation. This might cause unintended behaviour in cases where standard Java service loading is not possible.

JSON-P Strict Compliance (stable)

This has been removed with Johnzon 2.0.x, johnzon-core is now JSON-P compliant by default.

<dependency>
  <groupId>org.apache.johnzon</groupId>
  <artifactId>johnzon-jsonp-strict</artifactId>
  <version>${johnzon.version}</version>
</dependency>

This module enables to enforce a strict compliance of JsonPointer behavior on /- usage. Johnzon default implementation enables an extended usage of it for replace/remove and get operations. In that case, it will point to the last element of the array so it's easy to replace/remove or get the last element of the array. For add operation, it remains the same, aka points to the element right after the last element of the array.

This module enforces Johnzon to be JSONP compliant and fail if /- is used for anything but add.

Note that you can even customize this behavior implementing your own JsonPointerFactory and changing the ordinal value to take a highest priority.

Mapper (stable)

<dependency>
  <groupId>org.apache.johnzon</groupId>
  <artifactId>johnzon-mapper</artifactId>
  <version>${johnzon.version}</version>
</dependency>

The mapper module allows you to use the implementation you want of Json Processing specification to map Json to Object and the opposite.

final MySuperObject object = createObject();

final Mapper mapper = new MapperBuilder().build();
mapper.writeObject(object, outputStream);

final MySuperObject otherObject = mapper.readObject(inputStream, MySuperObject.class);

The mapper uses a direct java to json representation.

For instance this java bean:

public class MyModel {
  private int id;
  private String name;
  
  // getters/setters
}

will be mapped to:

{
  "id": 1234,
  "name": "Johnzon doc"
}

Note that Johnzon supports several customization either directly on the MapperBuilder of through annotations.

public class MyModel {
  @JohnzonIgnore
  private String name;
  
  // getters/setters
}

public class MyModel {
  @JohnzonIgnore(minVersion = 3)
  private String name;
  
  // getters/setters
}

public class LocalDateConverter implements Converter<LocalDate> {
    @Override
    public String toString(final LocalDate instance) {
        return instance.toString();
    }

    @Override
    public LocalDate fromString(final String text) {
        return LocalDate.parse(text);
    }
}

public class MyModel {
  @JohnzonConverter(LocalDateConverter.class)
  private LocalDate date;
  
  // getters/setters
}

public class MyModel {
  @JohnzonProperty("__date")
  private LocalDate date;
  
  // getters/setters
}

public class AnyMe {
    private String name; // Regular serialization for the known 'name' field

    /* This example uses a TreeMap to store and retrieve the other unknown
       fields for the @JohnzonAny annotated methods, but you can choose
       anything you want. Use @JohnzonIgnore to avoid exposing this as
       an actual 'unknownFields' property in JSON.
    */
    @JohnzonIgnore
    private Map<String, Object> unknownFields = new TreeMap<String, Object>();

    public String getName() {
        return name;
    }

    public void setName(final String name) {
        this.name = name;
    }

    @JohnzonAny
    public Map<String, Object> getAny() {
        return unknownFields;
    }

    @JohnzonAny
    public void handle(final String key, final Object val) {
        this.unknownFields.put(key, val);
    }
}

JAX-RS (stable)

<dependency>
  <groupId>org.apache.johnzon</groupId>
  <artifactId>johnzon-jaxrs</artifactId>
  <version>${johnzon.version}</version>
</dependency>

JAX-RS module provides two providers (and underlying MessageBodyReaders and MessageBodyWriters):

• org.apache.johnzon.jaxrs.[Wildcard]JohnzonProvider: use Johnzon Mapper to map Object to Json and the opposite
• org.apache.johnzon.jaxrs.[Wildcard]ConfigurableJohnzonProvider: same as JohnzonProvider but with setters to ease the configuration of the provider in most servers/containers
• org.apache.johnzon.jaxrs.[Wildcard]JsrProvider: allows you to use JsrArray, JsrObject (more generally JsonStructure)

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 Configuration

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:

1. Create a WEB-INF/openejb-jar.xml:

<?xml version="1.0" encoding="UTF-8"?>
<openejb-jar>
  <pojo-deployment class-name="jaxrs-application">
    <properties>
      # optional but requires to skip scanned providers if set to true
      cxf.jaxrs.skip-provider-scanning = true
      # list of providers we want
      cxf.jaxrs.providers = johnzon,org.apache.openejb.server.cxf.rs.EJBAccessExceptionMapper
    </properties>
  </pojo-deployment>
</openejb-jar>

1. Create a WEB-INF/resources.xml to define johnzon service which will be use to instantiate the provider

<?xml version="1.0" encoding="UTF-8"?>
<resources>
  <Service id="johnzon" class-name="org.apache.johnzon.jaxrs.ConfigurableJohnzonProvider">
    # 1M
    maxSize = 1048576
    bufferSize = 1048576

    # ordered attributes
    attributeOrder = $order

    # Additional types to ignore
    ignores = org.apache.cxf.jaxrs.ext.multipart.MultipartBody
  </Service>

  <Service id="order" class-name="com.company.MyAttributeSorter" />

</resources>

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.

JSON-B (JSON-B 3.0 compliant)

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:

• johnzon.use-big-decimal-for-object: true to use BigDecimal for numbers not typed (Object), false to adjust the type to the number size, true by default.
• johnzon.support-enum-container-deserialization: prevent EnumMap/EnumSet instantiation, true by default.
• johnzon.attributeOrder: Comparator instance to sort properties by name.
• johnzon.deduplicateObjects: should instances be deduplicated.
• johnzon.supportsPrivateAccess: should private constructors/methods with @JsonbCreator be used too.
• johnzon.fail-on-unknown-properties: should unmapped properties fail the mapping. Similar to jsonb.fail-on-unknown-properties.
• johnzon.readAttributeBeforeWrite: should collection be read before being written, it enables to have an “append” mode.
• johnzon.autoAdjustBuffer: should internal read buffers be autoadjusted to stay fixed.
• johnzon.serialize-value-filter: enable to set a filter to not serialize some values.
• johnzon.cdi.activated: should cdi support be active.
• johnzon.accessMode: custom access mode, note that it can disable some JSON-B feature (annotations support).
• johnzon.accessModeDelegate: delegate access mode used by JsonbAccessModel. Enables to enrich default access mode.
• johnzon.failOnMissingCreatorValues: should the mapping fail when a @JsonbCreator misses some values.
• johnzon.use-biginteger-stringadapter: Whether or not BigInteger is mapped as a string. true by default, set to false to ensure strict JSON-B 3 compliance
• johnzon.use-bigdecimal-stringadapter: Whether or not BigDecimal is mapped as a string. true by default, set to false to ensure strict JSON-B 3 compliance

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 jakarta.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`.

final JsonValueReader<Simple> reader = new JsonValueReader<>(Json.createObjectBuilder().add("value", "simple").build());
final Jsonb jsonb = getJohnzonJsonb();
final Simple simple = jsonb.fromJson(reader, SomeModel.class);

final JsonValueWriter writer = new JsonValueWriter();
final Jsonb jsonb = getJohnzonJsonb();
jsonb.toJson(object, writer);
final JsonObject jsonObject = writer.getObject();

Websocket

<dependency>
  <groupId>org.apache.johnzon</groupId>
  <artifactId>johnzon-websocket</artifactId>
  <version>${johnzon.version}</version>
</dependency>

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:

• The ones based on JSON-P (JsonObject, JsonArray, JsonStructure)
• The ones based on Johnzon Mapper

Note that if you want to control the Mapper or JSON-B instance used by decoders you can set up the associated servlet listeners:

• org.apache.johnzon.websocket.internal.mapper.MapperLocator for johnzon-mapper
• org.apache.johnzon.websocket.jsonb.JsonbLocator for JSON-B

if you write in the servlet context an attribute named org.apache.johnzon.websocket.internal.mapper.MapperLocator.mapper (it is a Supplier<Mapper>) or org.apache.johnzon.websocket.jsonb.JsonbLocator.jsonb (depending the implementation you use) it will be used instead of the default instance.

@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) {
        // ...
    }
}

@ServerEndpoint(value = "/server", encoders = JohnzonTextEncoder.class, decoders = JohnzonTextDecoder.class)
public class ServerEndpointImpl {
    @OnMessage
    public void on(final Session session, final Message message) {
        // ...
    }
}

@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);
        }
    }
}

JSON-B Extra

<dependency>
  <groupId>org.apache.johnzon</groupId>
  <artifactId>johnzon-jsonb-extras</artifactId>
  <version>${johnzon.version}</version>
</dependency>

This module provides some extension to JSON-B.

@Polymorphic.JsonChildren({
        Child1.class,
        Child2.class
})
public abstract class Root {
    public String name;
}

@Polymorphic.JsonId("first")
public class Child1 extends Root {
    public String type;
}

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;
}

JSON Schema

<dependency>
  <groupId>org.apache.johnzon</groupId>
  <artifactId>johnzon-jsonschema</artifactId>
  <version>${johnzon.version}</version>
</dependency>

This module provides a way to validate an instance against a JSON Schema.

// long live instances (@ApplicationScoped/@Singleton)
JsonObject schema = getJsonSchema();
JsonSchemaValidatorFactory factory = new JsonSchemaValidatorFactory();
JsonSchemaValidator validator = factory.newInstance(schema);

// runtime starts here
JsonObject objectToValidateAgainstSchema = getObject();
ValidatinResult result = validator.apply(objectToValidateAgainstSchema);
// if result.isSuccess, result.getErrors etc...

// end of runtime
validator.close();
factory.close();

Known limitations are (feel free to do a PR on github to add these missing features):

• Doesn't support references in the schema
• Doesn't support: dependencies, propertyNames, if/then/else, allOf/anyOf/oneOf/not, format validations

JSON Logic

<dependency>
  <groupId>org.apache.johnzon</groupId>
  <artifactId>johnzon-jsonlogic</artifactId>
  <version>${johnzon.version}</version>
</dependency>
<dependency> <!-- requires an implementation of JSON-P -->
  <groupId>org.apache.johnzon</groupId>
  <artifactId>johnzon-core</artifactId>
  <version>${johnzon.version}</version>
</dependency>

This module provides a way to execute any JSON Logic expression.

final JohnzonJsonLogic jsonLogic = new JohnzonJsonLogic();
final JsonValue result = jsonLogic.apply(
        builderFactory.createObjectBuilder()
                .add("merge", builderFactory.createArrayBuilder()
                        .add(builderFactory.createArrayBuilder()
                                .add(1)
                                .add(2))
                        .add(3)
                        .add("4"))
                .build(),
        JsonValue.EMPTY_JSON_ARRAY);

Default operators are supported - except “log” one to let you pick the logger (impl + name) you want.

To register a custom operator just do it on your json logic instance:

final JohnzonJsonLogic jsonLogic = new JohnzonJsonLogic();
jsonLogic.registerOperator(
  "log",
  (jsonLogic, config, args) -> log.info(String.valueOf(jsonLogic.apply(config, args)));

Note that by default the set of standard JSON Logic operators is enriched with JSON-P jsonpatch, json merge diff and json merge patch operators.

OSGi JAX-RS Whiteboard

Though Johnzon artifacts are OSGi bundles to begin with, this module provides further integration with the OSGi JAX-RS Whiteboard and OSGi CDI Integration specifications.