Quarkus Fory

Integrates with the Apache Fory serialization framework. Apache Fory is a blazingly fast multi-language serialization framework powered by JIT and zero-copy. With the quarkus-fory extension, users can use fast and easy-to-use serialization feature provided by Apache Fory out-of-box.

Installation

If you want to use this extension, you need to add the io.quarkiverse.fory:quarkus-fory extension first to your build file.

For instance, with Maven, add the following dependency to your POM file:

<dependency>
    <groupId>io.quarkiverse.fory</groupId>
    <artifactId>quarkus-fory</artifactId>
    <version>0.4.0</version>
</dependency>

Usage

If you want to use Apache Fory to serialize your objects, you need to use @Inject to get an instance of Fory to serialize your objects. Fory instance is created by quarkus-fory at build time, you don’t need to create Fory by yourself. And you also need to mark your classes for serialization.

For instance, the following code is an example using @Inject and @ForySerialization annotation to serialize a JDK 17+ record object.

import java.util.List;
import java.util.Map;

import io.quarkiverse.fory.ForySerialization;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

import org.apache.fory.BaseFory;

@ForySerialization
record Foo(int f1, String f2, List<String> f3, Map<String, Long> f4) {
}

@Path("/fory")
@ApplicationScoped
public class ForyResources {
  @Inject
  BaseFory fory;

  @GET
  @Path("/record")
  public Boolean testSerializeFooRecord() {
    Foo foo1 = new Foo(10, "abc", List.of("str1", "str2"), Map.of("k1", 10L, "k2", 20L));
    Foo foo2 = (Foo) fory.deserialize(fory.serialize(foo1));
    return foo1.equals(foo2);
  }
}

You can also mark a class for serialization by application.properties configurations.

quarkus.fory.register-class-names=io.demo.Foo,io.demo.Bar

If you want to specify class id or serializer for a class, you can do it by annotation:

import io.quarkiverse.fory.ForySerialization;

@ForySerialization(classId = 200, serializer = FooSerializer.class)
record Foo(int f1, String f2, List<String> f3, Map<String, Long> f4) {
}

If the class is a third-party class which you can’t add annotation, you can specify the targetClasses property:

import io.quarkiverse.fory.ForySerialization;

@ForySerialization(classId = 200, serializer = FooSerializer.class, targetClasses = Foo.class)
public class FooConfig {
}

Or you can configure by application.properties configurations.

quarkus.fory.register-class."io.demo.Foo".class-id=200
quarkus.fory.register-class."io.demo.Foo".serializer=io.demo.FooSerializer

For about how to create a customized Fory serializer for a class, see Apache Fory document

Integartion in Quarkus REST/RESTEasy

It enables efficient and structured data exchange between client and server using the fory during serialization and deserialization with application/fory media type. Example for a JAX-RS endpoint on the server side like:

@Path("/example")
@Produces("application/fory")
@Consumes("application/fory")
public class ExampleResource {
    @POST
    public Foo test(Foo obj) {
       return new Foo(1, "test");
    }
}
If class registration is enabled, the class ID (or serialization identifier) must be identical on both the client and server sides. A mismatch in the class ID will result in serialization or deserialization issues, potentially causing runtime errors or data corruption. If class registration is disabled, please do not assign class id at client and server slides.

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.fory.language

The language of fory. The default is JAVA.

Environment variable: QUARKUS_FORY_LANGUAGE

java, xlang

java

quarkus.fory.required-class-registration

Require class registration for serialization. The default is true.

Environment variable: QUARKUS_FORY_REQUIRED_CLASS_REGISTRATION

boolean

true

quarkus.fory.track-ref

Whether track shared or circular references.

Environment variable: QUARKUS_FORY_TRACK_REF

boolean

false

quarkus.fory.compatible-mode

Set class schema compatible mode.
SCHEMA_CONSISTENT: Class schema must be consistent between serialization peer and deserialization peer.
COMPATIBLE: Class schema can be different between serialization peer and deserialization peer. They can add/delete fields independently.

Environment variable: QUARKUS_FORY_COMPATIBLE_MODE

schema-consistent, compatible

schema-consistent

quarkus.fory.compress-number

Use variable length encoding for int/long.

Environment variable: QUARKUS_FORY_COMPRESS_NUMBER

boolean

true

quarkus.fory.compress-string

Whether compress string for small size.

Environment variable: QUARKUS_FORY_COMPRESS_STRING

boolean

true

quarkus.fory.deserialize-nonexistent-class

Whether deserialize/skip data of un-existed class. If not enabled, an exception will be thrown if class not exist.

Environment variable: QUARKUS_FORY_DESERIALIZE_NONEXISTENT_CLASS

boolean

false

quarkus.fory.deserialize-nonexistent-enum-value-as-null

If an enum value doesn’t exist, return a null instead of throws exception.

Environment variable: QUARKUS_FORY_DESERIALIZE_NONEXISTENT_ENUM_VALUE_AS_NULL

boolean

false

quarkus.fory.thread-safe

Whether to use thread safe fory. The default is true.

Environment variable: QUARKUS_FORY_THREAD_SAFE

boolean

true

quarkus.fory.register-class-names

Names of classes to register which no need to be with class-id or customize serializer. It has to be separated by comma.

Environment variable: QUARKUS_FORY_REGISTER_CLASS_NAMES

string

Configurations of register class

Type

Default

quarkus.fory.register-class."register-class-name".class-id

Class id must be greater or equal to 256, and it must be different between classes. The default is -1.

Environment variable: QUARKUS_FORY_REGISTER_CLASS__REGISTER_CLASS_NAME__CLASS_ID

int

-1

quarkus.fory.register-class."register-class-name".serializer

Specify a customized serializer for current class. This should be empty to let Fory create serializer for current class. But if users want to customize serialization for this class, one can provide serializer here.

Environment variable: QUARKUS_FORY_REGISTER_CLASS__REGISTER_CLASS_NAME__SERIALIZER

string