This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory-site.git
The following commit(s) were added to refs/heads/main by this push:
new 258f48931 π synced local 'docs/docs/guide/' with remote 'docs/guide/'
258f48931 is described below
commit 258f48931f9089b45e7590a0e4dbc8c0545ed6d9
Author: chaokunyang <[email protected]>
AuthorDate: Tue Oct 28 16:36:54 2025 +0000
π synced local 'docs/docs/guide/' with remote 'docs/guide/'
---
docs/docs/guide/graalvm_guide.md | 2 +-
docs/docs/guide/java_serialization_guide.md | 210 +++++++++++++++++++++++++++
docs/docs/guide/row_format_guide.md | 2 +-
docs/docs/guide/scala_guide.md | 2 +-
docs/docs/guide/xlang_serialization_guide.md | 2 +-
5 files changed, 214 insertions(+), 4 deletions(-)
diff --git a/docs/docs/guide/graalvm_guide.md b/docs/docs/guide/graalvm_guide.md
index 88b005552..3f85c2c70 100644
--- a/docs/docs/guide/graalvm_guide.md
+++ b/docs/docs/guide/graalvm_guide.md
@@ -1,7 +1,7 @@
---
title: GraalVM Guide
sidebar_position: 6
-id: graalvm_guide
+id: graalvm_serialization
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
diff --git a/docs/docs/guide/java_serialization_guide.md
b/docs/docs/guide/java_serialization_guide.md
index e7e538c0e..0a9f68bfa 100644
--- a/docs/docs/guide/java_serialization_guide.md
+++ b/docs/docs/guide/java_serialization_guide.md
@@ -309,8 +309,217 @@ SomeClass a = xxx;
SomeClass copied = fory.copy(a);
```
+### Cross-Language Serialization
+
+Apache Foryβ’ supports seamless data exchange between Java and other languages
(Python, Rust, Go, JavaScript, etc.) through the xlang serialization format.
This enables multi-language microservices, polyglot data pipelines, and
cross-platform data sharing.
+
+#### Enable Cross-Language Mode
+
+To serialize data for consumption by other languages, use `Language.XLANG`
mode:
+
+```java
+import org.apache.fory.*;
+import org.apache.fory.config.*;
+
+// Create Fory instance with XLANG mode
+Fory fory = Fory.builder()
+ .withLanguage(Language.XLANG)
+ .withRefTracking(true) // Enable reference tracking for complex graphs
+ .build();
+```
+
+#### Register Types for Cross-Language Compatibility
+
+Types must be registered with **consistent IDs or names** across all
languages. Fory supports two registration methods:
+
+**1. Register by ID (Recommended for Performance)**
+
+```java
+public record Person(String name, int age) {}
+
+// Register with numeric ID - faster and more compact
+fory.register(Person.class, 1);
+
+Person person = new Person("Alice", 30);
+byte[] bytes = fory.serialize(person);
+// bytes can be deserialized by Python, Rust, Go, etc.
+```
+
+**Benefits**: Faster serialization, smaller binary size
+**Trade-offs**: Requires coordination to avoid ID conflicts across
teams/services
+
+**2. Register by Name (Recommended for Flexibility)**
+
+```java
+public record Person(String name, int age) {}
+
+// Register with string name - more flexible
+fory.register(Person.class, "example.Person");
+
+Person person = new Person("Alice", 30);
+byte[] bytes = fory.serialize(person);
+// bytes can be deserialized by Python, Rust, Go, etc.
+```
+
+**Benefits**: Less prone to conflicts, easier management across teams, no
coordination needed
+**Trade-offs**: Slightly larger binary size due to string encoding
+
+#### Cross-Language Example: Java β Python
+
+**Java (Serializer)**
+
+```java
+import org.apache.fory.*;
+import org.apache.fory.config.*;
+
+public record Person(String name, int age) {}
+
+public class Example {
+ public static void main(String[] args) {
+ Fory fory = Fory.builder()
+ .withLanguage(Language.XLANG)
+ .withRefTracking(true)
+ .build();
+
+ // Register with consistent name
+ fory.register(Person.class, "example.Person");
+
+ Person person = new Person("Bob", 25);
+ byte[] bytes = fory.serialize(person);
+
+ // Send bytes to Python service via network/file/queue
+ }
+}
+```
+
+**Python (Deserializer)**
+
+```python
+import pyfory
+from dataclasses import dataclass
+
+@dataclass
+class Person:
+ name: str
+ age: pyfory.int32
+
+# Create Fory in xlang mode
+fory = pyfory.Fory(ref_tracking=True)
+
+# Register with the SAME name as Java
+fory.register_type(Person, typename="example.Person")
+
+# Deserialize bytes from Java
+person = fory.deserialize(bytes_from_java)
+print(f"{person.name}, {person.age}") # Output: Bob, 25
+```
+
+#### Handling Circular and Shared References
+
+Cross-language mode supports circular and shared references when reference
tracking is enabled:
+
+```java
+public class Node {
+ public String value;
+ public Node next;
+ public Node parent;
+}
+
+Fory fory = Fory.builder()
+ .withLanguage(Language.XLANG)
+ .withRefTracking(true) // Required for circular references
+ .build();
+
+fory.register(Node.class, "example.Node");
+
+// Create circular reference
+Node node1 = new Node();
+node1.value = "A";
+Node node2 = new Node();
+node2.value = "B";
+node1.next = node2;
+node2.parent = node1; // Circular reference
+
+byte[] bytes = fory.serialize(node1);
+// Python/Rust/Go can correctly deserialize this with circular references
preserved
+```
+
+#### Type Mapping Considerations
+
+Not all Java types have equivalents in other languages. When using xlang mode:
+
+- Use **primitive types** (`int`, `long`, `double`, `String`) for maximum
compatibility
+- Use **standard collections** (`List`, `Map`, `Set`) instead of
language-specific ones
+- Avoid **Java-specific types** like `Optional`, `BigDecimal` (unless the
target language supports them)
+- See [Type Mapping Guide](../specification/xlang_type_mapping.md) for
complete compatibility matrix
+
+**Compatible Types**:
+
+```java
+public record UserData(
+ String name, // β
Compatible
+ int age, // β
Compatible
+ List<String> tags, // β
Compatible
+ Map<String, Integer> scores // β
Compatible
+) {}
+```
+
+**Problematic Types**:
+
+```java
+public record UserData(
+ Optional<String> name, // β Not cross-language compatible
+ BigDecimal balance, // β Limited support
+ EnumSet<Status> statuses // β Java-specific collection
+) {}
+```
+
+#### Performance Considerations
+
+Cross-language mode has additional overhead compared to Java-only mode:
+
+- **Type metadata encoding**: Adds extra bytes per type
+- **Type resolution**: Requires name/ID lookup during deserialization
+
+**For best performance**:
+
+- Use **ID-based registration** when possible (smaller encoding)
+- **Disable reference tracking** if you don't need circular references
(`withRefTracking(false)`)
+- **Use Java mode** (`Language.JAVA`) when only Java serialization is needed
+
+#### Cross-Language Best Practices
+
+1. **Consistent Registration**: Ensure all services register types with
identical IDs/names
+2. **Version Compatibility**: Use compatible mode for schema evolution across
services
+
+#### Troubleshooting Cross-Language Serialization
+
+**"Type not registered" errors**:
+
+- Verify type is registered with same ID/name on both sides
+- Check if type name has typos or case differences
+
+**"Type mismatch" errors**:
+
+- Ensure field types are compatible across languages
+- Review [Type Mapping
Guide](https://fory.apache.org/docs/next/specification/xlang_type_mapping)
+
+**Data corruption or unexpected values**:
+
+- Verify both sides use `Language.XLANG` mode
+- Ensure both sides have compatible Fory versions
+
+**See Also**:
+
+- [Cross-Language Serialization
Specification](https://fory.apache.org/docs/next/specification/fory_xlang_serialization_spec)
+- [Type Mapping
Reference](https://fory.apache.org/docs/next/specification/xlang_type_mapping)
+- [Python Cross-Language Guide](python_guide.md#cross-language-serialization)
+- [Rust Cross-Language Guide](rust_guide.md#-cross-language-serialization)
+
### Implement a customized serializer
+````
+
In some cases, you may want to implement a serializer for your type,
especially some class customize serialization by
JDK `writeObject/writeReplace/readObject/readResolve`, which is very
inefficient. For example, if you don't want
following `Foo#writeObject` got invoked, you can take following
`FooSerializer` as an example:
@@ -1537,3 +1746,4 @@ deserialization instead of
`Fory#deserializeJavaObjectAndClass`/`Fory#deserializ
If you serialize an object by invoking `Fory#serializeJavaObjectAndClass`, you
should
invoke `Fory#deserializeJavaObjectAndClass` for deserialization instead
of `Fory#deserializeJavaObject`/`Fory#deserialize`.
+````
diff --git a/docs/docs/guide/row_format_guide.md
b/docs/docs/guide/row_format_guide.md
index a2526c1fe..ec6df6d63 100644
--- a/docs/docs/guide/row_format_guide.md
+++ b/docs/docs/guide/row_format_guide.md
@@ -1,7 +1,7 @@
---
title: Row Format Guide
sidebar_position: 5
-id: row_format_guide
+id: row_format
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
diff --git a/docs/docs/guide/scala_guide.md b/docs/docs/guide/scala_guide.md
index 29da5ee33..1070a5ac5 100644
--- a/docs/docs/guide/scala_guide.md
+++ b/docs/docs/guide/scala_guide.md
@@ -1,7 +1,7 @@
---
title: Scala Serialization Guide
sidebar_position: 3
-id: scala_guide
+id: scala_serialization
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
diff --git a/docs/docs/guide/xlang_serialization_guide.md
b/docs/docs/guide/xlang_serialization_guide.md
index 331440b0f..a5715a60a 100644
--- a/docs/docs/guide/xlang_serialization_guide.md
+++ b/docs/docs/guide/xlang_serialization_guide.md
@@ -1,7 +1,7 @@
---
title: Xlang Serialization Guide
sidebar_position: 4
-id: xlang_object_graph_guide
+id: xlang_serialization
license: |
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
