Quarkus Fury

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

Installation

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

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

<dependency>
    <groupId>io.quarkiverse.fury</groupId>
    <artifactId>quarkus-fury</artifactId>
    <version>0.2.1</version>
</dependency>

Usage

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

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

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

import io.quarkiverse.fury.FurySerialization;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

import org.apache.fury.BaseFury;

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

@Path("/fury")
@ApplicationScoped
public class FuryResources {
  @Inject
  BaseFury fury;

  @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) fury.deserialize(fury.serialize(foo1));
    return foo1.equals(foo2);
  }
}

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

quarkus.fury.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.fury.FurySerialization;

@FurySerialization(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.fury.FurySerialization;

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

Or you can configure by application.properties configurations.

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

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

Integartion in Quarkus REST/RESTEasy

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

@Path("/example")
@Produces("application/fury")
@Consumes("application/fury")
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.fury.language

The language of fury. The default is JAVA.

Environment variable: QUARKUS_FURY_LANGUAGE

java, xlang

java

quarkus.fury.required-class-registration

Require class registration for serialization. The default is true.

Environment variable: QUARKUS_FURY_REQUIRED_CLASS_REGISTRATION

boolean

true

quarkus.fury.track-ref

Whether track shared or circular references.

Environment variable: QUARKUS_FURY_TRACK_REF

boolean

false

quarkus.fury.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_FURY_COMPATIBLE_MODE

schema-consistent, compatible

schema-consistent

quarkus.fury.compress-number

Use variable length encoding for int/long.

Environment variable: QUARKUS_FURY_COMPRESS_NUMBER

boolean

true

quarkus.fury.compress-string

Whether compress string for small size.

Environment variable: QUARKUS_FURY_COMPRESS_STRING

boolean

true

quarkus.fury.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_FURY_DESERIALIZE_NONEXISTENT_CLASS

boolean

false

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

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

Environment variable: QUARKUS_FURY_DESERIALIZE_NONEXISTENT_ENUM_VALUE_AS_NULL

boolean

false

quarkus.fury.thread-safe

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

Environment variable: QUARKUS_FURY_THREAD_SAFE

boolean

true

quarkus.fury.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_FURY_REGISTER_CLASS_NAMES

string

Configurations of register class

Type

Default

quarkus.fury.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_FURY_REGISTER_CLASS__REGISTER_CLASS_NAME__CLASS_ID

int

-1

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

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

Environment variable: QUARKUS_FURY_REGISTER_CLASS__REGISTER_CLASS_NAME__SERIALIZER

string