Apache Fory™ Scala

Apache Fory™ Scala provides optimized serializers for Scala types, built on top of Fory Java. It delivers high-performance serialization for the Scala ecosystem with full support for Scala-specific types and idioms.

Both Scala 2 and Scala 3 are supported.

Scala uses xlang mode for cross-language payloads by default. Use native mode with .withXlang(false) for Scala/JVM-only traffic when you want the JVM native object serialization path plus Scala-specific types such as case classes, collections, tuples, options, and enumerations.

Features

Supported Types

Apache Fory™ Scala is tested and works with the following types:

• Case classes: Full support for case class serialization with all field types
• Regular classes: POJO/bean style classes with constructor parameters
• Object singletons: Scala object singletons preserve identity after deserialization
• Collections: Seq, List, Vector, Set, Map, ArrayBuffer, and other Scala collections
• Tuples: All tuple types from Tuple1 to Tuple22
• Option types: Some and None
• Either types: Left and Right
• Enumerations: Both Scala 2 Enumeration and Scala 3 enum

Scala-Specific Features

• Default Value Support: Automatic handling of Scala class default parameters during schema evolution
• Singleton Preservation: object singletons maintain referential equality after deserialization
• Scala Collection Optimization: Optimized serializers for Scala's immutable and mutable collections

Quick Start

import org.apache.fory.Fory
import org.apache.fory.scala.ForyScala

case class Person(name: String, id: Long, github: String)
case class Point(x: Int, y: Int, z: Int)

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

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

  def main(args: Array[String]): Unit = {
    val p = Person("Shawn Yang", 1, "https://github.com/chaokunyang")
    println(fory.deserialize(fory.serialize(p)))
    println(fory.deserialize(fory.serialize(Point(1, 2, 3))))
  }
}

Default Value Support

Apache Fory™ Scala provides support for Scala class default values during deserialization. This feature enables forward/backward compatibility when case classes or regular Scala classes have default parameters.

How It Works

When a Scala class has default parameters, the Scala compiler generates methods in the companion object (for case classes) or in the class itself that return default values. Fory detects these methods and uses them when deserializing objects where certain fields are missing from the serialized data.

Native-Mode Example

import org.apache.fory.Fory
import org.apache.fory.scala.ForyScala

// Original case class
case class User(name: String, age: Int)

// Evolved case class with new fields and default values
case class UserV2(name: String, age: Int, email: String = "unknown", active: Boolean = true)

object DefaultValueExample {
  val fory: Fory = ForyScala.builder().withXlang(false)
    .build()

  def main(args: Array[String]): Unit = {
    // Serialize with old schema
    val oldUser = User("John", 30)
    val serialized = fory.serialize(oldUser)

    // Deserialize with new schema - missing fields get default values
    val newUser = fory.deserialize(serialized).asInstanceOf[UserV2]
    println(newUser) // UserV2(John, 30, unknown, true)
  }
}

Supported Default Value Types

• Primitive types: Int, Long, Double, Float, Boolean, Byte, Short, Char
• String: String
• Collections: List, Set, Map, Seq, etc.
• Option types: Option[T]
• Custom objects: Any serializable object

Thread-Safe Usage

For multi-threaded applications, use ThreadSafeFory:

import org.apache.fory.{Fory, ThreadSafeFory}
import org.apache.fory.scala.ForyScala

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

  fory.register(classOf[Person])
}

// Use in multiple threads
val bytes = ForyHolder.fory.serialize(person)
val result = ForyHolder.fory.deserialize(bytes)

Configuration

Fory Scala is built on Fory Java, so all Java configuration options are available. The default builder uses xlang mode with compatible schema evolution:

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

Native-mode payloads can opt into JVM schema evolution explicitly:

import org.apache.fory.Fory
import org.apache.fory.scala.ForyScala

val fory = ForyScala.builder().withXlang(false)
  // Enable reference tracking for circular references
  .withRefTracking(true)
  // Compatible schema evolution is enabled by default
  // Enable async compilation for better startup performance
  .withAsyncCompilation(true)
  // Compression options
  .withIntCompressed(true)
  .withLongCompressed(true)
  .build()

Documentation

Installation

Add the dependency with sbt:

libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.2.0"

Building

Fory Scala requires Fory Java to be installed first:

# Install Fory Java
cd ../java && mvn -T16 install -DskipTests

# Build Fory Scala
cd ../scala
sbt compile

Testing

sbt test

Code Format

sbt scalafmt

Additional Notes

• Fory Reuse: Always reuse Fory instances; creation is expensive
• Scala Internal Types: You may need to register some Scala internal types like scala.Enumeration.Val

Contributing

See CONTRIBUTING.md for development guidelines.

License

Licensed under the Apache License 2.0.