ArangoDB v3.10 reached End of Life (EOL) and is no longer supported.
This documentation is outdated. Please see the most recent stable version.
Serialization (version 6)
Serialization (version 6)
While older versions of the driver used mapping features provided by the
velocypack
library, nowadays it is recommended to use
jackson-dataformat-velocypack ,
which is a VelocyPack dataformat backend for Jackson ,
supporting the Streaming, Data Binding and Tree Model API styles.
Import in Maven
To add it to your Maven project, add the following to pom.xml
:
<dependencies>
<dependency>
<groupId>com.arangodb</groupId>
<artifactId>jackson-dataformat-velocypack</artifactId>
<version>...</version>
</dependency>
</dependencies>
The package also depends on jackson-core
, jackson-databind
and
jackson-annotations
packages, but when using build tools like Maven or
Gradle, dependencies are automatically included. You may however want to
use jackson-bom
to ensure dependency convergence across the entire project, for example in case
there are in your project other libraries depending on different versions of
the same Jackson packages.
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.fasterxml.jackson</groupId>
<artifactId>jackson-bom</artifactId>
<version>...</version>
<scope>import</scope>
<type>pom</type>
</dependency>
</dependencies>
</dependencyManagement>
jackson-dataformat-velocypack
is compatible with Jackson 2.10, 2.11, 2.12, and 2.13.
Configure
Create an instance of ArangoJack
, optionally configure the underlying
ObjectMapper
and pass it to the driver through
ArangoDB.Builder.serializer(ArangoSerialization)
:
ArangoJack arangoJack = new ArangoJack();
arangoJack.configure((mapper) -> {
// your configuration here
});
ArangoDB arango = new ArangoDB.Builder()
.serializer(arangoJack)
// ...
.build();
where the lambda argument mapper
is an instance of VPackMapper
, subclass
of ObjectMapper
. See
Jackson Databind
configurable features.
Mapping API
The library is fully compatible with Jackson Databind API. To customize the serialization and deserialization behavior using the Jackson Data Binding API, entities can be annotated with Jackson Annotations . For more advanced customizations refer to Custom serializer section.
Renaming Properties
To use a different serialized name for a field, use the annotation
@JsonProperty
.
public class MyObject {
@JsonProperty("title")
private String name;
// ...
}
Ignoring properties
To ignore fields use the annotation @JsonIgnore
.
public class Value {
@JsonIgnore
public int internalValue;
}
Custom serializer
The serialization and deserialization can be customized using the lower level
Streaming API or the Tree Model API, creating and registering respectively
JsonSerializer<T>
and JsonDeserializer<T>
, as specified by the Jackson API
for CustomSerializers .
static class PersonSerializer extends JsonSerializer<Person> {
@Override
public void serialize(Person value, JsonGenerator gen, SerializerProvider serializers) throws IOException {
// example using the Streaming API
gen.writeStartObject();
gen.writeFieldName("name");
gen.writeString(value.name);
gen.writeEndObject();
}
}
static class PersonDeserializer extends JsonDeserializer<Person> {
@Override
public Person deserialize(JsonParser parser, DeserializationContext ctxt) throws IOException {
// example using the Tree Model API
Person person = new Person();
JsonNode rootNode = parser.getCodec().readTree(parser);
JsonNode nameNode = rootNode.get("name");
if (nameNode != null && nameNode.isTextual()) {
person.name = nameNode.asText();
}
return person;
}
}
// registering using annotation
@JsonSerialize(using = PersonSerializer.class)
public static class Person {
public String name;
}
// ...
// registering programmatically
ArangoJack arangoJack = new ArangoJack();
arangoJack.configure((mapper) -> {
SimpleModule module = new SimpleModule("PersonModule");
module.addDeserializer(Person.class, new PersonDeserializer());
mapper.registerModule(module);
});
ArangoDB arangoDB = new ArangoDB.Builder().serializer(arangoJack).build();
Jackson datatype and language modules
The VPackMapper
can be configured
with Jackson datatype modules
as well as Jackson JVM Language modules .
Kotlin
Kotlin language module enables support for Kotlin native types and can be registered in the following way:
val arangoDB = ArangoDB.Builder()
.serializer(ArangoJack().apply {
configure { it.registerModule(KotlinModule()) }
})
.build()
Scala
Scala language module enables support for Scala native types and can be registered in the following way:
val arangoJack = new ArangoJack()
arangoJack.configure(mapper => mapper.registerModule(DefaultScalaModule))
val arangoDB = new ArangoDB.Builder()
.serializer(arangoJack)
.build()
Java 8 types
Support for Java 8 features is offered by jackson-modules-java8 .
Joda types
Support for Joda data types, such as DateTime, is offered by jackson-datatype-joda .
Metadata fields
To map Arango metadata fields (like _id
, _key
, _rev
, _from
, _to
) in
your entities, use the annotation DocumentField
.
public class MyObject {
@DocumentField(Type.KEY)
private String key;
// ...
}
Manual serialization
To de-/serialize from and to VelocyPack before or after a database call, use the
ArangoUtil
from the method util()
in ArangoDB
, ArangoDatabase
,
ArangoCollection
, ArangoGraph
, ArangoEdgeCollection
or ArangoVertexCollection
.
ArangoDB arangoDB=new ArangoDB.Builder();
VPackSlice vpack=arangoDB.util(CUSTOM).serialize(myObj);
ArangoDB arangoDB=new ArangoDB.Builder();
MyObject myObj=arangoDB.util(CUSTOM).deserialize(vpack,MyObject.class);