Configuration

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

Xlang Setup

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

import org.apache.fory.scala.ForyScala

val fory = ForyScala.builder()
  .withXlang(true)
  .build()

Register application classes before serialization:

fory.register(classOf[Person])
fory.register(classOf[Point])

Native Mode Setup

For same-language Scala/JVM payloads that need native JVM object behavior, you must:

1. Create the Fory instance with ForyScala.builder().withXlang(false), or install ForyScala with Fory.builder().withXlang(false).withModule(ForyScala).
2. Register application classes before serialization.

import org.apache.fory.scala.ForyScala

val fory = ForyScala.builder().withXlang(false)
  .build()

Registering Scala Internal Types

Depending on the object types you serialize, you may need to register some Scala internal types:

fory.register(Class.forName("scala.Enumeration.Val"))

To avoid such registration, you can disable class registration:

val fory = ForyScala.builder().withXlang(false)
  .requireClassRegistration(false)
  .build()

Note: Disabling class registration allows deserialization of unknown types. This is more flexible but may be insecure if the classes contain malicious code.

Reference Tracking

Circular references are common in Scala. Reference tracking should be enabled with withRefTracking(true):

val fory = ForyScala.builder()
  .withRefTracking(true)
  .build()

Note: If you don't enable reference tracking, StackOverflowError may occur for some Scala versions when serializing Scala Enumeration.

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.scala.ForyScala

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

Multi-Thread Usage

For multi-threaded applications, use ThreadSafeFory:

import org.apache.fory.ThreadSafeFory
import org.apache.fory.scala.ForyScala

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

Configuration

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

Common options for Scala native-mode payloads:

import org.apache.fory.scala.ForyScala

val fory = ForyScala.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 Scala/JVM schema.
  .withCompatible(false)
  // Enable async compilation for better startup performance
  .withAsyncCompilation(true)
  .build()

Graph Memory Budget

Scala 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 = ForyScala.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.

Xlang Mode

For Scala xlang or schema IDL generated code, use the default xlang mode and register the generated schema module:

import org.apache.fory.scala.ForyScala
import example.ExampleForyModule

val fory = ForyScala.builder()
  .withXlang(true)
  .withRefTracking(true)
  .withModule(ExampleForyModule)
  .build()

In xlang mode, Scala collections use canonical list, set, and map payloads instead of Scala factory payloads. Generated optional fields use Option[T].

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 Scala Security for trust boundaries, safe reader configuration, and verification.