docs/object-serialization/scala/index.md

---
title: Scala Object Serialization
sidebar_position: 0
id: index
license: |
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
---

Apache Fory™ Scala provides optimized serializers for Scala types, built on top of Fory Java. It supports xlang mode for cross-language payloads and native mode for Scala/JVM-only object serialization. It supports all Scala object serialization:

- `case` class serialization
- `pojo/bean` class serialization
- `object` singleton serialization
- `collection` serialization (Seq, List, Map, etc.)
- `tuple` and `either` types
- `Option` types
- Scala 2 and 3 enumerations

The library artifact supports Scala 2.13 and Scala 3. Schema IDL generated
Scala source and macro-derived xlang serializers require Scala 3.

## Features

Fory Scala inherits all features from Fory Java, plus Scala-specific optimizations:

- **High Performance**: JIT code generation, zero-copy, 20-170x faster than traditional serialization
- **Scala Type Support**: Optimized serializers for case classes, singletons, collections, tuples, Option, Either
- **Default Value Support**: Automatic handling of Scala class default parameters during schema evolution
- **Singleton Preservation**: `object` singletons maintain referential equality after deserialization
- **Schema Evolution**: Forward/backward compatibility for class schema changes

See [Java Features](../java/index.md#features) for complete feature list.

## Installation

Add the dependency with sbt:

```sbt
libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.6.1"
```

### JDK25+

Scala uses the Fory Java core when running. On JDK25+, opening `java.lang.invoke` to Fory core is
also recommended. It avoids the current-JDK Unsafe fallback and is required when Unsafe
access is disabled or unavailable, including with `--sun-misc-unsafe-memory-access=deny`. Use
`ALL-UNNAMED` when Fory is on the classpath:

```bash
--add-opens=java.base/java.lang.invoke=ALL-UNNAMED
```

Use the Fory core module name when Fory is on the module path:

```bash
--add-opens=java.base/java.lang.invoke=org.apache.fory.core
```

## Quick Start

```scala
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))))
  }
}
```

## Xlang Mode And Native Mode

Use xlang mode for cross-language payloads and schemas shared with other Fory implementations. Xlang mode is the default Scala wire mode through the JVM builder, and Scala examples that use it set `.withXlang(true)` explicitly so the mode choice is visible.

Use native mode for Scala/JVM-only traffic. Native mode is selected with `.withXlang(false)` and inherits the JVM native-mode object serialization path from Fory Java while adding Scala-specific serializers for case classes, collections, tuples, options, and enumerations. It is optimized for JVM and Scala type systems and is the right path for same-language Scala/JVM framework replacement payloads. Compatible mode is enabled by default. Set `.withCompatible(false)` only when every reader and writer uses the same Scala/JVM schema and you want faster serialization and smaller size.

See [Configuration](configuration.md) for Scala builder setup and [Java Native Serialization](../java/native.md) for the full JVM native-mode behavior.

## Built on Fory Java

Fory Scala is built on top of Fory Java. Most configuration options, features, and concepts from Fory Java apply directly to Scala. Refer to the Java documentation for:

- [Configuration](../java/configuration.md) - All ForyBuilder options
- [Basic Serialization](../java/basic-serialization.md) - Serialization patterns and APIs
- [Type Registration](../java/type-registration.md) - Class registration and security
- [Schema Evolution](../java/schema-evolution.md) - Forward/backward compatibility
- [Custom Serializers](../java/custom-serializers.md) - Implement custom serializers
- [Compression](../java/compression.md) - Int, long, and string compression
- [Troubleshooting](../java/troubleshooting.md) - Common issues and solutions

## Scala-Specific Documentation

- [Configuration](configuration.md) - Scala-specific Fory setup requirements
- [Native Serialization](native.md) - Serializing Scala types in JVM-native mode
- [Schema Metadata](schema-metadata.md) - Scala annotations, references, enum IDs, and union metadata
- [Default Values](default-values.md) - Scala class default values support
- [Basic Serialization](basic-serialization.md) - Models, APIs, and interoperability in the default xlang mode
- [gRPC Support](../../grpc/scala.md) - Scala 3 generated gRPC service companions

Before decoding bytes from outside the application trust boundary, read
[Scala Security](security.md).