Dataformat
Overview
Section titled “Overview”Actor4j - Core defines a small JSON abstraction in the SDK: JsonObject and JsonArray (io.actor4j.core.json), an ObjectMapper for mapping Java objects to JSON and back, and a SerializerService for binary formats (io.actor4j.core.serializer.api). The SDK itself contains no implementation and has no external dependencies. Code written against the abstraction (actors, pods, other libraries) does not depend on a specific JSON library.
actor4j-dataformat provides the implementations. Each submodule wraps one library and registers itself via java.util.ServiceLoader. Adding the dependency is enough: JsonObject.create(), JsonArray.create() and ObjectMapper.create() then find the implementation on the classpath.
| Module | Library | Provides |
|---|---|---|
actor4j-dataformat-json-jackson |
Jackson (jackson-databind, jackson-datatype-jsr310) |
JsonFactoryService, ObjectMapperService |
actor4j-dataformat-json-org |
org.json |
JsonFactoryService |
actor4j-dataformat-json-vertx |
Vert.x (vertx-core, provided) |
JsonFactoryService |
actor4j-dataformat-bson |
MongoDB bson |
JsonFactoryService, plus a SerializerService (not registered) |
actor4j-dataformat-gson |
Gson | ObjectMapperService |
actor4j-dataformat-msgpack-jackson |
MessagePack via Jackson | SerializerService (not registered) |
JsonFactoryService creates JsonObject and JsonArray instances, ObjectMapperService creates the ObjectMapper. json-jackson provides both and is the reference for the common contract. If in doubt, choose it.
Add exactly one JSON implementation, e.g. json-jackson:
<dependency> <groupId>io.actor4j</groupId> <artifactId>actor4j-dataformat-json-jackson</artifactId> <version>2.5.0</version></dependency>The other modules use the same groupId and version with their own artifactId (see the table above). For actor4j-dataformat-json-vertx, the dependency io.vertx:vertx-core is provided and must be added by the application. Mapping of records or other objects with Vert.x additionally requires jackson-databind on the classpath. Without it, a Map still works. Other objects then fail with an IllegalStateException.
JsonObject and JsonArray
Section titled “JsonObject and JsonArray”The static factory methods of the SDK delegate to the implementation found on the classpath:
JsonObject user = JsonObject.create() .put("name", "Alice") .put("age", 42) .put("tags", JsonArray.create().add("admin").add("dev"));
String json = user.encode(); // {"name":"Alice","age":42,"tags":["admin","dev"]}
JsonObject parsed = JsonObject.create(json);String name = parsed.getString("name");Integer age = parsed.getInteger("age");JsonArray tags = parsed.getJsonArray("tags");Besides a JSON string, create(Object) accepts a Map or a record (and, except with bson, other beans). JsonArray.create(List) creates an array from a list:
record Plan(String summary, int steps) {}
JsonObject plan = JsonObject.create(new Plan("p", 2)); // {"summary":"p","steps":2}JsonObject map = JsonObject.create(Map.of("k", "v"));JsonArray array = JsonArray.create(List.of(1, "two"));JsonObject.mapFrom(obj) and JsonArray.mapFrom(list) combine create and encode. getMap() and getList() return the content as plain Java collections, and underlyingImpl() returns the object of the wrapped library (e.g. a Jackson ObjectNode).
Common Contract
Section titled “Common Contract”All four JsonFactoryService implementations follow the same contract (modeled on json-jackson):
nulland missing values returnnull.put(key, null)keeps the key.- A value of the wrong type throws a
ClassCastException, e.g.getJsonObjecton a number orgetIntegeron a string. Simple values are converted to a string bygetString, and numbers are converted bygetInteger,getLongandgetDouble. - Invalid JSON throws an
IllegalArgumentException, also an unsupported type passed tocreate(Object). - Nested values are wrapped:
getValue, the iterator of aJsonArrayandgetJsonObject/getJsonArrayreturn actor4jJsonObject/JsonArrayinstances, not the types of the underlying library. JsonObject/JsonArrayinstances of another implementation are taken by their content (e.g. input,addormergeIn).toString()returns the encoded JSON, andequalscompares by content.
JsonObject.create("{\"k\":1}").getJsonObject("k"); // ClassCastExceptionJsonObject.create("{ not json"); // IllegalArgumentExceptionJsonObject.create("{}").getString("missing"); // nullOne difference remains: whether getMap() and getList() return a copy or a live view depends on the implementation (a live view with Vert.x, a copy with the others). Do not rely on either.
One Implementation on the Classpath
Section titled “One Implementation on the Classpath”The SDK uses the first implementation that java.util.ServiceLoader finds and keeps it. If several JSON modules are on the classpath, the order of the classpath decides which one is used. Put only one JSON implementation (one JsonFactoryService, one ObjectMapperService) on the classpath. json-jackson together with gson is such a conflict, because both register an ObjectMapperService.
ObjectMapper
Section titled “ObjectMapper”ObjectMapper maps Java objects to JSON and back. It is provided by json-jackson and gson. Generic types are given with a GenericType (io.actor4j.core.utils):
ObjectMapper objectMapper = ObjectMapper.create();
List<Integer> list = List.of(567, 345, 859, 34);String json = objectMapper.mapFrom(list);List<Integer> result = objectMapper.mapTo(json, new GenericType<List<Integer>>(){});
Plan plan = objectMapper.mapTo("{\"summary\":\"p\",\"steps\":2}", Plan.class);Errors (invalid JSON, wrong target type) throw an IllegalArgumentException in both implementations. Unknown properties are ignored by json-jackson. Types from java.time are written as ISO-8601 strings by both, e.g. LocalDateTime as "2026-11-16T10:15:30". gson supports java.time via its own type adapters. Without an adapter, gson cannot map other JDK types that block reflection (e.g. Optional).
Binary Formats
Section titled “Binary Formats”The SerializerService implementations of bson and msgpack-jackson are deliberately not registered with the ServiceLoader. They are created and called directly.
MessagePack encodes any object that Jackson can map. Decoding works with a Class, a GenericType or without a type (the result is then a Map, List, String, Number, Boolean or null):
import io.actor4j.dataformat.msgpack.jackson.spi.SerializerProvider;
SerializerProvider serializer = new SerializerProvider();
byte[] bytes = serializer.encode(new Plan("p", 2));Plan plan = serializer.decode(bytes, Plan.class);
List<Integer> list = serializer.decode(serializer.encode(List.of(1, 2)), new GenericType<List<Integer>>(){});The same is available as static methods in MsgPackUtils (io.actor4j.dataformat.msgpack.jackson.utils). Invalid bytes or a wrong target type throw an IllegalArgumentException.
BSON encodes JSON objects only: a JsonObject of any implementation or an org.bson.Document. It decodes to a JsonObject (also without a type) or to a Document:
import io.actor4j.dataformat.bson.spi.SerializerProvider;
SerializerProvider serializer = new SerializerProvider();
byte[] bytes = serializer.encode(JsonObject.create().put("k", "v"));JsonObject object = serializer.decode(bytes);Document document = serializer.decode(bytes, Document.class);Other values or target types throw an IllegalArgumentException. BsonUtils (io.actor4j.dataformat.bson.utils) encodes and decodes a Document directly.