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
commit 6983b5cd7c776a0a6f675afe6acab0bd4bd95558 Author: chaokunyang <[email protected]> AuthorDate: Sun Apr 12 10:21:41 2026 +0000 π synced local 'docs/guide/' with remote 'docs/guide/' --- docs/guide/csharp/configuration.md | 14 +---- docs/guide/csharp/cross-language.md | 8 +-- docs/guide/csharp/troubleshooting.md | 10 +-- docs/guide/go/codegen.md | 22 +++---- docs/guide/go/index.md | 17 ++--- docs/guide/java/advanced-features.md | 2 +- docs/guide/java/compression.md | 2 +- docs/guide/java/configuration.md | 4 +- docs/guide/java/cross-language.md | 2 +- docs/guide/java/enum-configuration.md | 111 +++++++++++++++++++++++++++++++++ docs/guide/java/field-configuration.md | 2 + docs/guide/java/index.md | 3 + docs/guide/java/migration.md | 2 +- docs/guide/java/row-format.md | 2 +- docs/guide/java/schema-evolution.md | 2 +- docs/guide/java/troubleshooting.md | 2 +- docs/guide/java/virtual-threads.md | 2 +- 17 files changed, 156 insertions(+), 51 deletions(-) diff --git a/docs/guide/csharp/configuration.md b/docs/guide/csharp/configuration.md index 0b75b2ee4a..9d35ae0e5e 100644 --- a/docs/guide/csharp/configuration.md +++ b/docs/guide/csharp/configuration.md @@ -20,6 +20,7 @@ license: | --- This page covers `ForyBuilder` options and default configuration values for Apache Foryβ’ C#. +`Config` is an immutable runtime snapshot created by `ForyBuilder`. ## Build a Runtime @@ -36,7 +37,6 @@ ThreadSafeFory threadSafe = Fory.Builder().BuildThreadSafe(); | Option | Default | Description | | -------------------- | ------- | ---------------------------------------------- | -| `Xlang` | `true` | Cross-language protocol mode | | `TrackRef` | `false` | Reference tracking disabled | | `Compatible` | `false` | Schema-consistent mode (no evolution metadata) | | `CheckStructVersion` | `false` | Struct schema hash checks disabled | @@ -44,15 +44,8 @@ ThreadSafeFory threadSafe = Fory.Builder().BuildThreadSafe(); ## Builder Options -### `Xlang(bool enabled = true)` - -Controls cross-language mode. - -```csharp -Fory fory = Fory.Builder() - .Xlang(true) - .Build(); -``` +C# always uses xlang-compatible framing, so `ForyBuilder` does not expose a separate `Xlang(...)` +toggle. ### `TrackRef(bool enabled = false)` @@ -111,7 +104,6 @@ Fory fory = Fory.Builder() ```csharp Fory fory = Fory.Builder() - .Xlang(true) .Compatible(true) .TrackRef(true) .Build(); diff --git a/docs/guide/csharp/cross-language.md b/docs/guide/csharp/cross-language.md index 5a2af307ed..2b11ceb70e 100644 --- a/docs/guide/csharp/cross-language.md +++ b/docs/guide/csharp/cross-language.md @@ -21,13 +21,14 @@ license: | Apache Foryβ’ C# supports cross-language serialization with other Fory runtimes. -## Enable Cross-Language Mode +## Cross-Language Runtime -C# defaults to `Xlang(true)`, but it is good practice to configure it explicitly in interoperability code. +C# always writes and reads the xlang frame header. There is no separate `Xlang(...)` builder +option, so interoperability code only needs to configure the remaining runtime behavior such as +compatibility mode and reference tracking. ```csharp Fory fory = Fory.Builder() - .Xlang(true) .Compatible(true) .Build(); ``` @@ -43,7 +44,6 @@ public sealed class Person } Fory fory = Fory.Builder() - .Xlang(true) .Compatible(true) .Build(); diff --git a/docs/guide/csharp/troubleshooting.md b/docs/guide/csharp/troubleshooting.md index f078627eee..6f2ec28e07 100644 --- a/docs/guide/csharp/troubleshooting.md +++ b/docs/guide/csharp/troubleshooting.md @@ -38,13 +38,15 @@ Ensure the same type-ID/name mapping exists on both write and read sides. ## `InvalidDataException: xlang bitmap mismatch` -**Cause**: Writer/reader disagree on `Xlang` mode. +**Cause**: The payload is not an xlang Fory frame, or it came from a peer/runtime mode that does +not emit the xlang header C# requires. -**Fix**: Use the same `Xlang(...)` value on both peers. +**Fix**: Ensure the payload was produced by an xlang-compatible Fory runtime. C# always expects the +xlang header and does not expose a separate `Xlang(...)` builder option. ```csharp -Fory writer = Fory.Builder().Xlang(true).Build(); -Fory reader = Fory.Builder().Xlang(true).Build(); +Fory writer = Fory.Builder().Compatible(true).Build(); +Fory reader = Fory.Builder().Compatible(true).Build(); ``` ## Schema Version Mismatch in Strict Mode diff --git a/docs/guide/go/codegen.md b/docs/guide/go/codegen.md index 19cb384580..d78bbfb839 100644 --- a/docs/guide/go/codegen.md +++ b/docs/guide/go/codegen.md @@ -20,18 +20,18 @@ license: | --- :::warning Experimental Feature -Code generation is an **experimental** feature in Fory Go. The API and behavior may change in future releases. The reflection-based path remains the stable, recommended approach for most use cases. +Code generation is an **experimental** feature in Fory Go. The API and behavior may change in future releases. The standard runtime path remains the stable, recommended approach for most use cases. ::: -Fory Go provides optional ahead-of-time (AOT) code generation for performance-critical paths. This eliminates reflection overhead and provides compile-time type safety. +Fory Go provides optional ahead-of-time (AOT) code generation for performance-critical paths. This generates dedicated serializers ahead of time and adds compile-time shape checks. ## Why Code Generation? -| Aspect | Reflection-Based | Code Generation | +| Aspect | Standard Path | Code Generation | | ----------- | ------------------ | ---------------------- | | Setup | Zero configuration | Requires `go generate` | -| Performance | Good | Better (no reflection) | -| Type Safety | Runtime | Compile-time | +| Performance | Excellent | Better on hot paths | +| Type Safety | Runtime validation | Compile-time checks | | Maintenance | Automatic | Requires regeneration | **Use code generation when**: @@ -40,7 +40,7 @@ Fory Go provides optional ahead-of-time (AOT) code generation for performance-cr - Compile-time type safety is important - Hot paths are performance-critical -**Use reflection when**: +**Use the standard path when**: - Simple setup is preferred - Types change frequently @@ -307,7 +307,7 @@ type HotPathStruct struct { } type ColdPathStruct struct { - // Not annotated, uses reflection + // Not annotated, uses the standard runtime serializer } ``` @@ -326,12 +326,12 @@ type ColdPathStruct struct { - Private (unexported) fields - Custom serializers -### Reflection Fallback +### Standard Path Fallback -If codegen fails, Fory falls back to reflection: +If generated serializers are unavailable, Fory falls back to the standard serializer path: ```go -// If User_ForyGenSerializer not found, uses reflection +// If User_ForyGenSerializer is not linked in, Fory uses the standard path f.Serialize(&User{}) ``` @@ -405,7 +405,7 @@ type User struct { ### Is codegen required? -No. Reflection-based serialization works without code generation. +No. The standard serializer path works without code generation. ### Does generated code work across Go versions? diff --git a/docs/guide/go/index.md b/docs/guide/go/index.md index 90dba1b61d..68ef08c549 100644 --- a/docs/guide/go/index.md +++ b/docs/guide/go/index.md @@ -27,7 +27,7 @@ Apache Fory Go is a high-performance, cross-language serialization library for G - **Cross-Language**: Seamless data exchange with Java, Python, C++, Rust, and JavaScript - **Automatic Serialization**: No IDL definitions or schema compilation required - **Reference Tracking**: Built-in support for circular references and shared objects -- **Type Safety**: Strong typing with compile-time verification (optional codegen) +- **Type Safety**: Strong typing with schema-aware serializers - **Schema Evolution**: Compatible mode for forward/backward compatibility - **Thread-Safe Option**: Pool-based thread-safe wrapper for concurrent use @@ -84,23 +84,17 @@ func main() { } ``` -## Architecture +## Default Serialization Path -Fory Go provides two serialization paths: - -### Reflection-Based (Default) - -The default path uses Go's reflection to inspect types at runtime. This works out-of-the-box with any struct. Although this mode uses reflection, it is highly optimized with type caching, inlined hot paths, delivering excellent performance for most use cases: +Fory Go works out-of-the-box with ordinary Go structs. The standard runtime path caches type +metadata and keeps hot serialization paths optimized, so most applications can use it directly +without any extra build step: ```go f := fory.New() data, _ := f.Serialize(myStruct) ``` -### Code Generation (Experimental) - -For performance-critical paths, Fory provides optional ahead-of-time code generation that eliminates reflection overhead. See the [Code Generation](codegen.md) guide for details. - ## Configuration Fory Go uses a functional options pattern for configuration: @@ -153,7 +147,6 @@ See [Cross-Language Serialization](cross-language.md) for type mapping and compa | [Struct Tags](struct-tags.md) | Field-level configuration | | [Schema Evolution](schema-evolution.md) | Forward/backward compatibility | | [Cross-Language](cross-language.md) | Multi-language serialization | -| [Code Generation](codegen.md) | Experimental AOT code generation | | [Thread Safety](thread-safety.md) | Concurrent usage patterns | | [Troubleshooting](troubleshooting.md) | Common issues and solutions | diff --git a/docs/guide/java/advanced-features.md b/docs/guide/java/advanced-features.md index b7a535fe4e..c45d700d1c 100644 --- a/docs/guide/java/advanced-features.md +++ b/docs/guide/java/advanced-features.md @@ -1,6 +1,6 @@ --- title: Advanced Features -sidebar_position: 7 +sidebar_position: 10 id: advanced_features license: | Licensed to the Apache Software Foundation (ASF) under one or more diff --git a/docs/guide/java/compression.md b/docs/guide/java/compression.md index efe261aad4..88cfb70a6c 100644 --- a/docs/guide/java/compression.md +++ b/docs/guide/java/compression.md @@ -1,6 +1,6 @@ --- title: Compression -sidebar_position: 6 +sidebar_position: 7 id: compression license: | Licensed to the Apache Software Foundation (ASF) under one or more diff --git a/docs/guide/java/configuration.md b/docs/guide/java/configuration.md index 9071d423b6..dc1025bcd7 100644 --- a/docs/guide/java/configuration.md +++ b/docs/guide/java/configuration.md @@ -47,7 +47,7 @@ This page documents all configuration options available through `ForyBuilder`. | `asyncCompilationEnabled` | If enabled, serialization uses interpreter mode first and switches to JIT serialization after async serializer JIT for a class is finished. [...] | `scalaOptimizationEnabled` | Enables or disables Scala-specific serialization optimization. [...] | `copyRef` | When disabled, the copy performance will be better. But fory deep copy will ignore circular and shared reference. Same reference of an object graph will be copied into different objects in one `Fory#copy`. [...] -| `serializeEnumByName` | When Enabled, fory serialize enum by name instead of ordinal. [...] +| `serializeEnumByName` | When enabled, Fory serializes enum names instead of numeric enum tags. Without this option, Fory writes declaration ordinals by default, or explicit stable ids when the enum is configured with `@ForyEnumId`. [...] ## Example Configuration @@ -72,6 +72,8 @@ Fory fory = Fory.builder() ## Related Topics +- [Field Configuration](field-configuration.md) - `@ForyField`, `@Ignore`, and integer encoding annotations +- [Enum Configuration](enum-configuration.md) - `serializeEnumByName` and `@ForyEnumId` - [Schema Evolution](schema-evolution.md) - Compatible mode and meta sharing - [Compression](compression.md) - Int, long, and array compression details - [Type Registration](type-registration.md) - Class registration options diff --git a/docs/guide/java/cross-language.md b/docs/guide/java/cross-language.md index c9421245fc..31776ab7ca 100644 --- a/docs/guide/java/cross-language.md +++ b/docs/guide/java/cross-language.md @@ -1,6 +1,6 @@ --- title: Cross-Language Serialization -sidebar_position: 8 +sidebar_position: 11 id: cross_language license: | Licensed to the Apache Software Foundation (ASF) under one or more diff --git a/docs/guide/java/enum-configuration.md b/docs/guide/java/enum-configuration.md new file mode 100644 index 0000000000..c38507316a --- /dev/null +++ b/docs/guide/java/enum-configuration.md @@ -0,0 +1,111 @@ +--- +title: Enum Configuration +sidebar_position: 6 +id: enum_configuration +license: | + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--- + +This page explains how Java enum serialization is configured in Apache Fory. + +## Default Enum Behavior + +Java enums can be serialized in two modes: + +1. **By numeric tag**: the default behavior +2. **By enum name**: enabled with `serializeEnumByName(true)` + +Numeric tags are always used in xlang mode. In native Java mode, `serializeEnumByName(true)` +switches enum serialization to names instead of numeric tags. + +## Serialize Enums by Name + +Use `serializeEnumByName(true)` when native Java peers should match enum constants by name instead +of numeric tag. + +```java +Fory fory = Fory.builder() + .withLanguage(Language.JAVA) + .serializeEnumByName(true) + .build(); +``` + +This mode is useful when declaration order is unstable but enum names remain fixed. It only affects +native Java mode. Xlang still uses numeric tags. + +## Stable Numeric Enum IDs + +Without `serializeEnumByName(true)`, Java enums are serialized by numeric tag. The default tag is +the declaration ordinal. When an enum needs stable ids that do not depend on declaration order, +annotate exactly one id source with `@ForyEnumId`, or annotate every enum constant with explicit +tag values. + +```java +import org.apache.fory.annotation.ForyEnumId; + +enum Status { + Unknown(10), + Running(20), + Finished(30); + + private final int id; + + Status(int id) { + this.id = id; + } + + @ForyEnumId + public int getId() { + return id; + } +} +``` + +Java also supports annotating one enum instance field with `@ForyEnumId`, or annotating every enum +constant directly such as `@ForyEnumId(10) Unknown`. + +### `@ForyEnumId` Styles + +`@ForyEnumId` supports exactly three configuration styles: + +1. Annotate one enum instance field and store the numeric id there. +2. Annotate one zero-argument public instance method such as `getId()`. +3. Annotate every enum constant directly with an explicit value such as `@ForyEnumId(10) Unknown`. + +### Validation Rules + +1. Use exactly one of those three styles for a given enum. +2. Field and method annotations must leave `value()` at its default `-1`. +3. Enum-constant annotations must appear on every constant once any constant uses `@ForyEnumId`. +4. All ids must be non-negative, unique, and fit in Java `int`. + +### Lookup Behavior + +1. Without `@ForyEnumId`, Fory writes the declaration ordinal. +2. With `@ForyEnumId`, Fory writes the configured stable numeric tag instead. +3. Small dense tags use an array lookup internally; sparse larger tags fall back to a map. + +## Choosing Between Name and Numeric Modes + +- Use **enum names** when the enum is Java-only and constant names are the intended compatibility key. +- Use **numeric tags** when cross-language payloads or stable explicit ids matter. +- Use **`@ForyEnumId`** when declaration order may change but the numeric wire ids must stay stable. + +## Related Topics + +- [Configuration](configuration.md) - `serializeEnumByName` and other runtime options +- [Field Configuration](field-configuration.md) - `@ForyField`, `@Ignore`, and integer encoding annotations +- [Cross-Language](cross-language.md) - Xlang enum interoperability diff --git a/docs/guide/java/field-configuration.md b/docs/guide/java/field-configuration.md index 20a82c197e..6051090f67 100644 --- a/docs/guide/java/field-configuration.md +++ b/docs/guide/java/field-configuration.md @@ -601,5 +601,7 @@ public class User { ## Related Topics - [Basic Serialization](basic-serialization.md) - Getting started with Fory serialization +- [Configuration](configuration.md) - Runtime builder options +- [Enum Configuration](enum-configuration.md) - `@ForyEnumId` and enum name/tag behavior - [Schema Evolution](schema-evolution.md) - Compatible mode and schema evolution - [Cross-Language](cross-language.md) - Interoperability with Python, Rust, C++, Go diff --git a/docs/guide/java/index.md b/docs/guide/java/index.md index 2ce65869a5..e4b7d05aca 100644 --- a/docs/guide/java/index.md +++ b/docs/guide/java/index.md @@ -200,7 +200,10 @@ ThreadSafeFory threadLocalFory = Fory.builder() ## Next Steps - [Configuration](configuration.md) - Learn about ForyBuilder options +- [Field Configuration](field-configuration.md) - `@ForyField`, `@Ignore`, and integer encoding annotations +- [Enum Configuration](enum-configuration.md) - `serializeEnumByName` and `@ForyEnumId` - [Basic Serialization](basic-serialization.md) - Detailed serialization patterns +- [Compression](compression.md) - Integer, long, and array compression options - [Virtual Threads](virtual-threads.md) - Virtual-thread usage and pool sizing guidance - [Type Registration](type-registration.md) - Class registration and security - [Custom Serializers](custom-serializers.md) - Implement custom serializers diff --git a/docs/guide/java/migration.md b/docs/guide/java/migration.md index 20d41bedeb..9c77b35648 100644 --- a/docs/guide/java/migration.md +++ b/docs/guide/java/migration.md @@ -1,6 +1,6 @@ --- title: Migration Guide -sidebar_position: 10 +sidebar_position: 13 id: migration license: | Licensed to the Apache Software Foundation (ASF) under one or more diff --git a/docs/guide/java/row-format.md b/docs/guide/java/row-format.md index eb58646b38..14bb55ed4d 100644 --- a/docs/guide/java/row-format.md +++ b/docs/guide/java/row-format.md @@ -1,6 +1,6 @@ --- title: Row Format -sidebar_position: 9 +sidebar_position: 12 id: row_format license: | Licensed to the Apache Software Foundation (ASF) under one or more diff --git a/docs/guide/java/schema-evolution.md b/docs/guide/java/schema-evolution.md index 0ea207fa27..5b754171a7 100644 --- a/docs/guide/java/schema-evolution.md +++ b/docs/guide/java/schema-evolution.md @@ -1,6 +1,6 @@ --- title: Schema Evolution -sidebar_position: 5 +sidebar_position: 9 id: schema_evolution license: | Licensed to the Apache Software Foundation (ASF) under one or more diff --git a/docs/guide/java/troubleshooting.md b/docs/guide/java/troubleshooting.md index ec0e778bed..b693d51bc6 100644 --- a/docs/guide/java/troubleshooting.md +++ b/docs/guide/java/troubleshooting.md @@ -1,6 +1,6 @@ --- title: Troubleshooting -sidebar_position: 11 +sidebar_position: 14 id: troubleshooting license: | Licensed to the Apache Software Foundation (ASF) under one or more diff --git a/docs/guide/java/virtual-threads.md b/docs/guide/java/virtual-threads.md index 5db05a951e..cc57166b33 100644 --- a/docs/guide/java/virtual-threads.md +++ b/docs/guide/java/virtual-threads.md @@ -1,6 +1,6 @@ --- title: Virtual Threads -sidebar_position: 11 +sidebar_position: 8 id: java_virtual_threads license: | Licensed to the Apache Software Foundation (ASF) under one or more --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
