From d732ca93922145507f3fcd6d07cae33adce69fbb Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:10:22 +0800 Subject: [PATCH 01/19] docs: expand Why Fory capabilities --- README.md | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 94386e15ea..c061dbb7d5 100644 --- a/README.md +++ b/README.md @@ -34,14 +34,36 @@ references. directly in the schema, alongside numbers, strings, lists, maps, arrays, enums, structs, and unions. Define schemas once, then generate native domain objects for each language without forcing wrapper types into user code. -- **Row-Format Random Access**: Read fields, arrays, and nested values without - rebuilding full objects, with zero-copy access and partial reads. - **Optimized Implementations**: Java JIT serializers and generated/static serializers in other language implementations keep hot paths fast and payloads compact. - **Language And Platform Support**: Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Swift, Dart, Scala, and Kotlin, including GraalVM native image, Android, Dart VM/Flutter/web, and Node.js/browser JavaScript. +**Beyond Cross-Language Serialization** + +For same-language workloads, Fory provides native serialization modes that +support broader language-specific object models: + +- **Java Native Serialization**: A high-performance replacement for JDK + serialization, Hessian, Kryo, and FST in Java-only systems. It natively + supports JDK custom serialization hooks including `writeObject`, + `readObject`, `writeReplace`, and `readResolve`. +- **Python Native Serialization**: A faster and more compact replacement for + `pickle` and `cloudpickle` in Python-only systems. It supports Python + classes, modules, global and local functions, `__reduce__`/`__reduce_ex__`, + and `__getstate__`/`__setstate__`, with fine-grained deserialization + controls through `DeserializationPolicy` for class, module, function, + reduction, and state restoration behavior. + +Fory also provides specialized formats for other data-processing requirements: + +- **Row Format**: Read fields, arrays, and nested values without rebuilding + complete objects, with zero-copy access and partial reads. +- **JSON Serialization for Java**: Interoperable JSON for HTTP APIs, browsers, + logs, and configuration, with support for standard JDKs, GraalVM native + images, Android, and Java 17 records. + ## Performance Benchmarks show Fory delivering higher throughput and smaller serialized From 5cdc06909793663cddf29a3b86736613cb742a0f Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:11:11 +0800 Subject: [PATCH 02/19] docs: streamline Why Fory section --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index c061dbb7d5..13d8713233 100644 --- a/README.md +++ b/README.md @@ -40,8 +40,6 @@ references. JavaScript/TypeScript, C#, Swift, Dart, Scala, and Kotlin, including GraalVM native image, Android, Dart VM/Flutter/web, and Node.js/browser JavaScript. -**Beyond Cross-Language Serialization** - For same-language workloads, Fory provides native serialization modes that support broader language-specific object models: From fb0a6167fcdcbef6231c8c081f0890650051e73d Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:12:02 +0800 Subject: [PATCH 03/19] docs: emphasize Fory JSON performance --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 13d8713233..a4c0ccd024 100644 --- a/README.md +++ b/README.md @@ -58,9 +58,11 @@ Fory also provides specialized formats for other data-processing requirements: - **Row Format**: Read fields, arrays, and nested values without rebuilding complete objects, with zero-copy access and partial reads. -- **JSON Serialization for Java**: Interoperable JSON for HTTP APIs, browsers, - logs, and configuration, with support for standard JDKs, GraalVM native - images, Android, and Java 17 records. +- **High-Performance JSON Serialization for Java**: Built for maximum + throughput with runtime-generated codecs and optimized readers and writers, + while remaining interoperable with standard JSON for HTTP APIs, browsers, + logs, and configuration. Supports Java 8 and later on standard JDKs, GraalVM + native images, and Android, including Java 17 records. ## Performance From 042686d8b3a082b4db31e17fd6dedb846b0f943e Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:12:48 +0800 Subject: [PATCH 04/19] docs: focus Fory JSON description --- README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a4c0ccd024..1f61add31d 100644 --- a/README.md +++ b/README.md @@ -59,10 +59,9 @@ Fory also provides specialized formats for other data-processing requirements: - **Row Format**: Read fields, arrays, and nested values without rebuilding complete objects, with zero-copy access and partial reads. - **High-Performance JSON Serialization for Java**: Built for maximum - throughput with runtime-generated codecs and optimized readers and writers, - while remaining interoperable with standard JSON for HTTP APIs, browsers, - logs, and configuration. Supports Java 8 and later on standard JDKs, GraalVM - native images, and Android, including Java 17 records. + throughput through runtime-generated codecs and optimized readers and + writers. Supports Java 8 and later on standard JDKs, GraalVM native images, + and Android, including Java 17 records. ## Performance From 6d2a0038d5043cd6526bd89137c7069e9b36f42f Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:14:31 +0800 Subject: [PATCH 05/19] docs: simplify native serialization features --- README.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 1f61add31d..b62d5ba60e 100644 --- a/README.md +++ b/README.md @@ -44,15 +44,12 @@ For same-language workloads, Fory provides native serialization modes that support broader language-specific object models: - **Java Native Serialization**: A high-performance replacement for JDK - serialization, Hessian, Kryo, and FST in Java-only systems. It natively - supports JDK custom serialization hooks including `writeObject`, - `readObject`, `writeReplace`, and `readResolve`. + serialization, Hessian, Kryo, and FST in Java-only systems. It supports JDK + custom serialization semantics. - **Python Native Serialization**: A faster and more compact replacement for - `pickle` and `cloudpickle` in Python-only systems. It supports Python - classes, modules, global and local functions, `__reduce__`/`__reduce_ex__`, - and `__getstate__`/`__setstate__`, with fine-grained deserialization - controls through `DeserializationPolicy` for class, module, function, - reduction, and state restoration behavior. + `pickle` and `cloudpickle` in Python-only systems. It supports classes, + modules, functions, and custom object state, with fine-grained + deserialization controls through `DeserializationPolicy`. Fory also provides specialized formats for other data-processing requirements: From de10f91688f0d1af803e3a7551500d2be85047ca Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:15:52 +0800 Subject: [PATCH 06/19] docs: add JSON serialization section --- README.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/README.md b/README.md index b62d5ba60e..e0ceab4a9f 100644 --- a/README.md +++ b/README.md @@ -718,6 +718,39 @@ message TreeNode { See the [Fory IDL and compiler guide](https://fory.apache.org/docs/compiler). +## JSON Serialization + +Fory JSON is a high-performance, thread-safe JSON codec for Java. It combines +optimized readers and writers with runtime-generated codecs where available to +maximize throughput. It supports Java 8 and later on standard JDKs, GraalVM +native images, and Android, with Java records supported on Java 17 and later. + +Add `org.apache.fory:fory-json` with the same version as `fory-core`, then reuse +one `ForyJson` instance across threads: + +```java +import org.apache.fory.json.ForyJson; + +public class User { + public long id; + public String name; + + public User() {} + + public User(long id, String name) { + this.id = id; + this.name = name; + } +} + +ForyJson json = ForyJson.builder().build(); +byte[] bytes = json.toJsonBytes(new User(7, "Alice")); +User user = json.fromJson(bytes, User.class); +``` + +See the [Fory JSON guide](docs/guide/java/json-support.md) for installation, +configuration, supported types, custom codecs, and platform-specific setup. + ## Row Format Row format is for random access and partial reads. These examples encode an From e1897b46599c427cac1813daaa53edf30ad48a02 Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:16:06 +0800 Subject: [PATCH 07/19] docs: add Fory JSON string example --- README.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e0ceab4a9f..33970bde68 100644 --- a/README.md +++ b/README.md @@ -744,8 +744,13 @@ public class User { } ForyJson json = ForyJson.builder().build(); -byte[] bytes = json.toJsonBytes(new User(7, "Alice")); -User user = json.fromJson(bytes, User.class); +User input = new User(7, "Alice"); + +String text = json.toJson(input); +User fromText = json.fromJson(text, User.class); + +byte[] bytes = json.toJsonBytes(input); +User fromBytes = json.fromJson(bytes, User.class); ``` See the [Fory JSON guide](docs/guide/java/json-support.md) for installation, From 1073478a7f19d2e6fd2808890d600c722d3cdf74 Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:25:57 +0800 Subject: [PATCH 08/19] docs(java): reorganize README with Fory JSON --- java/README.md | 329 +++++++++++++++++++++++++++++++------------------ 1 file changed, 212 insertions(+), 117 deletions(-) diff --git a/java/README.md b/java/README.md index e7c41de149..e1fc68e4b3 100644 --- a/java/README.md +++ b/java/README.md @@ -4,66 +4,108 @@ [![Java Version](https://img.shields.io/badge/Java-8%2B-blue?style=for-the-badge)](https://www.oracle.com/java/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge)](https://opensource.org/licenses/Apache-2.0) -Apache Fory™ Java provides blazingly-fast serialization for the Java ecosystem, delivering up to **170x performance improvement** over traditional frameworks through JIT compilation and zero-copy techniques. +Apache Fory™ Java provides high-performance binary object serialization, JSON +serialization, and a random-access row format for the Java ecosystem. -## Features +## Choose a Format + +| Format | Use it when | Module | Guide | +| ------------------------------- | -------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------- | +| **Binary Object Serialization** | You need compact object graphs in Java native mode or across supported languages | `fory-core` | [Java guide](../docs/guide/java/) | +| **JSON Serialization** | You need high-throughput standard JSON for Java applications | `fory-json` | [Fory JSON guide](../docs/guide/java/json-support.md) | +| **Row Format** | You need zero-copy random access, partial reads, or Arrow integration | `fory-format` | [Row-format guide](../docs/guide/java/row-format.md) | -### High Performance +Keep all Fory modules in one application on the same version. -- **JIT Code Generation**: Highly-extensible JIT framework generates serializer code at runtime using async multi-threaded compilation, delivering 20-170x speedup through: - - Inlining variables to reduce memory access - - Inlining method calls to eliminate virtual dispatch overhead - - Minimizing conditional branching - - Eliminating hash lookups -- **Zero-Copy**: Direct memory access without intermediate buffer copies; row format supports random access and partial serialization -- **Variable-Length Encoding**: Optimized compression for integers, longs -- **Meta Sharing**: Cached class metadata reduces redundant type information -- **SIMD Acceleration**: Java Vector API support for array operations (Java 16+) +## Features -### Drop-in Replacement +### Binary Object Serialization + +- **Generated Codecs**: JIT-generated serializers inline data access and reduce + virtual dispatch, branching, and metadata lookups on hot paths. +- **Native and Cross-Language Modes**: Use Java-native object semantics for + Java-only traffic or a portable wire format across supported languages. +- **Object Graph Semantics**: Preserve shared and circular references, + polymorphism, and schema evolution. +- **Compact Encoding**: Variable-length integer encoding, metadata sharing, + string compression, and optional numeric-array compression reduce payload size. +- **Java Object Model**: Native mode supports ordinary Java classes, records, + JDK custom serialization semantics, `Externalizable`, and deep copy. +- **Security Controls**: Class registration, type checking, depth limits, and + configurable deserialization policies protect decoding boundaries. + +### JSON Serialization + +- **Performance-First Codec**: Optimized readers and writers plus interpreted + and runtime-generated codecs keep JSON encoding and decoding fast. +- **Java Object Mapping**: Supports ordinary objects, Java 17 records, immutable + creator-based classes, common JDK types, generic containers, custom codecs, + and annotation-declared polymorphism. +- **String and UTF-8 APIs**: Read and write both `String` and UTF-8 `byte[]` + without requiring separate mapper instances. +- **Thread-Safe Runtime**: Build one immutable `ForyJson` instance and reuse it + across threads. + +### Row Format -- **100% JDK Serialization Compatible**: Supports `writeObject`/`readObject`/`writeReplace`/`readResolve`/`readObjectNoData`/`Externalizable` -- **Java 8+ Support**: Works across all modern Java versions including Java 17+ records -- **GraalVM Native Image**: AOT compilation support without reflection configuration +- **Zero-Copy Random Access**: Read fields and nested values without rebuilding + complete objects. +- **Partial Reads**: Decode only the data required by an analytics or query path. +- **Apache Arrow Integration**: Convert between Fory row data and Arrow data for + columnar processing. -### Advanced Features +### Platforms -- **Reference Tracking**: Automatic handling of shared and circular references -- **Schema Evolution**: Forward/backward compatibility for class schema changes -- **Polymorphism**: Full support for inheritance hierarchies and interfaces -- **Deep Copy**: Efficient deep cloning of complex object graphs with reference preservation -- **Security**: Class registration and configurable deserialization policies +- `fory-core` and `fory-json` support Java 8 and later; Java records require + Java 17 or later. +- `fory-format` targets Java 11 and later. +- `fory-core` and `fory-json` run on standard JDKs, GraalVM native images, and + Android. Optional SIMD array acceleration in `fory-core` uses the Java Vector + API on Java 16 and later. ## Documentation -| Topic | Description | Source Doc Link | Website Doc Link | -| --------------------------- | -------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | -| **Java Guide** | Java xlang and native mode usage | [docs/guide/java](../docs/guide/java) | [Java Guide](https://fory.apache.org/docs/guide/java/) | -| **GraalVM Native Image** | Native image support | [graalvm-support.md](../docs/guide/java/graalvm-support.md) | [GraalVM Support](https://fory.apache.org/docs/guide/java/graalvm_support) | -| **Java Serialization Spec** | Protocol specification | [java_serialization_spec.md](../docs/specification/java_serialization_spec.md) | [Java Serialization Spec](https://fory.apache.org/docs/specification/java_serialization_spec) | -| **Java Benchmarks** | Performance data and plots | [java/README.md](../docs/benchmarks/java/README.md) | [Java Benchmarks](https://fory.apache.org/docs/benchmarks/java) | +| Topic | Description | Source Doc Link | Website Doc Link | +| --------------------------- | ----------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | +| **Java Guide** | Binary xlang and native mode usage | [docs/guide/java](../docs/guide/java) | [Java Guide](https://fory.apache.org/docs/guide/java/) | +| **Fory JSON** | JSON installation, APIs, and types | [json-support.md](../docs/guide/java/json-support.md) | [Fory JSON](https://fory.apache.org/docs/guide/java/json_support) | +| **Row Format** | Random access and Arrow integration | [row-format.md](../docs/guide/java/row-format.md) | [Row Format](https://fory.apache.org/docs/guide/java/row_format) | +| **GraalVM Native Image** | Native image support | [graalvm-support.md](../docs/guide/java/graalvm-support.md) | [GraalVM Support](https://fory.apache.org/docs/guide/java/graalvm_support) | +| **Java Serialization Spec** | Binary protocol specification | [java_serialization_spec.md](../docs/specification/java_serialization_spec.md) | [Java Serialization Spec](https://fory.apache.org/docs/specification/java_serialization_spec) | +| **Java Benchmarks** | Performance data and plots | [java/README.md](../docs/benchmarks/java/README.md) | [Java Benchmarks](https://fory.apache.org/docs/benchmarks/java) | ## Modules -| Module | Description | Maven Artifact | -| ------------------------------------ | ------------------------------------- | --------------------------------- | -| **fory-core** | Core serialization engine | `org.apache.fory:fory-core` | -| **fory-format** | Row format and Apache Arrow support | `org.apache.fory:fory-format` | -| [**fory-json**](fory-json/README.md) | JSON serialization and parsing | `org.apache.fory:fory-json` | -| **fory-extensions** | Protobuf support and meta compression | `org.apache.fory:fory-extensions` | -| **fory-test-core** | Testing utilities and data generators | `org.apache.fory:fory-test-core` | +| Module | Description | Maven Artifact | +| ------------------------------------ | ----------------------------------------- | --------------------------------- | +| **fory-core** | Binary native and xlang serialization | `org.apache.fory:fory-core` | +| [**fory-json**](fory-json/README.md) | High-performance JSON codec | `org.apache.fory:fory-json` | +| **fory-format** | Row format and Apache Arrow support | `org.apache.fory:fory-format` | +| **fory-extensions** | Protobuf support and metadata compression | `org.apache.fory:fory-extensions` | +| **fory-test-core** | Testing utilities and data generators | `org.apache.fory:fory-test-core` | ## Installation +Add only the artifacts required by your chosen formats and keep their versions +aligned. `fory-json` includes `fory-core` transitively. + ### Maven ```xml + org.apache.fory fory-core 1.4.0 + + + org.apache.fory + fory-json + 1.4.0 + + org.apache.fory @@ -77,15 +119,16 @@ Apache Fory™ Java provides blazingly-fast serialization for the Java ecosystem fory-extensions 1.4.0 - ``` ### Gradle ```gradle dependencies { + // Binary object serialization implementation 'org.apache.fory:fory-core:1.4.0' - // Optional modules + // Add only the optional formats and extensions you use + implementation 'org.apache.fory:fory-json:1.4.0' implementation 'org.apache.fory:fory-format:1.4.0' implementation 'org.apache.fory:fory-extensions:1.4.0' } @@ -106,15 +149,14 @@ Use the Fory core module name when Fory is on the module path: --add-opens=java.base/java.lang.invoke=org.apache.fory.core ``` -## Quick Start +## Binary Object Serialization -### Basic Usage +### Quick Start Create a Fory instance, register your classes, and start serializing objects. Remember to reuse the Fory instance for optimal performance: ```java -import org.apache.fory.*; -import org.apache.fory.config.*; +import org.apache.fory.Fory; // Create Fory instance (should be reused). Java defaults to xlang mode with // compatible schema evolution. @@ -123,15 +165,15 @@ Fory fory = Fory.builder() .requireClassRegistration(true) .build(); -// Register your classes -fory.register(MyClass.class); +// Register the same type identity on every xlang peer +fory.register(MyClass.class, "example.MyClass"); // Serialize MyClass object = new MyClass(); byte[] bytes = fory.serialize(object); // Deserialize -MyClass result = (MyClass) fory.deserialize(bytes); +MyClass result = fory.deserialize(bytes, MyClass.class); ``` ### Thread-Safe Usage @@ -139,14 +181,17 @@ MyClass result = (MyClass) fory.deserialize(bytes); For multi-threaded environments, use `ThreadSafeFory` which maintains a pool of Fory instances: ```java -import org.apache.fory.*; -import org.apache.fory.config.*; +import org.apache.fory.Fory; +import org.apache.fory.ThreadSafeFory; // Create thread-safe xlang Fory instance -private static final ThreadSafeFory fory = Fory.builder().withXlang(true).buildThreadSafeFory(); +private static final ThreadSafeFory fory = Fory.builder() + .withXlang(true) + .requireClassRegistration(true) + .buildThreadSafeFory(); static { - fory.register(MyClass.class); + fory.register(MyClass.class, "example.MyClass"); } // Use in multiple threads @@ -215,9 +260,7 @@ fory.register(MyClass.class, 1); byte[] bytes = fory.serialize(object); ``` -## Configuration Options - -### ForyBuilder Options +### Configuration Configure Fory with various options to suit your specific use case: @@ -245,14 +288,17 @@ Fory fory = Fory.builder() See the [Java guide](../docs/guide/java/) for detailed configuration options. -## Advanced Features - -### JDK Serialization Compatibility +### JDK Custom Serialization Semantics In native mode, Fory supports JDK serialization APIs with much better performance. Use native mode when replacing Java-only JDK serialization, Kryo, FST, Hessian, or Protocol Buffers payloads: ```java +import java.io.IOException; +import java.io.ObjectInputStream; +import java.io.ObjectOutputStream; +import java.io.Serializable; + public class MyClass implements Serializable { private void writeObject(ObjectOutputStream out) throws IOException { // Custom serialization logic @@ -286,58 +332,6 @@ MyClass original = new MyClass(); MyClass copy = fory.copy(original); ``` -### Row Format - -Fory provides a cache-friendly binary row format optimized for random access and analytics: - -- **Zero-Copy Random Access**: Read individual fields without deserializing entire objects -- **Partial Serialization**: Skip unnecessary fields during serialization -- **Cross-Language Compatible**: Row format data can be read by Python, C++ -- **Apache Arrow Integration**: Convert row format to/from Arrow RecordBatch for analytics - -```java -import org.apache.fory.format.encoder.*; -import org.apache.fory.format.row.*; - -public class Bar { - String f1; - List f2; -} - -public class Foo { - int f1; - List f2; - Map f3; - List f4; -} - -// Create row encoder -RowEncoder encoder = Encoders.bean(Foo.class); - -// Serialize to row format -Foo foo = new Foo(); -foo.f1 = 10; -foo.f2 = IntStream.range(0, 1000).boxed().collect(Collectors.toList()); -BinaryRow binaryRow = encoder.toRow(foo); - -// Zero-copy random access to fields -BinaryArray f2Array = binaryRow.getArray(1); // Access f2 without deserializing entire object -BinaryArray f4Array = binaryRow.getArray(3); // Access f4 - -// Zero-copy access nested fields -BinaryRow barStruct = f4Array.getStruct(10); // Get 11th element -long value = barStruct.getArray(1).getInt64(5); // Access nested field - -// Partial deserialization -RowEncoder barEncoder = Encoders.bean(Bar.class); -Bar partialBar = barEncoder.fromRow(barStruct); // Deserialize only one Bar object - -// Full deserialization -Foo deserializedFoo = encoder.fromRow(binaryRow); -``` - -See the [Java row-format guide](../docs/guide/java/row-format.md) for more details. - ### Array Compression Use width compression for integer and long arrays to reduce serialized size when array elements have small values. JDK 8 through 15 use scalar range analysis; JDK 16 and later automatically select the Vector API implementation from the multi-release JAR. @@ -364,7 +358,118 @@ On JDK 16 or later, resolve the incubator Vector API module when starting the ap java --add-modules=jdk.incubator.vector ... ``` -### GraalVM Native Image +### Performance Guidelines + +1. Reuse `Fory` or `ThreadSafeFory` instances instead of rebuilding runtime + state for each operation. +2. Register application classes to avoid repeated type metadata and keep type + identity explicit. +3. Use native mode for Java-only payloads; use xlang mode only when payloads + must cross language boundaries. +4. Keep compatible mode enabled when schemas may differ. Disable it only when + every reader and writer always uses the same schema. +5. Disable reference tracking only when shared identity and circular references + are not part of the data model. +6. Enable string, integer, long, or numeric-array compression only after + measuring the payload distribution and throughput tradeoff. +7. Warm up generated serializers before measuring steady-state performance. + +## JSON Serialization + +Fory JSON is a performance-first, thread-safe JSON codec for Java. Optimized +readers and writers handle `String` and UTF-8 `byte[]` directly, while +runtime-generated codecs accelerate object mapping where runtime code generation +is available. + +Build one `ForyJson` instance and reuse it across threads: + +```java +import java.nio.charset.StandardCharsets; +import org.apache.fory.json.ForyJson; + +public final class JsonExample { + private static final ForyJson JSON = ForyJson.builder().build(); + + public static final class User { + public long id; + public String name; + + public User() {} + + public User(long id, String name) { + this.id = id; + this.name = name; + } + } + + public static void main(String[] args) { + User input = new User(7, "Alice"); + + String text = JSON.toJson(input); + User fromText = JSON.fromJson(text, User.class); + + byte[] utf8 = JSON.toJsonBytes(input); + User fromUtf8 = JSON.fromJson(utf8, User.class); + + System.out.println(text); + System.out.println(new String(utf8, StandardCharsets.UTF_8)); + System.out.println(fromText.name + " / " + fromUtf8.name); + } +} +``` + +Fory JSON supports Java 8 and later on standard JDKs, GraalVM native images, +and Android. Java records are supported on Java 17 and later. See the +[Fory JSON guide](../docs/guide/java/json-support.md) for supported types, +annotations, custom codecs, security controls, and platform setup. + +## Row Format + +Fory row format is a cache-friendly binary format for random access and +analytics. It can read fields, arrays, and nested values without rebuilding the +complete object. + +```java +import org.apache.fory.format.encoder.Encoders; +import org.apache.fory.format.encoder.RowEncoder; +import org.apache.fory.format.row.ArrayData; +import org.apache.fory.format.row.binary.BinaryRow; +import org.apache.fory.format.type.Schema; + +public final class RowExample { + public static final class User { + public int id; + public String name; + public int[] scores; + } + + public static void main(String[] args) { + RowEncoder encoder = Encoders.bean(User.class); + + User user = new User(); + user.id = 1; + user.name = "Alice"; + user.scores = new int[] {98, 100, 95}; + + BinaryRow row = encoder.toRow(user); + + Schema schema = encoder.schema(); + Schema.StringField nameField = schema.stringField("name"); + Schema.ArrayField scoresField = schema.arrayField("scores"); + + String name = nameField.get(row); + ArrayData scores = scoresField.get(row); + int secondScore = scores.getInt32(1); + + System.out.println(name + ": " + secondScore); + } +} +``` + +See the [Java row-format guide](../docs/guide/java/row-format.md) for nested +structs, arrays, maps, partial deserialization, and Arrow integration. + +## GraalVM Native Image Fory supports GraalVM Native Image without application reflection configuration. Binary serialization generates serializers while the image is built; the Fory annotation processor @@ -427,16 +532,6 @@ mvn -T16 spotless:apply mvn -T16 checkstyle:check ``` -## Performance Tips - -1. **Reuse Fory Instances**: Creating Fory is expensive; reuse instances across serializations -2. **Enable Compression**: For numeric-heavy data, enable int/long compression -3. **Disable Reference Tracking**: If no circular references exist, disable tracking for better performance -4. **Use native mode**: For Java-only payloads, use `withXlang(false)`. Native mode reduces type metadata overhead and supports more Java-native types not available in xlang mode -5. **Warm Up**: Allow JIT compilation to complete before benchmarking -6. **Register Classes**: Class registration reduces metadata overhead -7. **Compress numeric arrays**: Enable array compression when numeric array values usually fit in narrower primitive types - ## Contributing See [CONTRIBUTING.md](../CONTRIBUTING.md) for development guidelines. From 2b03502c90888ee451a4d899ba80d6220f011a73 Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:32:32 +0800 Subject: [PATCH 09/19] docs: expand Java JSON and Schema IDL guides --- README.md | 37 +++++++++-- docs/guide/java/index.md | 130 +++++++++++++++++++++++++++++++-------- 2 files changed, 137 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 33970bde68..9e4cfa29d4 100644 --- a/README.md +++ b/README.md @@ -698,11 +698,25 @@ val fory = ForyKotlin.builder() ## Schema IDL -Fory IDL is Fory's schema language for shared data models. It supports -references, nullable fields, lists, maps, arrays, enums, messages, and unions, -and generates native data structures for Java, Python, C++, Go, Rust, -JavaScript/TypeScript, C#, Swift, Dart, Scala, and Kotlin. Use it when multiple -languages need one shared contract. +Fory IDL is Fory's schema-first path for shared data models. Use it when +multiple languages need one explicit contract, stable field identities, and +generated native domain objects instead of manually coordinating equivalent +types in every implementation. + +The schema supports primitive values, nullable fields, lists, maps, dense +arrays, enums, messages, unions, imports, and first-class shared or circular +references. The compiler generates idiomatic models and Fory integration for +Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Swift, Dart, Scala, and +Kotlin. It can also generate Fory-backed gRPC service companions for supported +languages. + +Install the compiler from PyPI: + +```bash +pip install fory-compiler +``` + +Define the shared model in `tree.fdl`: ```protobuf package tree; @@ -716,7 +730,18 @@ message TreeNode { } ``` -See the [Fory IDL and compiler guide](https://fory.apache.org/docs/compiler). +Generate native models for the languages used by your application: + +```bash +foryc tree.fdl --lang java,python,rust --output ./generated +``` + +Generated types use each language's normal classes, structs, dataclasses, +annotations, macros, or registration helpers, so application code works with +native domain objects while all peers share the same Fory schema. See the +[Fory IDL and compiler guide](https://fory.apache.org/docs/compiler) for the +complete type system, language-specific output options, schema evolution, and +gRPC generation. ## JSON Serialization diff --git a/docs/guide/java/index.md b/docs/guide/java/index.md index 9a8cfc4322..435c6574a3 100644 --- a/docs/guide/java/index.md +++ b/docs/guide/java/index.md @@ -19,56 +19,98 @@ license: | limitations under the License. --- -Apache Fory™ provides blazingly fast Java object serialization with JIT compilation and zero-copy techniques. Java supports both xlang mode and native mode. Xlang mode is the default cross-language wire format and uses compatible schema evolution. Native mode is the Java-only wire format for same-language object serialization, JDK serialization replacement behavior, framework replacement, and Java-native object graph features. +Apache Fory™ Java provides high-performance binary object serialization, JSON +serialization, and a random-access row format. Binary serialization supports +xlang mode for cross-language payloads and native mode for Java-only object +graphs. [Fory JSON](json-support.md) is a separate, performance-first standard +JSON codec with its own object-mapping model. -Fory also provides a separate [JSON codec](json-support.md) for interoperable text payloads. JSON is -not the native or xlang binary protocol and has its own object-mapping annotations and limits. +## Choose a Format + +| Format | Use it when | Artifact | Start here | +| ------------------------------- | -------------------------------------------------------------------------------- | ----------------------------- | --------------------------------------------- | +| **Binary Object Serialization** | You need compact object graphs in Java native mode or across supported languages | `org.apache.fory:fory-core` | [Basic Serialization](basic-serialization.md) | +| **Fory JSON** | You need high-throughput standard JSON for Java applications | `org.apache.fory:fory-json` | [JSON Support](json-support.md) | +| **Row Format** | You need zero-copy random access, partial reads, or Arrow integration | `org.apache.fory:fory-format` | [Row Format](row-format.md) | ## Features -### High Performance +### Binary Object Serialization + +- **Generated Codecs**: JIT-generated serializers reduce virtual dispatch, + branching, and metadata lookups on hot paths. +- **Native and Xlang Modes**: Choose Java-native object semantics or a portable + wire format shared with other Fory implementations. +- **Compact Encoding**: Variable-length integers, metadata sharing, string + compression, and optional numeric-array compression reduce payload size. +- **Object Graph Semantics**: Preserve shared and circular references, + polymorphism, schema evolution, and deep-copy identity. + +### Fory JSON + +- **Performance-First Codec**: Optimized readers and writers plus interpreted + and runtime-generated codecs keep JSON encoding and decoding fast. +- **Java Object Mapping**: Supports ordinary objects, Java 17 records, immutable + creator-based classes, common JDK types, generic containers, custom codecs, + and annotation-declared polymorphism. +- **String and UTF-8 APIs**: Read and write `String` and UTF-8 `byte[]` with one + immutable, thread-safe `ForyJson` instance. -- **JIT Code Generation**: Highly-extensible JIT framework generates serializer code at runtime using async multi-threaded compilation, delivering 20-170x speedup through: - - Inlining variables to reduce memory access - - Inlining method calls to eliminate virtual dispatch overhead - - Minimizing conditional branching - - Eliminating hash lookups -- **Zero-Copy**: Direct memory access without intermediate buffer copies; row format supports random access and partial serialization -- **Variable-Length Encoding**: Optimized compression for integers, longs -- **Meta Sharing**: Cached class metadata reduces redundant type information -- **SIMD Acceleration**: Java Vector API support for array operations (Java 16+) +### Java Native Serialization -### Drop-in Replacement +- **Framework Replacement**: Replace JDK serialization, Kryo, FST, Hessian, or + Java-only Protocol Buffers payloads in Java-only systems. +- **JDK Semantics**: Supports JDK custom serialization behavior and + `Externalizable` in native mode. +- **Security Controls**: Class registration, type checking, depth limits, and + configurable deserialization policies protect decoding boundaries. -- **100% JDK Serialization Compatible**: Supports `writeObject`/`readObject`/`writeReplace`/`readResolve`/`readObjectNoData`/`Externalizable` -- **Java 8+ Support**: Works across all modern Java versions including Java 17+ records -- **GraalVM Native Image**: AOT compilation support without reflection configuration -- **Android API 26+ Support**: Core object serialization works on Android without runtime code generation. +### Row Format -### Advanced Features +- **Zero-Copy Random Access**: Read fields and nested values without rebuilding + complete objects. +- **Partial Reads**: Decode only the data required by an analytics or query path. +- **Apache Arrow Integration**: Convert between Fory row data and Arrow data for + columnar processing. -- **Reference Tracking**: Automatic handling of shared and circular references -- **Schema Evolution**: Forward/backward compatibility for class schema changes -- **Polymorphism**: Full support for inheritance hierarchies and interfaces -- **Deep Copy**: Efficient deep cloning of complex object graphs with reference preservation -- **Security**: Class registration and configurable deserialization policies +### Platforms + +- `fory-core` and `fory-json` support Java 8 and later; Java records require + Java 17 or later. +- `fory-format` targets Java 11 and later and is not supported on Android. +- `fory-core` and `fory-json` run on standard JDKs, GraalVM native images, and + Android API level 26 and later. ## Installation +Add the artifact for the format you use and keep all Fory modules on the same +version. `fory-json` includes `fory-core` transitively. + ### Maven ```xml + org.apache.fory fory-core 1.4.0 + + + + org.apache.fory + fory-json + 1.4.0 + ``` ### Gradle ```kotlin +// Binary object serialization implementation("org.apache.fory:fory-core:1.4.0") +// JSON serialization +implementation("org.apache.fory:fory-json:1.4.0") ``` ### JDK25+ @@ -160,6 +202,46 @@ public class Example { } ``` +### Fory JSON + +`ForyJson` is immutable and thread-safe after construction. Reuse one instance +for both `String` and UTF-8 `byte[]` operations: + +```java +import org.apache.fory.json.ForyJson; + +public final class JsonExample { + private static final ForyJson JSON = ForyJson.builder().build(); + + public static final class User { + public long id; + public String name; + + public User() {} + + public User(long id, String name) { + this.id = id; + this.name = name; + } + } + + public static void main(String[] args) { + User input = new User(7, "Alice"); + + String text = JSON.toJson(input); + User fromText = JSON.fromJson(text, User.class); + + byte[] utf8 = JSON.toJsonBytes(input); + User fromUtf8 = JSON.fromJson(utf8, User.class); + + System.out.println(fromText.name + " / " + fromUtf8.name); + } +} +``` + +See [JSON Support](json-support.md) for supported types, annotations, custom +codecs, security controls, and platform setup. + ## Xlang Mode And Native Mode Use xlang mode for cross-language payloads and schemas shared with non-Java implementations. It is the default Java wire mode, and Java examples that use it set `.withXlang(true)` explicitly so the mode choice is visible. From 9e70bdd45a7c284f9d4dd9ff865bce8914ff3d5a Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:35:56 +0800 Subject: [PATCH 10/19] docs(java): separate serialization format sections --- docs/guide/java/index.md | 237 +++++++++++++++++++++++---------------- 1 file changed, 142 insertions(+), 95 deletions(-) diff --git a/docs/guide/java/index.md b/docs/guide/java/index.md index 435c6574a3..e2a453eae4 100644 --- a/docs/guide/java/index.md +++ b/docs/guide/java/index.md @@ -33,9 +33,9 @@ JSON codec with its own object-mapping model. | **Fory JSON** | You need high-throughput standard JSON for Java applications | `org.apache.fory:fory-json` | [JSON Support](json-support.md) | | **Row Format** | You need zero-copy random access, partial reads, or Arrow integration | `org.apache.fory:fory-format` | [Row Format](row-format.md) | -## Features +## Binary Object Serialization -### Binary Object Serialization +### Features - **Generated Codecs**: JIT-generated serializers reduce virtual dispatch, branching, and metadata lookups on hot paths. @@ -46,17 +46,7 @@ JSON codec with its own object-mapping model. - **Object Graph Semantics**: Preserve shared and circular references, polymorphism, schema evolution, and deep-copy identity. -### Fory JSON - -- **Performance-First Codec**: Optimized readers and writers plus interpreted - and runtime-generated codecs keep JSON encoding and decoding fast. -- **Java Object Mapping**: Supports ordinary objects, Java 17 records, immutable - creator-based classes, common JDK types, generic containers, custom codecs, - and annotation-declared polymorphism. -- **String and UTF-8 APIs**: Read and write `String` and UTF-8 `byte[]` with one - immutable, thread-safe `ForyJson` instance. - -### Java Native Serialization +### Native Mode Features - **Framework Replacement**: Replace JDK serialization, Kryo, FST, Hessian, or Java-only Protocol Buffers payloads in Java-only systems. @@ -65,28 +55,12 @@ JSON codec with its own object-mapping model. - **Security Controls**: Class registration, type checking, depth limits, and configurable deserialization policies protect decoding boundaries. -### Row Format - -- **Zero-Copy Random Access**: Read fields and nested values without rebuilding - complete objects. -- **Partial Reads**: Decode only the data required by an analytics or query path. -- **Apache Arrow Integration**: Convert between Fory row data and Arrow data for - columnar processing. - -### Platforms - -- `fory-core` and `fory-json` support Java 8 and later; Java records require - Java 17 or later. -- `fory-format` targets Java 11 and later and is not supported on Android. -- `fory-core` and `fory-json` run on standard JDKs, GraalVM native images, and - Android API level 26 and later. - -## Installation +### Installation -Add the artifact for the format you use and keep all Fory modules on the same -version. `fory-json` includes `fory-core` transitively. +Add `fory-core` for binary object serialization. Keep all Fory modules in one +application on the same version. -### Maven +#### Maven ```xml @@ -95,27 +69,18 @@ version. `fory-json` includes `fory-core` transitively. fory-core 1.4.0 - - - - org.apache.fory - fory-json - 1.4.0 - ``` -### Gradle +#### Gradle ```kotlin // Binary object serialization implementation("org.apache.fory:fory-core:1.4.0") -// JSON serialization -implementation("org.apache.fory:fory-json:1.4.0") ``` -### JDK25+ +#### JDK 25 and Later -On JDK25+, open `java.lang.invoke` to Fory. Use `ALL-UNNAMED` when Fory is on +On JDK 25 and later, open `java.lang.invoke` to Fory. Use `ALL-UNNAMED` when Fory is on the classpath: ```bash @@ -128,11 +93,11 @@ Use the Fory core module name when Fory is on the module path: --add-opens=java.base/java.lang.invoke=org.apache.fory.core ``` -## Quick Start +### Quick Start Note that Fory creation is not cheap, the **Fory instances should be reused between serializations** instead of creating it every time. You should keep Fory as a static global variable, or instance variable of some singleton object or limited objects. -### Single-Thread Usage +#### Single-Thread Usage ```java import java.util.List; @@ -160,7 +125,7 @@ public class Example { } ``` -### Multi-Thread Usage +#### Multi-Thread Usage ```java import org.apache.fory.*; @@ -179,7 +144,7 @@ public class Example { } ``` -### Fory Instance Reuse Pattern +#### Fory Instance Reuse Pattern ```java import org.apache.fory.*; @@ -202,47 +167,7 @@ public class Example { } ``` -### Fory JSON - -`ForyJson` is immutable and thread-safe after construction. Reuse one instance -for both `String` and UTF-8 `byte[]` operations: - -```java -import org.apache.fory.json.ForyJson; - -public final class JsonExample { - private static final ForyJson JSON = ForyJson.builder().build(); - - public static final class User { - public long id; - public String name; - - public User() {} - - public User(long id, String name) { - this.id = id; - this.name = name; - } - } - - public static void main(String[] args) { - User input = new User(7, "Alice"); - - String text = JSON.toJson(input); - User fromText = JSON.fromJson(text, User.class); - - byte[] utf8 = JSON.toJsonBytes(input); - User fromUtf8 = JSON.fromJson(utf8, User.class); - - System.out.println(fromText.name + " / " + fromUtf8.name); - } -} -``` - -See [JSON Support](json-support.md) for supported types, annotations, custom -codecs, security controls, and platform setup. - -## Xlang Mode And Native Mode +### Xlang Mode And Native Mode Use xlang mode for cross-language payloads and schemas shared with non-Java implementations. It is the default Java wire mode, and Java examples that use it set `.withXlang(true)` explicitly so the mode choice is visible. @@ -250,11 +175,11 @@ Use native mode for Java-only traffic. Native mode is selected with `.withXlang( See [Native Serialization](native-serialization.md) for Java-only serialization details and [Xlang Serialization](xlang-serialization.md) for Java xlang registration and interoperability rules. -## Thread Safety +### Thread Safety Fory provides two thread-safe Fory instance styles: -### `buildThreadSafeFory` +#### `buildThreadSafeFory` This is the default choice. It uses a fixed-size shared `ThreadPoolFory` sized to `4 * availableProcessors()` and is the preferred instance form for virtual-thread workloads: @@ -269,7 +194,7 @@ ThreadSafeFory fory = Fory.builder() See more details in [Virtual Threads](virtual-threads.md). -### ThreadLocalFory +#### ThreadLocalFory Use `buildThreadLocalFory()` only when you explicitly want one `Fory` instance per long-lived platform thread, or when you want to pin that choice regardless of JDK version: @@ -283,7 +208,7 @@ byte[] bytes = fory.serialize(object); System.out.println(fory.deserialize(bytes)); ``` -### `buildThreadSafeForyPool` +#### `buildThreadSafeForyPool` Use `buildThreadSafeForyPool(poolSize)` when you want to set that fixed shared pool size explicitly. It eagerly creates `poolSize` `Fory` instances, keeps them in shared fixed slots, and @@ -298,7 +223,7 @@ ThreadSafeFory fory = Fory.builder() .buildThreadSafeForyPool(poolSize); ``` -### Builder Methods +#### Builder Methods ```java // Single-thread Fory @@ -321,6 +246,128 @@ ThreadSafeFory threadLocalFory = Fory.builder() .buildThreadLocalFory(); ``` +## Fory JSON + +Fory JSON is a separate, performance-first standard JSON codec for Java. It has +its own object-mapping annotations and limits and does not use Fory's native or +xlang binary wire format. + +### Features + +- **Performance-First Codec**: Optimized readers and writers plus interpreted + and runtime-generated codecs keep JSON encoding and decoding fast. +- **Java Object Mapping**: Supports ordinary objects, Java 17 records, immutable + creator-based classes, common JDK types, generic containers, custom codecs, + and annotation-declared polymorphism. +- **String and UTF-8 APIs**: Read and write `String` and UTF-8 `byte[]` with one + immutable, thread-safe `ForyJson` instance. + +### Installation + +`fory-json` includes `fory-core` transitively. Keep both modules on the same +version when another dependency also brings `fory-core` into the application. + +#### Maven + +```xml + + org.apache.fory + fory-json + 1.4.0 + +``` + +#### Gradle + +```kotlin +implementation("org.apache.fory:fory-json:1.4.0") +``` + +On JDK 25 and later, use the same `java.lang.invoke` module open described in +the binary serialization installation section. + +### Quick Start + +`ForyJson` is immutable and thread-safe after construction. Reuse one instance +for both `String` and UTF-8 `byte[]` operations: + +```java +import org.apache.fory.json.ForyJson; + +public final class JsonExample { + private static final ForyJson JSON = ForyJson.builder().build(); + + public static final class User { + public long id; + public String name; + + public User() {} + + public User(long id, String name) { + this.id = id; + this.name = name; + } + } + + public static void main(String[] args) { + User input = new User(7, "Alice"); + + String text = JSON.toJson(input); + User fromText = JSON.fromJson(text, User.class); + + byte[] utf8 = JSON.toJsonBytes(input); + User fromUtf8 = JSON.fromJson(utf8, User.class); + + System.out.println(fromText.name + " / " + fromUtf8.name); + } +} +``` + +See [JSON Support](json-support.md) for supported types, annotations, custom +codecs, security controls, and platform setup. + +## Row Format + +Fory row format is a separate cache-friendly binary format for random access, +partial reads, and analytics workloads. + +### Features + +- **Zero-Copy Random Access**: Read fields and nested values without rebuilding + complete objects. +- **Partial Reads**: Decode only the data required by an analytics or query path. +- **Apache Arrow Integration**: Convert between Fory row data and Arrow data for + columnar processing. + +### Installation + +#### Maven + +```xml + + org.apache.fory + fory-format + 1.4.0 + +``` + +#### Gradle + +```kotlin +implementation("org.apache.fory:fory-format:1.4.0") +``` + +See [Row Format](row-format.md) for encoding, typed field access, partial +deserialization, nested values, and Arrow integration. + +## Platform Support + +- `fory-core` and `fory-json` support Java 8 and later; Java records require + Java 17 or later. +- `fory-format` targets Java 11 and later and is not supported on Android. +- `fory-core` and `fory-json` run on standard JDKs, GraalVM native images, and + Android API level 26 and later. + ## Next Steps - [Configuration](configuration.md) - Learn about ForyBuilder options From 90f9337d3401e7e9164c2b599564f4e8dd4f5652 Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:37:41 +0800 Subject: [PATCH 11/19] docs(java): clarify format dependencies --- java/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/java/README.md b/java/README.md index e1fc68e4b3..85548e552d 100644 --- a/java/README.md +++ b/java/README.md @@ -106,7 +106,7 @@ aligned. `fory-json` includes `fory-core` transitively. 1.4.0 - + org.apache.fory fory-format @@ -127,9 +127,11 @@ aligned. `fory-json` includes `fory-core` transitively. dependencies { // Binary object serialization implementation 'org.apache.fory:fory-core:1.4.0' - // Add only the optional formats and extensions you use + // JSON serialization implementation 'org.apache.fory:fory-json:1.4.0' + // Row format implementation 'org.apache.fory:fory-format:1.4.0' + // Optional: Protobuf serializers and metadata compression implementation 'org.apache.fory:fory-extensions:1.4.0' } ``` From b1d98f92163538c7b2e25a863bca96f7b6889715 Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:38:17 +0800 Subject: [PATCH 12/19] docs(java): simplify Fory JSON introduction --- docs/guide/java/index.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/guide/java/index.md b/docs/guide/java/index.md index e2a453eae4..759ac47866 100644 --- a/docs/guide/java/index.md +++ b/docs/guide/java/index.md @@ -22,8 +22,8 @@ license: | Apache Fory™ Java provides high-performance binary object serialization, JSON serialization, and a random-access row format. Binary serialization supports xlang mode for cross-language payloads and native mode for Java-only object -graphs. [Fory JSON](json-support.md) is a separate, performance-first standard -JSON codec with its own object-mapping model. +graphs. [Fory JSON](json-support.md) provides high-performance standard JSON +serialization for Java applications. ## Choose a Format @@ -248,9 +248,8 @@ ThreadSafeFory threadLocalFory = Fory.builder() ## Fory JSON -Fory JSON is a separate, performance-first standard JSON codec for Java. It has -its own object-mapping annotations and limits and does not use Fory's native or -xlang binary wire format. +Fory JSON is a high-performance, thread-safe JSON serializer for Java, with +optimized APIs for both `String` and UTF-8 `byte[]`. ### Features From 0a7746d62b93b73fafe42cb02cb48950ecd05b29 Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:39:08 +0800 Subject: [PATCH 13/19] docs(java): correct Fory JSON positioning --- docs/guide/java/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guide/java/index.md b/docs/guide/java/index.md index 759ac47866..98da334101 100644 --- a/docs/guide/java/index.md +++ b/docs/guide/java/index.md @@ -22,8 +22,8 @@ license: | Apache Fory™ Java provides high-performance binary object serialization, JSON serialization, and a random-access row format. Binary serialization supports xlang mode for cross-language payloads and native mode for Java-only object -graphs. [Fory JSON](json-support.md) provides high-performance standard JSON -serialization for Java applications. +graphs. [Fory JSON](json-support.md) is a high-performance JSON serialization +framework for Java applications. ## Choose a Format @@ -248,8 +248,8 @@ ThreadSafeFory threadLocalFory = Fory.builder() ## Fory JSON -Fory JSON is a high-performance, thread-safe JSON serializer for Java, with -optimized APIs for both `String` and UTF-8 `byte[]`. +Fory JSON is a high-performance, thread-safe JSON serialization framework for +Java. It supports both `String` and UTF-8 `byte[]` input and output. ### Features From be8185fedccb2605b31f199472efcb3ff3e1e9bb Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:39:37 +0800 Subject: [PATCH 14/19] docs(java): focus Fory JSON overview --- docs/guide/java/index.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/guide/java/index.md b/docs/guide/java/index.md index 98da334101..c9a25c6808 100644 --- a/docs/guide/java/index.md +++ b/docs/guide/java/index.md @@ -249,7 +249,7 @@ ThreadSafeFory threadLocalFory = Fory.builder() ## Fory JSON Fory JSON is a high-performance, thread-safe JSON serialization framework for -Java. It supports both `String` and UTF-8 `byte[]` input and output. +Java. ### Features @@ -258,8 +258,6 @@ Java. It supports both `String` and UTF-8 `byte[]` input and output. - **Java Object Mapping**: Supports ordinary objects, Java 17 records, immutable creator-based classes, common JDK types, generic containers, custom codecs, and annotation-declared polymorphism. -- **String and UTF-8 APIs**: Read and write `String` and UTF-8 `byte[]` with one - immutable, thread-safe `ForyJson` instance. ### Installation @@ -288,7 +286,7 @@ the binary serialization installation section. ### Quick Start `ForyJson` is immutable and thread-safe after construction. Reuse one instance -for both `String` and UTF-8 `byte[]` operations: +across threads: ```java import org.apache.fory.json.ForyJson; From 61c5b14bc01017fe8d77fc23a424dd0fd8e34e43 Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:41:11 +0800 Subject: [PATCH 15/19] docs(java): strengthen Fory JSON performance positioning --- docs/guide/java/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/guide/java/index.md b/docs/guide/java/index.md index c9a25c6808..cada0d8922 100644 --- a/docs/guide/java/index.md +++ b/docs/guide/java/index.md @@ -248,8 +248,9 @@ ThreadSafeFory threadLocalFory = Fory.builder() ## Fory JSON -Fory JSON is a high-performance, thread-safe JSON serialization framework for -Java. +Fory JSON is a thread-safe JSON serialization framework for Java, extensively +optimized for maximum performance across JSON encoding, decoding, and Java +object mapping. ### Features From 98423d37b4be5448d302f88ec03c13303a379a6c Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:43:13 +0800 Subject: [PATCH 16/19] docs: align Fory JSON positioning --- README.md | 64 ++++++++++++++++++++++++++++---------------------- java/README.md | 47 +++++++++++++++++------------------- 2 files changed, 58 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 9e4cfa29d4..3bf006ec37 100644 --- a/README.md +++ b/README.md @@ -53,12 +53,12 @@ support broader language-specific object models: Fory also provides specialized formats for other data-processing requirements: -- **Row Format**: Read fields, arrays, and nested values without rebuilding - complete objects, with zero-copy access and partial reads. -- **High-Performance JSON Serialization for Java**: Built for maximum +- **Fory JSON**: A Java JSON serialization framework built for maximum throughput through runtime-generated codecs and optimized readers and writers. Supports Java 8 and later on standard JDKs, GraalVM native images, and Android, including Java 17 records. +- **Row Format**: Read fields, arrays, and nested values without rebuilding + complete objects, with zero-copy access and partial reads. ## Performance @@ -310,13 +310,14 @@ See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md). Snapshots for Java, Scala, and Kotlin are available from `https://repository.apache.org/snapshots/` with the matching `-SNAPSHOT` version. -## Choose Serialization Mode +## Choose a Serialization Format -| Mode | Use it when | Start here | -| ----------- | ------------------------------------------------------------- | -------------------------------------------------------- | -| Xlang mode | Data crosses language boundaries | [Cross-language guide](docs/guide/xlang) | -| Native mode | Producer and consumer are in the same language | Language guide | -| Row format | You need random field access or analytics-style partial reads | [Row format spec](docs/specification/row_format_spec.md) | +| Format | Use it when | Start here | +| ------------- | ------------------------------------------------------------- | -------------------------------------------------------- | +| Xlang binary | Data crosses language boundaries | [Cross-language guide](docs/guide/xlang) | +| Native binary | Producer and consumer are in the same language | Language guide | +| Fory JSON | Java applications need high-performance standard JSON | [Fory JSON guide](docs/guide/java/json-support.md) | +| Row format | You need random field access or analytics-style partial reads | [Row format spec](docs/specification/row_format_spec.md) | For Java, Scala, Kotlin, Python, C++, Go, and Rust, use native mode for same-language traffic. It avoids xlang's cross-language type mapping and @@ -743,12 +744,12 @@ native domain objects while all peers share the same Fory schema. See the complete type system, language-specific output options, schema evolution, and gRPC generation. -## JSON Serialization +## Fory JSON -Fory JSON is a high-performance, thread-safe JSON codec for Java. It combines -optimized readers and writers with runtime-generated codecs where available to -maximize throughput. It supports Java 8 and later on standard JDKs, GraalVM -native images, and Android, with Java records supported on Java 17 and later. +Fory JSON is a thread-safe JSON serialization framework for Java, extensively +optimized for maximum performance across JSON encoding, decoding, and Java +object mapping. It supports Java 8 and later on standard JDKs, GraalVM native +images, and Android, with Java records supported on Java 17 and later. Add `org.apache.fory:fory-json` with the same version as `fory-core`, then reuse one `ForyJson` instance across threads: @@ -756,26 +757,33 @@ one `ForyJson` instance across threads: ```java import org.apache.fory.json.ForyJson; -public class User { - public long id; - public String name; +public final class JsonExample { + private static final ForyJson JSON = ForyJson.builder().build(); + + public static final class User { + public long id; + public String name; - public User() {} + public User() {} - public User(long id, String name) { - this.id = id; - this.name = name; + public User(long id, String name) { + this.id = id; + this.name = name; + } } -} -ForyJson json = ForyJson.builder().build(); -User input = new User(7, "Alice"); + public static void main(String[] args) { + User input = new User(7, "Alice"); -String text = json.toJson(input); -User fromText = json.fromJson(text, User.class); + String text = JSON.toJson(input); + User fromText = JSON.fromJson(text, User.class); -byte[] bytes = json.toJsonBytes(input); -User fromBytes = json.fromJson(bytes, User.class); + byte[] bytes = JSON.toJsonBytes(input); + User fromBytes = JSON.fromJson(bytes, User.class); + + System.out.println(fromText.name + " / " + fromBytes.name); + } +} ``` See the [Fory JSON guide](docs/guide/java/json-support.md) for installation, diff --git a/java/README.md b/java/README.md index 85548e552d..ef80eb0997 100644 --- a/java/README.md +++ b/java/README.md @@ -12,7 +12,7 @@ serialization, and a random-access row format for the Java ecosystem. | Format | Use it when | Module | Guide | | ------------------------------- | -------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------- | | **Binary Object Serialization** | You need compact object graphs in Java native mode or across supported languages | `fory-core` | [Java guide](../docs/guide/java/) | -| **JSON Serialization** | You need high-throughput standard JSON for Java applications | `fory-json` | [Fory JSON guide](../docs/guide/java/json-support.md) | +| **Fory JSON** | You need high-throughput standard JSON for Java applications | `fory-json` | [Fory JSON guide](../docs/guide/java/json-support.md) | | **Row Format** | You need zero-copy random access, partial reads, or Arrow integration | `fory-format` | [Row-format guide](../docs/guide/java/row-format.md) | Keep all Fory modules in one application on the same version. @@ -34,15 +34,13 @@ Keep all Fory modules in one application on the same version. - **Security Controls**: Class registration, type checking, depth limits, and configurable deserialization policies protect decoding boundaries. -### JSON Serialization +### Fory JSON -- **Performance-First Codec**: Optimized readers and writers plus interpreted +- **Maximum Performance**: Optimized readers and writers plus interpreted and runtime-generated codecs keep JSON encoding and decoding fast. - **Java Object Mapping**: Supports ordinary objects, Java 17 records, immutable creator-based classes, common JDK types, generic containers, custom codecs, and annotation-declared polymorphism. -- **String and UTF-8 APIs**: Read and write both `String` and UTF-8 `byte[]` - without requiring separate mapper instances. - **Thread-Safe Runtime**: Build one immutable `ForyJson` instance and reuse it across threads. @@ -65,24 +63,24 @@ Keep all Fory modules in one application on the same version. ## Documentation -| Topic | Description | Source Doc Link | Website Doc Link | -| --------------------------- | ----------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | -| **Java Guide** | Binary xlang and native mode usage | [docs/guide/java](../docs/guide/java) | [Java Guide](https://fory.apache.org/docs/guide/java/) | -| **Fory JSON** | JSON installation, APIs, and types | [json-support.md](../docs/guide/java/json-support.md) | [Fory JSON](https://fory.apache.org/docs/guide/java/json_support) | -| **Row Format** | Random access and Arrow integration | [row-format.md](../docs/guide/java/row-format.md) | [Row Format](https://fory.apache.org/docs/guide/java/row_format) | -| **GraalVM Native Image** | Native image support | [graalvm-support.md](../docs/guide/java/graalvm-support.md) | [GraalVM Support](https://fory.apache.org/docs/guide/java/graalvm_support) | -| **Java Serialization Spec** | Binary protocol specification | [java_serialization_spec.md](../docs/specification/java_serialization_spec.md) | [Java Serialization Spec](https://fory.apache.org/docs/specification/java_serialization_spec) | -| **Java Benchmarks** | Performance data and plots | [java/README.md](../docs/benchmarks/java/README.md) | [Java Benchmarks](https://fory.apache.org/docs/benchmarks/java) | +| Topic | Description | Source Doc Link | Website Doc Link | +| --------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | +| **Java Guide** | Binary xlang and native mode usage | [docs/guide/java](../docs/guide/java) | [Java Guide](https://fory.apache.org/docs/guide/java/) | +| **Fory JSON** | JSON usage, object mapping, and configuration | [json-support.md](../docs/guide/java/json-support.md) | [Fory JSON](https://fory.apache.org/docs/guide/java/json_support) | +| **Row Format** | Random access and Arrow integration | [row-format.md](../docs/guide/java/row-format.md) | [Row Format](https://fory.apache.org/docs/guide/java/row_format) | +| **GraalVM Native Image** | Native image support | [graalvm-support.md](../docs/guide/java/graalvm-support.md) | [GraalVM Support](https://fory.apache.org/docs/guide/java/graalvm_support) | +| **Java Serialization Spec** | Binary protocol specification | [java_serialization_spec.md](../docs/specification/java_serialization_spec.md) | [Java Serialization Spec](https://fory.apache.org/docs/specification/java_serialization_spec) | +| **Java Benchmarks** | Performance data and plots | [java/README.md](../docs/benchmarks/java/README.md) | [Java Benchmarks](https://fory.apache.org/docs/benchmarks/java) | ## Modules -| Module | Description | Maven Artifact | -| ------------------------------------ | ----------------------------------------- | --------------------------------- | -| **fory-core** | Binary native and xlang serialization | `org.apache.fory:fory-core` | -| [**fory-json**](fory-json/README.md) | High-performance JSON codec | `org.apache.fory:fory-json` | -| **fory-format** | Row format and Apache Arrow support | `org.apache.fory:fory-format` | -| **fory-extensions** | Protobuf support and metadata compression | `org.apache.fory:fory-extensions` | -| **fory-test-core** | Testing utilities and data generators | `org.apache.fory:fory-test-core` | +| Module | Description | Maven Artifact | +| ------------------------------------ | --------------------------------------------- | --------------------------------- | +| **fory-core** | Binary native and xlang serialization | `org.apache.fory:fory-core` | +| [**fory-json**](fory-json/README.md) | High-performance JSON serialization framework | `org.apache.fory:fory-json` | +| **fory-format** | Row format and Apache Arrow support | `org.apache.fory:fory-format` | +| **fory-extensions** | Protobuf support and metadata compression | `org.apache.fory:fory-extensions` | +| **fory-test-core** | Testing utilities and data generators | `org.apache.fory:fory-test-core` | ## Installation @@ -376,12 +374,11 @@ java --add-modules=jdk.incubator.vector ... measuring the payload distribution and throughput tradeoff. 7. Warm up generated serializers before measuring steady-state performance. -## JSON Serialization +## Fory JSON -Fory JSON is a performance-first, thread-safe JSON codec for Java. Optimized -readers and writers handle `String` and UTF-8 `byte[]` directly, while -runtime-generated codecs accelerate object mapping where runtime code generation -is available. +Fory JSON is a thread-safe JSON serialization framework for Java, extensively +optimized for maximum performance across JSON encoding, decoding, and Java +object mapping. Build one `ForyJson` instance and reuse it across threads: From cff1d0d6d33cc3f0866b90df57e30a1463c217f5 Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:49:09 +0800 Subject: [PATCH 17/19] docs: prioritize cross-language row format --- README.md | 96 ++++++++++++++-------------- docs/guide/java/index.md | 84 ++++++++++++------------- java/README.md | 131 ++++++++++++++++++++------------------- 3 files changed, 156 insertions(+), 155 deletions(-) diff --git a/README.md b/README.md index 3bf006ec37..ad9f763dc2 100644 --- a/README.md +++ b/README.md @@ -53,12 +53,12 @@ support broader language-specific object models: Fory also provides specialized formats for other data-processing requirements: +- **Row Format**: Read fields, arrays, and nested values without rebuilding + complete objects, with zero-copy access and partial reads. - **Fory JSON**: A Java JSON serialization framework built for maximum throughput through runtime-generated codecs and optimized readers and writers. Supports Java 8 and later on standard JDKs, GraalVM native images, and Android, including Java 17 records. -- **Row Format**: Read fields, arrays, and nested values without rebuilding - complete objects, with zero-copy access and partial reads. ## Performance @@ -316,8 +316,8 @@ Snapshots for Java, Scala, and Kotlin are available from | ------------- | ------------------------------------------------------------- | -------------------------------------------------------- | | Xlang binary | Data crosses language boundaries | [Cross-language guide](docs/guide/xlang) | | Native binary | Producer and consumer are in the same language | Language guide | -| Fory JSON | Java applications need high-performance standard JSON | [Fory JSON guide](docs/guide/java/json-support.md) | | Row format | You need random field access or analytics-style partial reads | [Row format spec](docs/specification/row_format_spec.md) | +| Fory JSON | Java applications need high-performance standard JSON | [Fory JSON guide](docs/guide/java/json-support.md) | For Java, Scala, Kotlin, Python, C++, Go, and Rust, use native mode for same-language traffic. It avoids xlang's cross-language type mapping and @@ -744,51 +744,6 @@ native domain objects while all peers share the same Fory schema. See the complete type system, language-specific output options, schema evolution, and gRPC generation. -## Fory JSON - -Fory JSON is a thread-safe JSON serialization framework for Java, extensively -optimized for maximum performance across JSON encoding, decoding, and Java -object mapping. It supports Java 8 and later on standard JDKs, GraalVM native -images, and Android, with Java records supported on Java 17 and later. - -Add `org.apache.fory:fory-json` with the same version as `fory-core`, then reuse -one `ForyJson` instance across threads: - -```java -import org.apache.fory.json.ForyJson; - -public final class JsonExample { - private static final ForyJson JSON = ForyJson.builder().build(); - - public static final class User { - public long id; - public String name; - - public User() {} - - public User(long id, String name) { - this.id = id; - this.name = name; - } - } - - public static void main(String[] args) { - User input = new User(7, "Alice"); - - String text = JSON.toJson(input); - User fromText = JSON.fromJson(text, User.class); - - byte[] bytes = JSON.toJsonBytes(input); - User fromBytes = JSON.fromJson(bytes, User.class); - - System.out.println(fromText.name + " / " + fromBytes.name); - } -} -``` - -See the [Fory JSON guide](docs/guide/java/json-support.md) for installation, -configuration, supported types, custom codecs, and platform-specific setup. - ## Row Format Row format is for random access and partial reads. These examples encode an @@ -850,6 +805,51 @@ deserialization, see the [Python row-format guide](docs/guide/python/row-format.md), and the [row-format specification](docs/specification/row_format_spec.md). +## Fory JSON + +Fory JSON is a thread-safe JSON serialization framework for Java, extensively +optimized for maximum performance across JSON encoding, decoding, and Java +object mapping. It supports Java 8 and later on standard JDKs, GraalVM native +images, and Android, with Java records supported on Java 17 and later. + +Add `org.apache.fory:fory-json` with the same version as `fory-core`, then reuse +one `ForyJson` instance across threads: + +```java +import org.apache.fory.json.ForyJson; + +public final class JsonExample { + private static final ForyJson JSON = ForyJson.builder().build(); + + public static final class User { + public long id; + public String name; + + public User() {} + + public User(long id, String name) { + this.id = id; + this.name = name; + } + } + + public static void main(String[] args) { + User input = new User(7, "Alice"); + + String text = JSON.toJson(input); + User fromText = JSON.fromJson(text, User.class); + + byte[] bytes = JSON.toJsonBytes(input); + User fromBytes = JSON.fromJson(bytes, User.class); + + System.out.println(fromText.name + " / " + fromBytes.name); + } +} +``` + +See the [Fory JSON guide](docs/guide/java/json-support.md) for installation, +configuration, supported types, custom codecs, and platform-specific setup. + ## Documentation **User Guides** diff --git a/docs/guide/java/index.md b/docs/guide/java/index.md index cada0d8922..0daa4058a6 100644 --- a/docs/guide/java/index.md +++ b/docs/guide/java/index.md @@ -19,19 +19,19 @@ license: | limitations under the License. --- -Apache Fory™ Java provides high-performance binary object serialization, JSON -serialization, and a random-access row format. Binary serialization supports -xlang mode for cross-language payloads and native mode for Java-only object -graphs. [Fory JSON](json-support.md) is a high-performance JSON serialization -framework for Java applications. +Apache Fory™ Java provides high-performance binary object serialization, a +cross-language random-access row format, and JSON serialization for Java. +Binary serialization supports xlang mode for cross-language payloads and native +mode for Java-only object graphs. [Fory JSON](json-support.md) is a +high-performance JSON serialization framework for Java applications. ## Choose a Format | Format | Use it when | Artifact | Start here | | ------------------------------- | -------------------------------------------------------------------------------- | ----------------------------- | --------------------------------------------- | | **Binary Object Serialization** | You need compact object graphs in Java native mode or across supported languages | `org.apache.fory:fory-core` | [Basic Serialization](basic-serialization.md) | -| **Fory JSON** | You need high-throughput standard JSON for Java applications | `org.apache.fory:fory-json` | [JSON Support](json-support.md) | | **Row Format** | You need zero-copy random access, partial reads, or Arrow integration | `org.apache.fory:fory-format` | [Row Format](row-format.md) | +| **Fory JSON** | You need high-throughput standard JSON for Java applications | `org.apache.fory:fory-json` | [JSON Support](json-support.md) | ## Binary Object Serialization @@ -246,6 +246,40 @@ ThreadSafeFory threadLocalFory = Fory.builder() .buildThreadLocalFory(); ``` +## Row Format + +Fory row format is a separate cache-friendly binary format for random access, +partial reads, and analytics workloads. + +### Features + +- **Zero-Copy Random Access**: Read fields and nested values without rebuilding + complete objects. +- **Partial Reads**: Decode only the data required by an analytics or query path. +- **Apache Arrow Integration**: Convert between Fory row data and Arrow data for + columnar processing. + +### Installation + +#### Maven + +```xml + + org.apache.fory + fory-format + 1.4.0 + +``` + +#### Gradle + +```kotlin +implementation("org.apache.fory:fory-format:1.4.0") +``` + +See [Row Format](row-format.md) for encoding, typed field access, partial +deserialization, nested values, and Arrow integration. + ## Fory JSON Fory JSON is a thread-safe JSON serialization framework for Java, extensively @@ -254,8 +288,8 @@ object mapping. ### Features -- **Performance-First Codec**: Optimized readers and writers plus interpreted - and runtime-generated codecs keep JSON encoding and decoding fast. +- **Maximum Performance**: Optimized readers and writers plus interpreted and + runtime-generated codecs keep JSON encoding and decoding fast. - **Java Object Mapping**: Supports ordinary objects, Java 17 records, immutable creator-based classes, common JDK types, generic containers, custom codecs, and annotation-declared polymorphism. @@ -324,40 +358,6 @@ public final class JsonExample { See [JSON Support](json-support.md) for supported types, annotations, custom codecs, security controls, and platform setup. -## Row Format - -Fory row format is a separate cache-friendly binary format for random access, -partial reads, and analytics workloads. - -### Features - -- **Zero-Copy Random Access**: Read fields and nested values without rebuilding - complete objects. -- **Partial Reads**: Decode only the data required by an analytics or query path. -- **Apache Arrow Integration**: Convert between Fory row data and Arrow data for - columnar processing. - -### Installation - -#### Maven - -```xml - - org.apache.fory - fory-format - 1.4.0 - -``` - -#### Gradle - -```kotlin -implementation("org.apache.fory:fory-format:1.4.0") -``` - -See [Row Format](row-format.md) for encoding, typed field access, partial -deserialization, nested values, and Arrow integration. - ## Platform Support - `fory-core` and `fory-json` support Java 8 and later; Java records require diff --git a/java/README.md b/java/README.md index ef80eb0997..67e97fa675 100644 --- a/java/README.md +++ b/java/README.md @@ -4,16 +4,17 @@ [![Java Version](https://img.shields.io/badge/Java-8%2B-blue?style=for-the-badge)](https://www.oracle.com/java/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge)](https://opensource.org/licenses/Apache-2.0) -Apache Fory™ Java provides high-performance binary object serialization, JSON -serialization, and a random-access row format for the Java ecosystem. +Apache Fory™ Java provides high-performance binary object serialization, a +cross-language random-access row format, and JSON serialization for the Java +ecosystem. ## Choose a Format | Format | Use it when | Module | Guide | | ------------------------------- | -------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------- | | **Binary Object Serialization** | You need compact object graphs in Java native mode or across supported languages | `fory-core` | [Java guide](../docs/guide/java/) | -| **Fory JSON** | You need high-throughput standard JSON for Java applications | `fory-json` | [Fory JSON guide](../docs/guide/java/json-support.md) | | **Row Format** | You need zero-copy random access, partial reads, or Arrow integration | `fory-format` | [Row-format guide](../docs/guide/java/row-format.md) | +| **Fory JSON** | You need high-throughput standard JSON for Java applications | `fory-json` | [Fory JSON guide](../docs/guide/java/json-support.md) | Keep all Fory modules in one application on the same version. @@ -34,6 +35,14 @@ Keep all Fory modules in one application on the same version. - **Security Controls**: Class registration, type checking, depth limits, and configurable deserialization policies protect decoding boundaries. +### Row Format + +- **Zero-Copy Random Access**: Read fields and nested values without rebuilding + complete objects. +- **Partial Reads**: Decode only the data required by an analytics or query path. +- **Apache Arrow Integration**: Convert between Fory row data and Arrow data for + columnar processing. + ### Fory JSON - **Maximum Performance**: Optimized readers and writers plus interpreted @@ -44,14 +53,6 @@ Keep all Fory modules in one application on the same version. - **Thread-Safe Runtime**: Build one immutable `ForyJson` instance and reuse it across threads. -### Row Format - -- **Zero-Copy Random Access**: Read fields and nested values without rebuilding - complete objects. -- **Partial Reads**: Decode only the data required by an analytics or query path. -- **Apache Arrow Integration**: Convert between Fory row data and Arrow data for - columnar processing. - ### Platforms - `fory-core` and `fory-json` support Java 8 and later; Java records require @@ -66,8 +67,8 @@ Keep all Fory modules in one application on the same version. | Topic | Description | Source Doc Link | Website Doc Link | | --------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | | **Java Guide** | Binary xlang and native mode usage | [docs/guide/java](../docs/guide/java) | [Java Guide](https://fory.apache.org/docs/guide/java/) | -| **Fory JSON** | JSON usage, object mapping, and configuration | [json-support.md](../docs/guide/java/json-support.md) | [Fory JSON](https://fory.apache.org/docs/guide/java/json_support) | | **Row Format** | Random access and Arrow integration | [row-format.md](../docs/guide/java/row-format.md) | [Row Format](https://fory.apache.org/docs/guide/java/row_format) | +| **Fory JSON** | JSON usage, object mapping, and configuration | [json-support.md](../docs/guide/java/json-support.md) | [Fory JSON](https://fory.apache.org/docs/guide/java/json_support) | | **GraalVM Native Image** | Native image support | [graalvm-support.md](../docs/guide/java/graalvm-support.md) | [GraalVM Support](https://fory.apache.org/docs/guide/java/graalvm_support) | | **Java Serialization Spec** | Binary protocol specification | [java_serialization_spec.md](../docs/specification/java_serialization_spec.md) | [Java Serialization Spec](https://fory.apache.org/docs/specification/java_serialization_spec) | | **Java Benchmarks** | Performance data and plots | [java/README.md](../docs/benchmarks/java/README.md) | [Java Benchmarks](https://fory.apache.org/docs/benchmarks/java) | @@ -77,8 +78,8 @@ Keep all Fory modules in one application on the same version. | Module | Description | Maven Artifact | | ------------------------------------ | --------------------------------------------- | --------------------------------- | | **fory-core** | Binary native and xlang serialization | `org.apache.fory:fory-core` | -| [**fory-json**](fory-json/README.md) | High-performance JSON serialization framework | `org.apache.fory:fory-json` | | **fory-format** | Row format and Apache Arrow support | `org.apache.fory:fory-format` | +| [**fory-json**](fory-json/README.md) | High-performance JSON serialization framework | `org.apache.fory:fory-json` | | **fory-extensions** | Protobuf support and metadata compression | `org.apache.fory:fory-extensions` | | **fory-test-core** | Testing utilities and data generators | `org.apache.fory:fory-test-core` | @@ -97,17 +98,17 @@ aligned. `fory-json` includes `fory-core` transitively. 1.4.0 - + org.apache.fory - fory-json + fory-format 1.4.0 - + org.apache.fory - fory-format + fory-json 1.4.0 @@ -125,10 +126,10 @@ aligned. `fory-json` includes `fory-core` transitively. dependencies { // Binary object serialization implementation 'org.apache.fory:fory-core:1.4.0' - // JSON serialization - implementation 'org.apache.fory:fory-json:1.4.0' // Row format implementation 'org.apache.fory:fory-format:1.4.0' + // JSON serialization + implementation 'org.apache.fory:fory-json:1.4.0' // Optional: Protobuf serializers and metadata compression implementation 'org.apache.fory:fory-extensions:1.4.0' } @@ -374,6 +375,52 @@ java --add-modules=jdk.incubator.vector ... measuring the payload distribution and throughput tradeoff. 7. Warm up generated serializers before measuring steady-state performance. +## Row Format + +Fory row format is a cache-friendly binary format for random access and +analytics. It can read fields, arrays, and nested values without rebuilding the +complete object. + +```java +import org.apache.fory.format.encoder.Encoders; +import org.apache.fory.format.encoder.RowEncoder; +import org.apache.fory.format.row.ArrayData; +import org.apache.fory.format.row.binary.BinaryRow; +import org.apache.fory.format.type.Schema; + +public final class RowExample { + public static final class User { + public int id; + public String name; + public int[] scores; + } + + public static void main(String[] args) { + RowEncoder encoder = Encoders.bean(User.class); + + User user = new User(); + user.id = 1; + user.name = "Alice"; + user.scores = new int[] {98, 100, 95}; + + BinaryRow row = encoder.toRow(user); + + Schema schema = encoder.schema(); + Schema.StringField nameField = schema.stringField("name"); + Schema.ArrayField scoresField = schema.arrayField("scores"); + + String name = nameField.get(row); + ArrayData scores = scoresField.get(row); + int secondScore = scores.getInt32(1); + + System.out.println(name + ": " + secondScore); + } +} +``` + +See the [Java row-format guide](../docs/guide/java/row-format.md) for nested +structs, arrays, maps, partial deserialization, and Arrow integration. + ## Fory JSON Fory JSON is a thread-safe JSON serialization framework for Java, extensively @@ -422,52 +469,6 @@ and Android. Java records are supported on Java 17 and later. See the [Fory JSON guide](../docs/guide/java/json-support.md) for supported types, annotations, custom codecs, security controls, and platform setup. -## Row Format - -Fory row format is a cache-friendly binary format for random access and -analytics. It can read fields, arrays, and nested values without rebuilding the -complete object. - -```java -import org.apache.fory.format.encoder.Encoders; -import org.apache.fory.format.encoder.RowEncoder; -import org.apache.fory.format.row.ArrayData; -import org.apache.fory.format.row.binary.BinaryRow; -import org.apache.fory.format.type.Schema; - -public final class RowExample { - public static final class User { - public int id; - public String name; - public int[] scores; - } - - public static void main(String[] args) { - RowEncoder encoder = Encoders.bean(User.class); - - User user = new User(); - user.id = 1; - user.name = "Alice"; - user.scores = new int[] {98, 100, 95}; - - BinaryRow row = encoder.toRow(user); - - Schema schema = encoder.schema(); - Schema.StringField nameField = schema.stringField("name"); - Schema.ArrayField scoresField = schema.arrayField("scores"); - - String name = nameField.get(row); - ArrayData scores = scoresField.get(row); - int secondScore = scores.getInt32(1); - - System.out.println(name + ": " + secondScore); - } -} -``` - -See the [Java row-format guide](../docs/guide/java/row-format.md) for nested -structs, arrays, maps, partial deserialization, and Arrow integration. - ## GraalVM Native Image Fory supports GraalVM Native Image without application reflection configuration. Binary From 72f26044fbac3b2281e83897d6077df126778899 Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:50:03 +0800 Subject: [PATCH 18/19] docs: add Fory JSON dependency examples --- README.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ad9f763dc2..fc31132c57 100644 --- a/README.md +++ b/README.md @@ -812,8 +812,26 @@ optimized for maximum performance across JSON encoding, decoding, and Java object mapping. It supports Java 8 and later on standard JDKs, GraalVM native images, and Android, with Java records supported on Java 17 and later. -Add `org.apache.fory:fory-json` with the same version as `fory-core`, then reuse -one `ForyJson` instance across threads: +Add Fory JSON to your project: + +**Maven** + +```xml + + org.apache.fory + fory-json + 1.4.0 + +``` + +**Gradle** + +```gradle +implementation "org.apache.fory:fory-json:1.4.0" +``` + +Keep all Fory modules in the same application on the same version. Build one +`ForyJson` instance and reuse it across threads: ```java import org.apache.fory.json.ForyJson; From 3545c649a4b86aa97e73d4b28ad3e402db40bb9a Mon Sep 17 00:00:00 2001 From: chaokunyang Date: Mon, 20 Jul 2026 11:51:03 +0800 Subject: [PATCH 19/19] docs: label Fory JSON quick start --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fc31132c57..e358a480c6 100644 --- a/README.md +++ b/README.md @@ -830,8 +830,11 @@ Add Fory JSON to your project: implementation "org.apache.fory:fory-json:1.4.0" ``` -Keep all Fory modules in the same application on the same version. Build one -`ForyJson` instance and reuse it across threads: +Keep all Fory modules in the same application on the same version. + +**Quick Start** + +Build one `ForyJson` instance and reuse it across threads: ```java import org.apache.fory.json.ForyJson;