Skip to main content
Version: dev

Configuration

This page covers Kotlin-specific Fory instance configuration and creation.

Xlang Setup​

Fory Kotlin follows the Java builder default: xlang mode with compatible schema evolution. Use this path for cross-language Kotlin payloads, schema IDL generated Kotlin models, and KSP-generated xlang serializers.

import org.apache.fory.kotlin.ForyKotlin

val fory = ForyKotlin.builder()
    .withXlang(true)
    .requireClassRegistration(true)
    .build()

Native Mode Setup​

For same-language Kotlin/JVM payloads that need native JVM object behavior, use native mode explicitly:

import org.apache.fory.kotlin.ForyKotlin

val fory = ForyKotlin.builder().withXlang(false)
    .requireClassRegistration(true)
    .build()

Thread Safety​

Fory instance creation is not cheap. Instances should be shared between multiple serializations.

Single-Thread Usage​

import org.apache.fory.Fory
import org.apache.fory.kotlin.ForyKotlin

object ForyHolder {
    val fory: Fory = ForyKotlin.builder()
        .withXlang(true)
        .requireClassRegistration(true)
        .build()
}

Multi-Thread Usage​

For multi-threaded applications, use ThreadSafeFory:

import org.apache.fory.ThreadSafeFory
import org.apache.fory.kotlin.ForyKotlin

object ForyHolder {
    val fory: ThreadSafeFory = ForyKotlin.builder()
        .withXlang(true)
        .requireClassRegistration(true)
        .buildThreadSafeFory()
}

Using Builder Methods​

// Thread-safe Fory
val fory: ThreadSafeFory = ForyKotlin.builder()
    .withXlang(true)
    .requireClassRegistration(true)
    .buildThreadSafeFory()

Configuration​

All configuration options from Fory Java are available. See Java Configuration for the complete list.

Common options for Kotlin native-mode payloads:

import org.apache.fory.kotlin.ForyKotlin

val fory = ForyKotlin.builder().withXlang(false)
    // Enable reference tracking for circular references
    .withRefTracking(true)
    // Same-schema optimization. Use only when every reader and writer
    // always uses the same Kotlin/JVM schema.
    .withCompatible(false)
    // Enable async compilation for better startup performance
    .withAsyncCompilation(true)
    // Compression options
    .withIntCompressed(true)
    .withLongCompressed(true)
    .build()

Graph Memory Budget​

Kotlin uses the Java withMaxGraphMemoryBytes(...) option. It sets an approximate graph-memory gate for one root deserialization, mainly for materialized collections, maps, arrays, structs, and objects. It skips leaf values such as strings, binary data, primitive scalars, and dense primitive arrays, so actual process memory can be higher than this value. Leaf values are still gated by remaining input bytes: if the unread input does not contain enough bytes, Fory will not read or create that leaf value.

val fory = ForyKotlin.builder()
    .withMaxGraphMemoryBytes(128L * 1024 * 1024)
    .withMaxUnbackedContainerItems(8192)
    .build()

withMaxUnbackedContainerItems(...) limits collection elements and map entries whose repeated read bodies do not consume proportional input during one root deserialization. The default is 8192; zero is a strict limit.

Compatible Mode​

Compatible mode is enabled by default through the Java builder in both xlang and native mode. Keep this default when models may evolve independently, when services deploy separately, or when xlang schemas are written by hand in different languages.

Use withCompatible(false) only when the class schema used to deserialize every payload is always the same as the class schema used to serialize it and you want faster serialization and smaller size. For xlang payloads, call withCompatible(false) only after verifying that every language uses the same schema, or when native types are generated from Fory schema IDL.

Security​

See Kotlin Security for trust boundaries, safe reader configuration, and verification.