Configuration

This page covers Scala-specific runtime configuration and Fory instance 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 runtime 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().withXlang(false)
  .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)
  // Enable schema evolution support for native-mode payloads
  .withCompatible(true)
  // Enable async compilation for better startup performance
  .withAsyncCompilation(true)
  .build()

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].

Security

Scala uses the Java runtime configuration surface. Keep class registration enabled for production and any untrusted payload source:

val fory = ForyScala.builder()
  .requireClassRegistration(true)
  .withMaxDepth(50)
  .build()

Security-related configuration:

• Keep requireClassRegistration(true) and register application classes or generated modules.
• Use withMaxDepth(...) to reject unexpectedly deep object graphs.
• Follow Java Configuration for allow-listing and unknown-class controls.