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 ac7594280eb02a2987251048f60c90d3941c0834 Author: chaokunyang <[email protected]> AuthorDate: Tue Aug 4 05:58:23 2026 +0000 π synced local 'docs/object-serialization/' with remote 'docs/object-serialization/' --- docs/object-serialization/core-concepts.md | 30 ++-- .../cpp/basic-serialization.md | 2 +- docs/object-serialization/cpp/configuration.md | 2 +- docs/object-serialization/cpp/polymorphism.md | 2 +- docs/object-serialization/cpp/security.md | 6 +- .../csharp/basic-serialization.md | 2 +- docs/object-serialization/csharp/configuration.md | 2 +- docs/object-serialization/csharp/external-types.md | 4 +- .../object-serialization/csharp/schema-metadata.md | 2 +- docs/object-serialization/csharp/security.md | 6 +- .../dart/basic-serialization.md | 2 +- docs/object-serialization/dart/configuration.md | 2 +- docs/object-serialization/dart/external-types.md | 2 +- docs/object-serialization/dart/schema-evolution.md | 2 +- docs/object-serialization/dart/security.md | 6 +- .../object-serialization/dart/type-registration.md | 4 +- .../object-serialization/go/basic-serialization.md | 2 +- docs/object-serialization/go/configuration.md | 4 +- docs/object-serialization/go/security.md | 6 +- docs/object-serialization/index.md | 45 +++--- docs/object-serialization/java/android.md | 2 +- .../java/basic-serialization.md | 2 +- docs/object-serialization/java/index.md | 10 +- docs/object-serialization/java/schema-evolution.md | 2 +- docs/object-serialization/java/security.md | 6 +- .../java/static-generated-serializers.md | 2 +- docs/object-serialization/java/troubleshooting.md | 6 +- .../javascript/basic-serialization.md | 2 +- .../javascript/configuration.md | 2 +- docs/object-serialization/javascript/security.md | 6 +- .../kotlin/basic-serialization.md | 2 +- docs/object-serialization/kotlin/index.md | 6 +- docs/object-serialization/kotlin/native.md | 6 +- docs/object-serialization/kotlin/security.md | 4 +- docs/object-serialization/native.md | 154 +++++++++++++++++++-- .../python/basic-serialization.md | 2 +- .../object-serialization/python/schema-metadata.md | 2 +- docs/object-serialization/python/security.md | 6 +- .../rust/basic-serialization.md | 2 +- docs/object-serialization/rust/configuration.md | 2 +- docs/object-serialization/rust/external-types.md | 2 +- docs/object-serialization/rust/index.md | 14 +- docs/object-serialization/rust/native.md | 2 +- docs/object-serialization/rust/polymorphism.md | 2 +- docs/object-serialization/rust/security.md | 6 +- .../object-serialization/rust/type-registration.md | 2 +- docs/object-serialization/scala/index.md | 6 +- docs/object-serialization/scala/native.md | 4 +- docs/object-serialization/scala/security.md | 4 +- .../swift/basic-serialization.md | 2 +- docs/object-serialization/swift/configuration.md | 2 +- docs/object-serialization/swift/security.md | 6 +- docs/object-serialization/xlang.md | 97 ++++++------- 53 files changed, 327 insertions(+), 181 deletions(-) diff --git a/docs/object-serialization/core-concepts.md b/docs/object-serialization/core-concepts.md index c122e6d450..bdb8e9b877 100644 --- a/docs/object-serialization/core-concepts.md +++ b/docs/object-serialization/core-concepts.md @@ -30,18 +30,18 @@ cycles. Serialization walks that graph from the root. Deserialization creates a encoded type and field data. This is different from serializing a row or a JSON document. Object serialization can preserve -runtime types and object identity so the reader can reconstruct application objects rather than +concrete object types and object identity so the reader can reconstruct application objects rather than only values. Use [Row Format](../row-format/index.md) for trusted analytical rows and [Fory JSON](../json/index.md) for JSON interchange. -## Runtime instances and registration +## Fory instances and registration A Fory instance owns its mode, schema behavior, reference settings, registered types, custom serializers, and read limits. Configure and register the instance before its first root serialization or deserialization operation, then reuse it. Registration is frozen after the first root operation so the same instance always resolves a type in the same way. -Thread-safety differs by runtime. Some runtimes provide a thread-safe wrapper or pool; others use +Thread-safety differs by Fory implementation. Some implementations provide a thread-safe wrapper or pool; others use one instance per thread or task. Follow the selected language guide instead of sharing an ordinary instance without checking its concurrency contract. @@ -52,13 +52,14 @@ extension types use a registered numeric ID or name. Type identity answers _whic model should read this value_; a field schema describes _what data that model contains_. A statically known field can use its declared type directly. A dynamic field also carries the -concrete runtime type needed for interfaces, abstract classes, trait objects, broad object types, +concrete type needed for interfaces, abstract classes, trait objects, broad object types, or heterogeneous values. Dynamic typing is more flexible but requires every possible concrete type to be registered and supported by the selected mode. In xlang mode, peers must coordinate the same portable type identity and mapping. Native mode may -use runtime-specific identities and types. See [Xlang Serialization](xlang.md) for the portable -rules and each language's Type Registration page for its exact API. +use implementation-specific identities and language-specific types. See +[Xlang Serialization](xlang.md) for the portable rules and each language's Type Registration page +for its exact API. ## Schemas and evolution @@ -90,7 +91,7 @@ than once or contains a cycle. Without reference tracking, repeated values may b objects and cycles may recurse until the operation fails. Leave reference tracking disabled for value-shaped, acyclic data when identity does not matter; it -adds per-object metadata and lookup work. Some runtimes combine a global setting with field-level +adds per-object metadata and lookup work. Some Fory implementations combine a global setting with field-level metadata, so use the language-specific References or Basic Serialization page for exact behavior. ## Polymorphism @@ -99,24 +100,25 @@ Polymorphism stores the concrete type of a value whose declared position is broa must know and accept that concrete type, and the type must be representable in the selected mode. Host-language inheritance alone does not create a portable contract. For cross-language data, -model only alternatives that have xlang mappings on every peer. For same-runtime data, native mode -may support additional runtime-specific class, trait, or hook behavior. +model only alternatives that have xlang mappings on every peer. For data within one Fory +implementation family, native mode may support additional language-specific class, trait, or hook +behavior. ## Custom serializers Use a custom serializer when a type needs a representation that built-in schema inference cannot provide. Registration connects the custom serializer to the application type. A custom serializer must follow the selected mode's rules: xlang serializers need a portable representation, while -native serializers may use runtime-specific data and hooks. +native serializers may use language-specific data and hooks. Prefer built-in serializers and generated models when they already describe the type. They keep schema evolution, reference handling, and cross-language behavior easier to reason about. ## Continue with a mode -- [Xlang Serialization](xlang.md) is the default and is required when different language runtimes - exchange bytes. -- [Native Serialization](native.md) is for supported same-runtime use cases that need native types - or behavior. +- [Xlang Serialization](xlang.md) is the default and is required when peers use different Fory + implementation families or need a portable contract. +- [Native Serialization](native.md) is for supported use cases within one Fory implementation + family that need native types or behavior. - Choose a language section after selecting a mode to find installation, API, configuration, registration, platform, security, and troubleshooting guidance. diff --git a/docs/object-serialization/cpp/basic-serialization.md b/docs/object-serialization/cpp/basic-serialization.md index 275ad53ed4..ae71428a9d 100644 --- a/docs/object-serialization/cpp/basic-serialization.md +++ b/docs/object-serialization/cpp/basic-serialization.md @@ -357,7 +357,7 @@ fory.register_struct<Outer>(2); ## Cross-Language Interoperability -The default xlang format is shared by all Fory runtimes. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. +The default xlang format is shared by all supported Fory implementations. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. This page explains how to use Fory xlang serialization between C++ and other languages. diff --git a/docs/object-serialization/cpp/configuration.md b/docs/object-serialization/cpp/configuration.md index 78c77939d2..42d066000c 100644 --- a/docs/object-serialization/cpp/configuration.md +++ b/docs/object-serialization/cpp/configuration.md @@ -108,7 +108,7 @@ auto fory = Fory::builder() The default limit is a fixed `128 MiB` for byte-array, `Buffer`, and stream roots. Positive values override the default. Explicit non-positive values are -rejected when the runtime is created. +rejected when the Fory instance is created. This budget is an approximate lower-bound estimate for materialized graph owners, mainly collections, maps, arrays, structs, and objects. It is not an diff --git a/docs/object-serialization/cpp/polymorphism.md b/docs/object-serialization/cpp/polymorphism.md index 383ba7c36d..553214a674 100644 --- a/docs/object-serialization/cpp/polymorphism.md +++ b/docs/object-serialization/cpp/polymorphism.md @@ -206,7 +206,7 @@ static_cast<Dog*>(container.pet.get())->breed = "Beagle"; auto bytes = fory.serialize(container).value(); auto decoded = fory.deserialize<Container>(bytes).value(); -// Runtime type preserved +// Dynamic type preserved auto* dog = dynamic_cast<Dog*>(decoded.pet.get()); assert(dog != nullptr); assert(dog->breed == "Beagle"); diff --git a/docs/object-serialization/cpp/security.md b/docs/object-serialization/cpp/security.md index fe86e37d2d..860505ee98 100644 --- a/docs/object-serialization/cpp/security.md +++ b/docs/object-serialization/cpp/security.md @@ -33,7 +33,7 @@ Before deserialization: first root operation. - Validate the deserialized value against application authorization and domain rules before use. -## Runtime safeguards +## Built-in safeguards Security-related configuration: @@ -51,7 +51,7 @@ Security-related configuration: Add negative tests for the boundary as well as normal round trips. Verify that the configured reader rejects unexpected application types, excessive nesting, resource-limit violations, and malformed -input. After a failed read, verify that a valid root can still be read with the reusable runtime. +input. After a failed read, verify that a valid root can still be read with the same Fory instance. See [Configuration](configuration.md) for the complete option reference and -[Type Registration](type-registration.md) for the runtime's registration API. +[Type Registration](type-registration.md) for the Fory registration API. diff --git a/docs/object-serialization/csharp/basic-serialization.md b/docs/object-serialization/csharp/basic-serialization.md index 7c77560a7d..af40c1a309 100644 --- a/docs/object-serialization/csharp/basic-serialization.md +++ b/docs/object-serialization/csharp/basic-serialization.md @@ -161,7 +161,7 @@ fory.Serialize<object?>(dynamicWriter, value); ## Cross-Language Interoperability -The default xlang format is shared by all Fory runtimes. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. +The default xlang format is shared by all Fory implementations. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. Apache Foryβ’ C# supports xlang serialization with other Fory implementations. diff --git a/docs/object-serialization/csharp/configuration.md b/docs/object-serialization/csharp/configuration.md index 5bac8df215..7ac807affc 100644 --- a/docs/object-serialization/csharp/configuration.md +++ b/docs/object-serialization/csharp/configuration.md @@ -112,7 +112,7 @@ Fory fory = Fory.Builder() ``` The default limit is a fixed `128 MiB` for all root input forms. A positive value overrides the -default. Explicit non-positive values are rejected when the runtime is created. Skipped leaf values +default. Explicit non-positive values are rejected when the Fory instance is created. Skipped leaf values are still gated by remaining input bytes: if the unread input does not contain enough bytes, Fory will not read or create that leaf value. diff --git a/docs/object-serialization/csharp/external-types.md b/docs/object-serialization/csharp/external-types.md index 0b1e18fd1a..b14b7aeb0e 100644 --- a/docs/object-serialization/csharp/external-types.md +++ b/docs/object-serialization/csharp/external-types.md @@ -131,7 +131,7 @@ private mapping is an application-owned package ABI declaration. Pin and test the package version together with the declaration. If a mapped private field changes, the generated exact accessor fails with the CLR's missing-field error; Fory does not fall back to reflection or another member. An ignored private -field has no runtime accessor, so validate that storage declaration against the +field has no generated accessor, so validate that storage declaration against the pinned package build. External struct targets support visible field and property mappings only. @@ -306,7 +306,7 @@ List<ThirdParty.User> decoded = ``` External children are supported through the concrete carrier types already -supported by the C# runtime: +supported by Fory C#: - `Nullable<T>` for external structs and one-dimensional `T[]`; - `List<T>`, `LinkedList<T>`, `Queue<T>`, and `Stack<T>`; diff --git a/docs/object-serialization/csharp/schema-metadata.md b/docs/object-serialization/csharp/schema-metadata.md index 99f9cb3a62..d9858982e5 100644 --- a/docs/object-serialization/csharp/schema-metadata.md +++ b/docs/object-serialization/csharp/schema-metadata.md @@ -29,7 +29,7 @@ External-type serialization puts `Target` on a local abstract serializer declaration. Its properties own the field names, IDs, schema descriptors, and nullability. A standalone declaration also owns its `Evolving` setting. An external `BaseOnly` declaration cannot set `Evolving`; each concrete -descendant owns that setting. The target supplies the runtime values and +descendant owns that setting. The target supplies values of the target type and directly accessed members. ```csharp diff --git a/docs/object-serialization/csharp/security.md b/docs/object-serialization/csharp/security.md index 06416a73e0..58c33374be 100644 --- a/docs/object-serialization/csharp/security.md +++ b/docs/object-serialization/csharp/security.md @@ -33,7 +33,7 @@ Before deserialization: first root operation. - Validate the deserialized value against application authorization and domain rules before use. -## Runtime safeguards +## Built-in safeguards Security-related configuration: @@ -50,7 +50,7 @@ Security-related configuration: Add negative tests for the boundary as well as normal round trips. Verify that the configured reader rejects unexpected application types, excessive nesting, resource-limit violations, and malformed -input. After a failed read, verify that a valid root can still be read with the reusable runtime. +input. After a failed read, verify that a valid root can still be read with the same Fory instance. See [Configuration](configuration.md) for the complete option reference and -[Type Registration](type-registration.md) for the runtime's registration API. +[Type Registration](type-registration.md) for the Fory registration API. diff --git a/docs/object-serialization/dart/basic-serialization.md b/docs/object-serialization/dart/basic-serialization.md index 0b28adb02b..4ada0c62c4 100644 --- a/docs/object-serialization/dart/basic-serialization.md +++ b/docs/object-serialization/dart/basic-serialization.md @@ -140,7 +140,7 @@ If you skip registration, deserialization fails with `Type ... is not registered ## Cross-Language Interoperability -The default xlang format is shared by all Fory runtimes. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. +The default xlang format is shared by all Fory implementations. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. Apache Foryβ’ Dart serializes to the same binary format as the Java, Go, C#, Python, Rust, and Swift Fory implementations. You can write a message in Dart and read it in Java β or any other direction β without any conversion layer. diff --git a/docs/object-serialization/dart/configuration.md b/docs/object-serialization/dart/configuration.md index 7094e9b4a9..e310843651 100644 --- a/docs/object-serialization/dart/configuration.md +++ b/docs/object-serialization/dart/configuration.md @@ -126,7 +126,7 @@ collection/map/struct gate: final fory = Fory(maxGraphMemoryBytes: 256 * 1024 * 1024); ``` -Explicit non-positive values are rejected when the runtime is created. +Explicit non-positive values are rejected when the Fory instance is created. ### `maxUnbackedContainerItems` diff --git a/docs/object-serialization/dart/external-types.md b/docs/object-serialization/dart/external-types.md index 0141164b4e..2ec2796172 100644 --- a/docs/object-serialization/dart/external-types.md +++ b/docs/object-serialization/dart/external-types.md @@ -226,7 +226,7 @@ Register every concrete external type that can appear dynamically. Non-empty root lists, sets, and maps decode their elements, keys, and values as the registered external targets. Dart root collections retain their existing -runtime shapes, so read a root collection as `Object?` and cast its outer +untyped outer shapes, so read a root collection as `Object?` and cast its outer carrier: ```dart diff --git a/docs/object-serialization/dart/schema-evolution.md b/docs/object-serialization/dart/schema-evolution.md index 6f290413a1..560bd7b684 100644 --- a/docs/object-serialization/dart/schema-evolution.md +++ b/docs/object-serialization/dart/schema-evolution.md @@ -124,7 +124,7 @@ must change together because the resulting field list is different. A parent annotation does not propagate this setting to children. This option changes generated field selection only. It does not change the -runtime reference protocol or add a compatibility reader. +reference protocol or add a compatibility reader. ## Related Topics diff --git a/docs/object-serialization/dart/security.md b/docs/object-serialization/dart/security.md index 4367148291..a3f5d4ca85 100644 --- a/docs/object-serialization/dart/security.md +++ b/docs/object-serialization/dart/security.md @@ -33,7 +33,7 @@ Before deserialization: first root operation. - Validate the deserialized value against application authorization and domain rules before use. -## Runtime safeguards +## Built-in safeguards Security-related configuration: @@ -50,7 +50,7 @@ Security-related configuration: Add negative tests for the boundary as well as normal round trips. Verify that the configured reader rejects unexpected application types, excessive nesting, resource-limit violations, and malformed -input. After a failed read, verify that a valid root can still be read with the reusable runtime. +input. After a failed read, verify that a valid root can still be read with the same Fory instance. See [Configuration](configuration.md) for the complete option reference and -[Type Registration](type-registration.md) for the runtime's registration API. +[Type Registration](type-registration.md) for the Fory registration API. diff --git a/docs/object-serialization/dart/type-registration.md b/docs/object-serialization/dart/type-registration.md index 2364c81bd6..574039f98c 100644 --- a/docs/object-serialization/dart/type-registration.md +++ b/docs/object-serialization/dart/type-registration.md @@ -67,11 +67,11 @@ UserModelsForyModule.register(fory, User, id: 100); For an ordinary inherited type, register the concrete annotated child. Its generated serializer already owns the complete flattened child schema; Fory -does not require runtime registration of a superclass or mixin merely because +does not require separate registration of a superclass or mixin merely because it contributes fields. Register an independently annotated concrete parent only when values whose -runtime type is that parent are also serialized. A provider-only +actual type is exactly that parent are also serialized. A provider-only `@ForyStruct(exposePrivateFields: true)` boundary supplies generated field access and has no registration entry of its own. See [Struct Inheritance](inheritance.md) for boundary and child-schema options. diff --git a/docs/object-serialization/go/basic-serialization.md b/docs/object-serialization/go/basic-serialization.md index e5b19b3fc5..8dca339ffb 100644 --- a/docs/object-serialization/go/basic-serialization.md +++ b/docs/object-serialization/go/basic-serialization.md @@ -403,7 +403,7 @@ func main() { ## Cross-Language Interoperability -The default xlang format is shared by all Fory runtimes. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. +The default xlang format is shared by all Fory implementations. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. Fory Go enables seamless data exchange with Java, Python, C++, Rust, JavaScript/TypeScript, C#, Swift, Dart, Scala, and Kotlin. This guide covers diff --git a/docs/object-serialization/go/configuration.md b/docs/object-serialization/go/configuration.md index e3de7416ed..8f59db06e2 100644 --- a/docs/object-serialization/go/configuration.md +++ b/docs/object-serialization/go/configuration.md @@ -144,7 +144,7 @@ leaf values such as strings, binary data, primitive scalars, and dense primitive process memory can be higher than this value. The default limit is a fixed `128 MiB` for all root input forms. A positive value overrides the -default. Explicit non-positive values are rejected when the runtime is created. Graph memory +default. Explicit non-positive values are rejected when the Fory instance is created. Graph memory reservation complements byte-availability checks; it does not replace them. Skipped leaf values are still gated by remaining input bytes: if the unread input does not contain enough bytes, Fory will not read or create that leaf value. @@ -214,7 +214,7 @@ xlang := fory.New(fory.WithXlang(true)) - Go-native serialization mode - Supports more Go-native type behavior -- Not compatible with other language implementations +- Not wire-compatible with other Fory implementation families ## Thread Safety diff --git a/docs/object-serialization/go/security.md b/docs/object-serialization/go/security.md index 916643e3e3..0ad71c5513 100644 --- a/docs/object-serialization/go/security.md +++ b/docs/object-serialization/go/security.md @@ -33,7 +33,7 @@ Before deserialization: first root operation. - Validate the deserialized value against application authorization and domain rules before use. -## Runtime safeguards +## Built-in safeguards Security-related configuration: @@ -47,7 +47,7 @@ Security-related configuration: Add negative tests for the boundary as well as normal round trips. Verify that the configured reader rejects unexpected application types, excessive nesting, resource-limit violations, and malformed -input. After a failed read, verify that a valid root can still be read with the reusable runtime. +input. After a failed read, verify that a valid root can still be read with the same Fory instance. See [Configuration](configuration.md) for the complete option reference and -[Type Registration](type-registration.md) for the runtime's registration API. +[Type Registration](type-registration.md) for the Fory registration API. diff --git a/docs/object-serialization/index.md b/docs/object-serialization/index.md index 02eeae901e..0fbf24c06f 100644 --- a/docs/object-serialization/index.md +++ b/docs/object-serialization/index.md @@ -24,10 +24,10 @@ collections, polymorphic values, and optional shared references. ## Choose a mode -| Mode | Use it when | Start here | -| --------------- | ---------------------------------------------------- | --------------------------------- | -| Xlang (default) | Bytes cross runtime boundaries | [Xlang Serialization](xlang.md) | -| Native | Every writer and reader uses the same runtime family | [Native serialization](native.md) | +| Mode | Use it when | Start here | +| --------------- | ----------------------------------------------------------- | --------------------------------- | +| Xlang (default) | Bytes cross language boundaries | [Xlang Serialization](xlang.md) | +| Native | Every writer and reader uses one Fory implementation family | [Native serialization](native.md) | Xlang and native are the only object-serialization modes. Row Format is a random-access analytical representation, and Fory JSON is a Java JSON codec; use the @@ -35,32 +35,33 @@ representation, and Fory JSON is a Java JSON codec; use the ## Read the concepts and modes -Read these pages before choosing a runtime API: +Read these pages before choosing the Fory API for a language: 1. [Core Concepts](core-concepts.md) explains object graphs, types, schemas, references, polymorphism, and schema evolution across both modes. 2. [Xlang Serialization](xlang.md) explains the portable format used by default and the rules that - different language runtimes must share. -3. [Native Serialization](native.md) explains when a same-runtime native format is appropriate. + Fory implementations in different languages must share. +3. [Native Serialization](native.md) explains when an implementation-specific native format is + appropriate. -## Browse by runtime +## Browse by language -Choose a runtime to find its installation route, lifecycle, exact APIs, configuration, type +Choose a language to find its installation route, lifecycle, exact APIs, configuration, type registration, schema behavior, extensions, platforms, and troubleshooting: -| Runtime | Modes | Documentation | -| --------------------- | -------------------- | ------------------------------------------------------ | -| Java | xlang and native | [Java runtime](./java/index.md) | -| Python | xlang and native | [Python runtime](./python/index.md) | -| C++ | xlang and native | [C++ runtime](./cpp/index.md) | -| Go | xlang and native | [Go runtime](./go/index.md) | -| Rust | xlang and native | [Rust runtime](./rust/index.md) | -| JavaScript/TypeScript | xlang | [JavaScript/TypeScript runtime](./javascript/index.md) | -| C# | xlang | [C# runtime](./csharp/index.md) | -| Swift | xlang | [Swift runtime](./swift/index.md) | -| Dart | xlang | [Dart runtime](./dart/index.md) | -| Scala | xlang and JVM native | [Scala runtime](./scala/index.md) | -| Kotlin | xlang and JVM native | [Kotlin runtime](./kotlin/index.md) | +| Language | Modes | Documentation | +| --------------------- | -------------------- | ---------------------------------------------------- | +| Java | xlang and native | [Java guide](./java/index.md) | +| Python | xlang and native | [Python guide](./python/index.md) | +| C++ | xlang and native | [C++ guide](./cpp/index.md) | +| Go | xlang and native | [Go guide](./go/index.md) | +| Rust | xlang and native | [Rust guide](./rust/index.md) | +| JavaScript/TypeScript | xlang | [JavaScript/TypeScript guide](./javascript/index.md) | +| C# | xlang | [C# guide](./csharp/index.md) | +| Swift | xlang | [Swift guide](./swift/index.md) | +| Dart | xlang | [Dart guide](./dart/index.md) | +| Scala | xlang and JVM native | [Scala guide](./scala/index.md) | +| Kotlin | xlang and JVM native | [Kotlin guide](./kotlin/index.md) | ## Specifications diff --git a/docs/object-serialization/java/android.md b/docs/object-serialization/java/android.md index 34fd3ea105..817c99d15f 100644 --- a/docs/object-serialization/java/android.md +++ b/docs/object-serialization/java/android.md @@ -19,7 +19,7 @@ license: | limitations under the License. --- -## Android Runtime +## Android Support Fory Java supports Android 8.0+ (API level 26+) through the regular `fory-core` artifact. No separate Android artifact is required for core object serialization. diff --git a/docs/object-serialization/java/basic-serialization.md b/docs/object-serialization/java/basic-serialization.md index 70fb3ea7dc..464145215c 100644 --- a/docs/object-serialization/java/basic-serialization.md +++ b/docs/object-serialization/java/basic-serialization.md @@ -125,7 +125,7 @@ object copy, and native-mode zero-copy buffers. See [Native Serialization](nativ ## Cross-Language Interoperability -The default xlang format is shared by all Fory runtimes. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. +The default xlang format is shared by all supported Fory implementations. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. Apache Foryβ’ xlang serialization is the Java wire mode for payloads that must be read by Python, Rust, Go, JavaScript/TypeScript, C++, C#, Swift, Dart, Scala, Kotlin, or another non-Java Fory implementation. Java defaults to diff --git a/docs/object-serialization/java/index.md b/docs/object-serialization/java/index.md index 2d5add91f8..15fadb9c40 100644 --- a/docs/object-serialization/java/index.md +++ b/docs/object-serialization/java/index.md @@ -20,9 +20,9 @@ license: | --- Apache Fory Java provides high-performance binary object serialization. Use xlang mode for payloads -shared with other supported runtimes and native mode for Java/JVM-only object graphs. +shared across Fory implementation families and native mode for JVM-family object graphs. -This runtime guide is scoped to Binary Object Serialization. For other Java capabilities, use +This Java guide is scoped to Binary Object Serialization. For other Java capabilities, use [Row Format](../../row-format/java.md), [Fory JSON](../../json/index.md), [Fory IDL and compiler](../../compiler/index.md), or [Fory gRPC](../../grpc/java.md). @@ -76,8 +76,10 @@ implementation("org.apache.fory:fory-core:1.5.0") #### JDK 25 and Later -On JDK 25 and later, open `java.lang.invoke` to Fory. Use `ALL-UNNAMED` when Fory is on -the classpath: +On JDK 25 and later, opening `java.lang.invoke` to Fory core is not required, but is recommended. It avoids +the current-JDK Unsafe fallback and is required when Unsafe access is disabled or unavailable, +including with `--sun-misc-unsafe-memory-access=deny`. Use `ALL-UNNAMED` when Fory is on the +classpath: ```bash --add-opens=java.base/java.lang.invoke=ALL-UNNAMED diff --git a/docs/object-serialization/java/schema-evolution.md b/docs/object-serialization/java/schema-evolution.md index 9a2796306e..044768fb54 100644 --- a/docs/object-serialization/java/schema-evolution.md +++ b/docs/object-serialization/java/schema-evolution.md @@ -27,7 +27,7 @@ In many systems, the schema of a class used for serialization may change over ti ### Default Mode -Fory defaults to compatible mode in both Java native mode (`xlang=false`) and xlang mode. This default is safer for independently deployed services because writer and reader schemas can diverge during rolling upgrades or across language implementations. +Fory defaults to compatible mode in both Java native mode (`xlang=false`) and xlang mode. This default is safer for independently deployed services because writer and reader schemas can diverge during rolling upgrades or across Fory implementations in different languages. For payloads whose reader and writer schemas never differ, see [Same-Schema Optimization](#same-schema-optimization). diff --git a/docs/object-serialization/java/security.md b/docs/object-serialization/java/security.md index 780d39b2d2..77f6ac4350 100644 --- a/docs/object-serialization/java/security.md +++ b/docs/object-serialization/java/security.md @@ -33,7 +33,7 @@ Before deserialization: first root operation. - Validate the deserialized value against application authorization and domain rules before use. -## Runtime safeguards +## Built-in safeguards Keep class registration enabled for production and any untrusted payload source: @@ -77,7 +77,7 @@ allow list when dynamic class loading is required. Add negative tests for the boundary as well as normal round trips. Verify that the configured reader rejects unexpected application types, excessive nesting, resource-limit violations, and malformed -input. After a failed read, verify that a valid root can still be read with the reusable runtime. +input. After a failed read, verify that a valid root can still be read with the same Fory instance. See [Configuration](configuration.md) for the complete option reference and -[Type Registration](type-registration.md) for the runtime's registration API. +[Type Registration](type-registration.md) for the Fory registration API. diff --git a/docs/object-serialization/java/static-generated-serializers.md b/docs/object-serialization/java/static-generated-serializers.md index 14f7546263..4eea62dbf1 100644 --- a/docs/object-serialization/java/static-generated-serializers.md +++ b/docs/object-serialization/java/static-generated-serializers.md @@ -104,7 +104,7 @@ public class DebugOrder { } ``` -## Runtime Use +## Serializer Selection Fory uses static generated serializers when they are available on: diff --git a/docs/object-serialization/java/troubleshooting.md b/docs/object-serialization/java/troubleshooting.md index 8d68b68b0c..d70a027552 100644 --- a/docs/object-serialization/java/troubleshooting.md +++ b/docs/object-serialization/java/troubleshooting.md @@ -185,8 +185,10 @@ fory.registerSerializer(MyClass.class, new MyClassSerializer(fory.getTypeResolve ### JDK25+ access errors -On JDK25+, if an error names `java.base/java.lang.invoke`, open `java.lang.invoke` to Fory. Use -`ALL-UNNAMED` when Fory is on the classpath: +On JDK25+, opening `java.lang.invoke` to Fory core is not required, but is recommended. Add the opening if +an error names `java.base/java.lang.invoke`, or when Unsafe access is disabled or unavailable, +including with `--sun-misc-unsafe-memory-access=deny`. Use `ALL-UNNAMED` when Fory is on the +classpath: ```bash --add-opens=java.base/java.lang.invoke=ALL-UNNAMED diff --git a/docs/object-serialization/javascript/basic-serialization.md b/docs/object-serialization/javascript/basic-serialization.md index ce14adb1ce..28752265cc 100644 --- a/docs/object-serialization/javascript/basic-serialization.md +++ b/docs/object-serialization/javascript/basic-serialization.md @@ -239,7 +239,7 @@ This is useful when debugging schema behavior, field ordering, or generated fast ## Cross-Language Interoperability -The default xlang format is shared by all Fory runtimes. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. +The default xlang format is shared by all Fory implementations. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. Fory JavaScript serializes to the same binary format as the Java, Python, C++, Go, Rust, C#, Swift, Dart, Scala, and Kotlin Fory implementations. You can write a diff --git a/docs/object-serialization/javascript/configuration.md b/docs/object-serialization/javascript/configuration.md index c73194882e..51c0544689 100644 --- a/docs/object-serialization/javascript/configuration.md +++ b/docs/object-serialization/javascript/configuration.md @@ -113,7 +113,7 @@ const fory = new Fory({ }); ``` -Explicit non-positive values are rejected when the runtime is created. +Explicit non-positive values are rejected when the Fory instance is created. String, binary, and dedicated dense primitive array payloads keep their normal byte-size checks and do not consume this graph budget. Raise the limit only for diff --git a/docs/object-serialization/javascript/security.md b/docs/object-serialization/javascript/security.md index 6a01ac5b73..8b0f959030 100644 --- a/docs/object-serialization/javascript/security.md +++ b/docs/object-serialization/javascript/security.md @@ -33,7 +33,7 @@ Before deserialization: first root operation. - Validate the deserialized value against application authorization and domain rules before use. -## Runtime safeguards +## Built-in safeguards Security-related configuration: @@ -54,7 +54,7 @@ Security-related configuration: Add negative tests for the boundary as well as normal round trips. Verify that the configured reader rejects unexpected application types, excessive nesting, resource-limit violations, and malformed -input. After a failed read, verify that a valid root can still be read with the reusable runtime. +input. After a failed read, verify that a valid root can still be read with the same Fory instance. See [Configuration](configuration.md) for the complete option reference and -[Type Registration](type-registration.md) for the runtime's registration API. +[Type Registration](type-registration.md) for the Fory registration API. diff --git a/docs/object-serialization/kotlin/basic-serialization.md b/docs/object-serialization/kotlin/basic-serialization.md index 0fdbfb3c04..7b88988f01 100644 --- a/docs/object-serialization/kotlin/basic-serialization.md +++ b/docs/object-serialization/kotlin/basic-serialization.md @@ -26,7 +26,7 @@ Xlang is the default serialization mode for Fory Kotlin. This page covers the ba The following sections cover model generation, registration, and cross-language round trips in the default xlang mode. Kotlin xlang serialization uses the JVM Fory implementation through `ForyKotlin`. Use it when -Kotlin payloads must be read by another supported Fory runtime. Register portable model types with +Kotlin payloads must be read by another supported Fory implementation. Register portable model types with the same identity and field schema on every peer. Kotlin data classes, enums, and sealed-class models use the Kotlin integration and generated diff --git a/docs/object-serialization/kotlin/index.md b/docs/object-serialization/kotlin/index.md index 5b5910fff2..77dda3e8c9 100644 --- a/docs/object-serialization/kotlin/index.md +++ b/docs/object-serialization/kotlin/index.md @@ -65,8 +65,10 @@ implementation("org.apache.fory:fory-kotlin:1.5.0") ### JDK25+ -Kotlin uses the Fory Java core when running. On JDK25+, open `java.lang.invoke` -to Fory. Use `ALL-UNNAMED` when Fory is on the classpath: +Kotlin uses the Fory Java core when running. On JDK25+, opening `java.lang.invoke` to Fory core is +not required, but is recommended. It avoids the current-JDK Unsafe fallback and is required when Unsafe +access is disabled or unavailable, including with `--sun-misc-unsafe-memory-access=deny`. Use +`ALL-UNNAMED` when Fory is on the classpath: ```bash --add-opens=java.base/java.lang.invoke=ALL-UNNAMED diff --git a/docs/object-serialization/kotlin/native.md b/docs/object-serialization/kotlin/native.md index 99a88b9670..58b0415cdd 100644 --- a/docs/object-serialization/kotlin/native.md +++ b/docs/object-serialization/kotlin/native.md @@ -190,7 +190,7 @@ The following types work with the default Fory Java implementation: Use `ForyKotlin.builder()` for Kotlin-specific types such as unsigned values, ranges, and `Duration`. -Use native mode for Kotlin/JVM-only traffic that needs Kotlin data classes, -nullable types, ranges, unsigned values, or Kotlin collections on the JVM runtime -path. Choose registration and thread-safety settings for the application in +Use native mode for Kotlin/JVM-only traffic with Kotlin data classes, nullable +types, ranges, unsigned values, or Kotlin collections. Choose registration and +thread-safety settings for the application in [Kotlin Configuration](configuration.md). diff --git a/docs/object-serialization/kotlin/security.md b/docs/object-serialization/kotlin/security.md index 56bbafd556..84340916c5 100644 --- a/docs/object-serialization/kotlin/security.md +++ b/docs/object-serialization/kotlin/security.md @@ -33,7 +33,7 @@ Before deserialization: first root operation. - Validate the deserialized value against application authorization and domain rules before use. -## Runtime safeguards +## Built-in safeguards Kotlin uses the Java configuration surface. Keep class registration enabled for production and any untrusted payload source: @@ -68,7 +68,7 @@ Security-related configuration: Add negative tests for the boundary as well as normal round trips. Verify that the configured reader rejects unexpected application types, excessive nesting, resource-limit violations, and malformed -input. After a failed read, verify that a valid root can still be read with the reusable runtime. +input. After a failed read, verify that a valid root can still be read with the same Fory instance. See [Configuration](configuration.md) for the Kotlin option reference and [Java Type Registration](../java/type-registration.md) for the underlying registration API. diff --git a/docs/object-serialization/native.md b/docs/object-serialization/native.md index d5bf9a87dc..d6a3e3d03d 100644 --- a/docs/object-serialization/native.md +++ b/docs/object-serialization/native.md @@ -19,18 +19,152 @@ license: | limitations under the License. --- -Native serialization uses a binding-specific wire format and the owning runtime's native type -system. It is not one shared cross-language protocol. +Native serialization uses an implementation-specific wire format and the host language's native +type system. Choose it when every writer and reader uses the same Fory implementation family and +the payload should preserve language-specific types or behavior. Native payloads from different +implementation families are not interchangeable. -## When to use native mode +Use [xlang serialization](xlang.md) whenever a peer with a different native wire format must read +the bytes. Xlang uses a shared type system and wire format; native mode deliberately stays closer to +the implementation family's native object model. -Use native mode for same-runtime traffic that needs language-specific object shapes, migration from -a host serializer, or a smaller/faster format without xlang type-mapping constraints. Use -[xlang mode](xlang.md) whenever a different runtime must read the bytes. +Native and xlang type support overlap. A type listed on this page is not necessarily exclusive to +native mode; many language-native carriers also work in xlang when they have a portable mapping. +Choose the mode from the data boundary and required wire contract first, then check the language's +type mapping for the specific model. -## Supported runtime families +## When To Use Native Mode -- [Java](java/native.md), including the JVM path used by Scala and Kotlin +Native mode is the right choice when: + +- every producer and consumer uses one Fory implementation family; +- the object graph contains language-specific types or behavior outside the portable xlang type + mapping; +- an application is moving from an existing same-language serializer and should keep its current + object model instead of introducing a cross-language schema; or +- stored or transported data stays within one implementation family rather than a contract shared + across implementation families. + +Use xlang instead when peers use different Fory implementation families, when the contract must +remain language-independent, or when portability is more important than the full native object +surface. + +| Scenario | Recommended mode | +| ------------------------------------------------------------- | ---------------- | +| One implementation family with language-specific types | Native | +| Replacement for an existing same-language object serializer | Native | +| Data exchanged across Fory implementation families | Xlang | +| A long-lived contract intended to remain language-independent | Xlang | + +## Java + +Choose [Java native serialization](java/native.md) for Java/JVM-only payloads that need a broader +Java object surface than the portable xlang mapping. This includes ordinary Java objects, records, +enums, primitive and object arrays, common JDK collections and wrappers, interfaces, inheritance, +shared references, and circular object graphs. + +Java native mode also supports classes that use JDK serialization hooks: + +- `writeObject` and `readObject`; +- `writeReplace` and `readResolve`; +- `readObjectNoData`; and +- `Externalizable`. + +Fory honors these hooks while writing Fory native bytes; it does not emit Java +`ObjectOutputStream` bytes. See [JDK Custom Serialization](java/jdk-serialization.md) for the exact +semantics. + +Use Java native mode when replacing Java-only use of Kryo, FST, Hessian, or JDK serialization and +the existing Java object model should remain the serialization model. + +## Python + +Choose [Python native serialization](python/native.md) for Python-only payloads that need Python +objects beyond the portable xlang surface. Native mode supports classes, global and local +functions, lambdas, closures, instance methods, class methods, static methods, shared references, +and circular object graphs. + +It also supports Python object construction and state hooks, including: + +- `__getstate__` and `__setstate__`; +- `__getnewargs__` and `__getnewargs_ex__`; and +- `__reduce__` and `__reduce_ex__`. + +Use it when replacing Pickle or cloudpickle for a Python-only object graph. It is also an option for +replacing a Python-only MessagePack boundary when both endpoints move to Fory and the application +wants to serialize Python objects directly. If MessagePack is currently used as a language-neutral +exchange format, use xlang instead. + +See [Functions, Classes, and Methods](python/functions-classes-methods.md) and +[Serialization Hooks](python/serialization-hooks.md) for the supported Python object shapes and +reconstruction behavior. + +## Rust + +Choose [Rust native serialization](rust/native.md) when every endpoint is Rust and the payload +should use the Rust-specific wire format. This choice does not mean common Rust containers, +`Rc<T>`, `Arc<T>`, trait objects, or `dyn Any` are unavailable in xlang. Those carriers can also +participate in xlang when their selected concrete types have portable mappings. Use the +[Xlang Type Mapping](../specification/xlang_type_mapping.md) and the Rust language guide to check the +exact model. + +One native-specific shape is a data-carrying, struct-style enum whose variants contain multiple +fields directly. In native mode, a `#[derive(ForyUnion)]` enum can mix unit variants, tuple variants +with one or more fields, and named variants with one or more fields: + +```rust +use fory::ForyUnion; + +#[derive(ForyUnion)] +enum Command { + #[fory(default)] + Idle, + Move(i32, i32), + Create { id: u128, label: String }, +} +``` + +An xlang UNION alternative carries at most one declared payload value. Multiple logical fields must +be wrapped in an explicitly declared struct for xlang, while Rust native mode can encode the tuple +or named fields directly. See [Rust Enum Support](rust/schema-evolution.md#enum-support) and +[External-Type Serialization](rust/external-types.md#native-struct-style-enums) for local and +third-party enum shapes. + +## C++ + +Choose [C++ native serialization](cpp/native.md) when every endpoint is C++ and the data model +should use the C++-specific wire format. Standard containers, structs and classes, +`std::optional`, `std::variant`, tuple-like values, smart pointers, and supported scalar carriers +are not categorically native-only; they can also work in xlang when the corresponding portable +mapping exists. + +Choose native mode because the boundary is C++-only or because the particular model needs a +C++-specific representation, not merely because it uses a C++ standard-library type. Use +[Supported Types](cpp/supported-types.md) for the exact native and xlang mappings. + +## Migrating From Another Serializer + +Native mode is a replacement serialization path, not a decoder for another library's wire format. +Kryo, FST, Hessian, JDK serialization, Pickle, cloudpickle, and MessagePack bytes do not become Fory +native bytes automatically. + +Move writers and readers to the corresponding Fory implementation family together. If existing +stored data must remain readable during migration, keep the previous decoder at that boundary and +reserialize values with Fory as they are migrated. Do not use native mode for a boundary that still +has readers using a different native wire format. + +## Enable Native Mode + +| Language | Native-mode configuration | +| -------- | ----------------------------------------- | +| Java | `Fory.builder().withXlang(false).build()` | +| Python | `pyfory.Fory(xlang=False)` | +| C++ | `Fory::builder().xlang(false).build()` | +| Rust | `Fory::builder().xlang(false).build()` | + +## Language Guides + +- [Java](java/native.md) - [Python](python/native.md) - [C++](cpp/native.md) - [Go](go/native.md) @@ -38,5 +172,5 @@ a host serializer, or a smaller/faster format without xlang type-mapping constra - [Scala](scala/native.md) - [Kotlin](kotlin/native.md) -Each runtime page owns its exact object model, schema rules, configuration, extension APIs, and -diagnostics. Native payloads from different runtime families are not interchangeable. +Each language guide owns its exact supported types, configuration, schema behavior, extension APIs, +and diagnostics. diff --git a/docs/object-serialization/python/basic-serialization.md b/docs/object-serialization/python/basic-serialization.md index 489bc77929..b7245315d6 100644 --- a/docs/object-serialization/python/basic-serialization.md +++ b/docs/object-serialization/python/basic-serialization.md @@ -106,7 +106,7 @@ for obj in objects: ## Cross-Language Interoperability -The default xlang format is shared by all Fory runtimes. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. +The default xlang format is shared by all supported Fory implementations. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. `pyfory` supports xlang object graph serialization, allowing you to serialize data in Python and deserialize it in Java, C++, Go, Rust, diff --git a/docs/object-serialization/python/schema-metadata.md b/docs/object-serialization/python/schema-metadata.md index 913cafb4f8..e7359c96a9 100644 --- a/docs/object-serialization/python/schema-metadata.md +++ b/docs/object-serialization/python/schema-metadata.md @@ -320,7 +320,7 @@ class Counters: ``` For `values`, map keys are written as fixed-width int32 values and each nested list element is -written as tagged int64. Runtime type inference is used only for dynamic or unknown container +written as tagged int64. Value-based type inference is used only for dynamic or unknown container schemas. In compatible mode, readers consume field bytes using the remote schema metadata. Python assigns the diff --git a/docs/object-serialization/python/security.md b/docs/object-serialization/python/security.md index db9e96c980..df3c5cba6b 100644 --- a/docs/object-serialization/python/security.md +++ b/docs/object-serialization/python/security.md @@ -33,7 +33,7 @@ Before deserialization: first root operation. - Validate the deserialized value against application authorization and domain rules before use. -## Runtime safeguards +## Built-in safeguards Treat native-mode bytes from untrusted sources the same way you would treat untrusted pickle bytes. Native mode can reconstruct Python objects, import modules, invoke reduction hooks, and rebuild @@ -157,7 +157,7 @@ unchanged. Add negative tests for the boundary as well as normal round trips. Verify that the configured reader rejects unexpected application types, excessive nesting, resource-limit violations, and malformed -input. After a failed read, verify that a valid root can still be read with the reusable runtime. +input. After a failed read, verify that a valid root can still be read with the same Fory instance. See [Configuration](configuration.md) for the complete option reference and -[Type Registration](type-registration.md) for the runtime's registration API. +[Type Registration](type-registration.md) for the Fory registration API. diff --git a/docs/object-serialization/rust/basic-serialization.md b/docs/object-serialization/rust/basic-serialization.md index b8fcf9e873..08e189570e 100644 --- a/docs/object-serialization/rust/basic-serialization.md +++ b/docs/object-serialization/rust/basic-serialization.md @@ -211,7 +211,7 @@ all supported carriers, and registration. ## Cross-Language Interoperability -The default xlang format is shared by all Fory runtimes. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. +The default xlang format is shared by all supported Fory implementations. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. Apache Foryβ’ supports seamless data exchange across Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Swift, Dart, Scala, and Kotlin. diff --git a/docs/object-serialization/rust/configuration.md b/docs/object-serialization/rust/configuration.md index f5fb04eefc..1ba92cd25b 100644 --- a/docs/object-serialization/rust/configuration.md +++ b/docs/object-serialization/rust/configuration.md @@ -126,7 +126,7 @@ let fory = Fory::builder() .build(); ``` -Zero is rejected when the runtime is created. +Zero is rejected when the Fory instance is created. ### Unbacked Container Work Budget diff --git a/docs/object-serialization/rust/external-types.md b/docs/object-serialization/rust/external-types.md index 39a51fbf7a..735c33e7e5 100644 --- a/docs/object-serialization/rust/external-types.md +++ b/docs/object-serialization/rust/external-types.md @@ -108,7 +108,7 @@ enum ValueSerializer { } ``` -The target must represent the same runtime unknown carrier for lossless xlang +The target must represent the same in-memory unknown-case carrier for lossless xlang union reads. A third-party crate can remain independent of Fory by declaring a generic enum such as `Value<U>`; the application sets the serializer target to `Value<UnknownCase>`. A target that cannot carry unknown cases is not eligible diff --git a/docs/object-serialization/rust/index.md b/docs/object-serialization/rust/index.md index 6f1156060e..0db68ae3d0 100644 --- a/docs/object-serialization/rust/index.md +++ b/docs/object-serialization/rust/index.md @@ -35,16 +35,16 @@ The Rust implementation provides versatile and high-performance serialization wi ## Crates -| Crate | Description | Version | -| --------------------------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------- | -| [`fory`](https://github.com/apache/fory/blob/main/rust/fory) | User-facing API, runtime types, and derive macros | [1.5.0](https://crates.io/crates/fory) | -| [`fory-core`](https://github.com/apache/fory/blob/main/rust/fory-core/) | Lower-level runtime crate for advanced integrations | [1.5.0](https://crates.io/crates/fory-core) | -| [`fory-derive`](https://github.com/apache/fory/blob/main/rust/fory-derive/) | Lower-level procedural macro crate for direct runtime use | [1.5.0](https://crates.io/crates/fory-derive) | +| Crate | Description | Version | +| --------------------------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------- | +| [`fory`](https://github.com/apache/fory/blob/main/rust/fory) | User-facing API, public Fory types, and derive macros | [1.5.0](https://crates.io/crates/fory) | +| [`fory-core`](https://github.com/apache/fory/blob/main/rust/fory-core/) | Lower-level core crate for advanced integrations | [1.5.0](https://crates.io/crates/fory-core) | +| [`fory-derive`](https://github.com/apache/fory/blob/main/rust/fory-derive/) | Procedural macro crate for direct derive-macro use | [1.5.0](https://crates.io/crates/fory-derive) | Most applications should depend on `fory` only. It re-exports the derive -macros and the public runtime types needed by generated code. Use `fory-core` +macros and the public Fory types needed by generated code. Use `fory-core` or `fory-derive` directly only when intentionally building on the lower-level -runtime crates. +crates. ## Quick Start diff --git a/docs/object-serialization/rust/native.md b/docs/object-serialization/rust/native.md index 084d6ab118..751a71aaba 100644 --- a/docs/object-serialization/rust/native.md +++ b/docs/object-serialization/rust/native.md @@ -108,7 +108,7 @@ Native serialization owns the Rust-specific object surface: - `Box<T>`, `Rc<T>`, `Arc<T>`, `RcWeak<T>`, and `ArcWeak<T>`. - `RefCell<T>` and `Mutex<T>`. - Trait objects such as `Box<dyn Trait>`, `Rc<dyn Trait>`, and `Arc<dyn Trait>`. -- Runtime type dispatch with `Box<dyn Any>`, `Rc<dyn Any>`, and +- Dynamic type dispatch with `Box<dyn Any>`, `Rc<dyn Any>`, and `Arc<dyn Any + Send + Sync>` for registered non-container payloads. Wrap containers in registered structs, enums, or unions, or register an exact-target custom serializer when an opaque EXT/NAMED_EXT representation diff --git a/docs/object-serialization/rust/polymorphism.md b/docs/object-serialization/rust/polymorphism.md index 47ac16ede8..783dee315b 100644 --- a/docs/object-serialization/rust/polymorphism.md +++ b/docs/object-serialization/rust/polymorphism.md @@ -61,7 +61,7 @@ impl Animal for Cat { register_trait_type!(Animal, Dog, Cat); ``` -The concrete list contains runtime value types. Each type must also be +The concrete list contains concrete Rust value types. Each type must also be registered with the `Fory` instance: ```rust diff --git a/docs/object-serialization/rust/security.md b/docs/object-serialization/rust/security.md index 7a17d95fec..abc79510c3 100644 --- a/docs/object-serialization/rust/security.md +++ b/docs/object-serialization/rust/security.md @@ -33,7 +33,7 @@ Before deserialization: first root operation. - Validate the deserialized value against application authorization and domain rules before use. -## Runtime safeguards +## Built-in safeguards Security-related configuration: @@ -52,7 +52,7 @@ Security-related configuration: Add negative tests for the boundary as well as normal round trips. Verify that the configured reader rejects unexpected application types, excessive nesting, resource-limit violations, and malformed -input. After a failed read, verify that a valid root can still be read with the reusable runtime. +input. After a failed read, verify that a valid root can still be read with the same Fory instance. See [Configuration](configuration.md) for the complete option reference and -[Type Registration](type-registration.md) for the runtime's registration API. +[Type Registration](type-registration.md) for the Fory registration API. diff --git a/docs/object-serialization/rust/type-registration.md b/docs/object-serialization/rust/type-registration.md index 162eb4a954..87fe456587 100644 --- a/docs/object-serialization/rust/type-registration.md +++ b/docs/object-serialization/rust/type-registration.md @@ -76,7 +76,7 @@ API: fory.register::<UserSerializer>(101)?; ``` -The serializer's `Target` is the runtime value type. Registration does not +The serializer's `Target` is the Rust value type. Registration does not require a separate external-type API. At fields, `with` can select an exact carrier serializer such as `VecSerializer<UserSerializer>`, while recursive `list`, `map`, or `tuple` annotations select serializers at child nodes. At diff --git a/docs/object-serialization/scala/index.md b/docs/object-serialization/scala/index.md index de1d3efec9..7a10630b66 100644 --- a/docs/object-serialization/scala/index.md +++ b/docs/object-serialization/scala/index.md @@ -54,8 +54,10 @@ libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.5.0" ### JDK25+ -Scala uses the Fory Java core when running. On JDK25+, open `java.lang.invoke` to -Fory. Use `ALL-UNNAMED` when Fory is on the classpath: +Scala uses the Fory Java core when running. On JDK25+, opening `java.lang.invoke` to Fory core is +not required, but is recommended. It avoids the current-JDK Unsafe fallback and is required when Unsafe +access is disabled or unavailable, including with `--sun-misc-unsafe-memory-access=deny`. Use +`ALL-UNNAMED` when Fory is on the classpath: ```bash --add-opens=java.base/java.lang.invoke=ALL-UNNAMED diff --git a/docs/object-serialization/scala/native.md b/docs/object-serialization/scala/native.md index 20fd963b97..105ab4ab30 100644 --- a/docs/object-serialization/scala/native.md +++ b/docs/object-serialization/scala/native.md @@ -178,6 +178,6 @@ val employee = Employee( println(fory.deserialize(fory.serialize(employee))) ``` -Use native mode for Scala/JVM-only traffic that needs Scala case classes, -collections, tuples, options, or enums on the JVM runtime path. See +Use native mode for Scala/JVM-only traffic with Scala case classes, collections, +tuples, options, or enums. See [Scala Configuration](configuration.md) for production builder settings. diff --git a/docs/object-serialization/scala/security.md b/docs/object-serialization/scala/security.md index f5f40c61c7..529f5fb9f9 100644 --- a/docs/object-serialization/scala/security.md +++ b/docs/object-serialization/scala/security.md @@ -33,7 +33,7 @@ Before deserialization: first root operation. - Validate the deserialized value against application authorization and domain rules before use. -## Runtime safeguards +## Built-in safeguards Scala uses the Java configuration surface. Keep class registration enabled for production and any untrusted payload source: @@ -68,7 +68,7 @@ Security-related configuration: Add negative tests for the boundary as well as normal round trips. Verify that the configured reader rejects unexpected application types, excessive nesting, resource-limit violations, and malformed -input. After a failed read, verify that a valid root can still be read with the reusable runtime. +input. After a failed read, verify that a valid root can still be read with the same Fory instance. See [Configuration](configuration.md) for the Scala option reference and [Java Type Registration](../java/type-registration.md) for the underlying registration API. diff --git a/docs/object-serialization/swift/basic-serialization.md b/docs/object-serialization/swift/basic-serialization.md index 1f1eaadb3f..4374739db7 100644 --- a/docs/object-serialization/swift/basic-serialization.md +++ b/docs/object-serialization/swift/basic-serialization.md @@ -177,7 +177,7 @@ See [Polymorphism and Dynamic Types](polymorphism.md). ## Cross-Language Interoperability -The default xlang format is shared by all Fory runtimes. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. +The default xlang format is shared by all Fory implementations. The following sections cover its cross-language type mapping, type identity, and interoperability requirements. Fory Swift can exchange payloads with other Fory implementations using the xlang protocol. diff --git a/docs/object-serialization/swift/configuration.md b/docs/object-serialization/swift/configuration.md index 1d3bae58ad..5961790a2a 100644 --- a/docs/object-serialization/swift/configuration.md +++ b/docs/object-serialization/swift/configuration.md @@ -105,7 +105,7 @@ skips leaf values such as strings, binary data, primitive scalars, and dense pri actual process memory can be higher than this value. Leaf values remain protected by byte-availability checks: if the unread input does not contain enough bytes, Fory will not read or create that leaf value. The default limit is a fixed `128 MiB` for all root input forms. A positive -value overrides the default. Explicit non-positive values are rejected when the runtime is created. +value overrides the default. Explicit non-positive values are rejected when the Fory instance is created. `maxUnbackedContainerItems` limits collection elements and map entries whose repeated read bodies do not consume proportional input during one root diff --git a/docs/object-serialization/swift/security.md b/docs/object-serialization/swift/security.md index a03e6c58b5..53dec527d8 100644 --- a/docs/object-serialization/swift/security.md +++ b/docs/object-serialization/swift/security.md @@ -33,7 +33,7 @@ Before deserialization: first root operation. - Validate the deserialized value against application authorization and domain rules before use. -## Runtime safeguards +## Built-in safeguards Security-related configuration: @@ -50,7 +50,7 @@ Security-related configuration: Add negative tests for the boundary as well as normal round trips. Verify that the configured reader rejects unexpected application types, excessive nesting, resource-limit violations, and malformed -input. After a failed read, verify that a valid root can still be read with the reusable runtime. +input. After a failed read, verify that a valid root can still be read with the same Fory instance. See [Configuration](configuration.md) for the complete option reference and -[Type Registration](type-registration.md) for the runtime's registration API. +[Type Registration](type-registration.md) for the Fory registration API. diff --git a/docs/object-serialization/xlang.md b/docs/object-serialization/xlang.md index bfd8ea7b4f..09b7993b7c 100644 --- a/docs/object-serialization/xlang.md +++ b/docs/object-serialization/xlang.md @@ -20,16 +20,16 @@ license: | --- Xlang is Fory's default object serialization mode. It uses one portable binary format across Java, -Python, C++, Go, Rust, JavaScript/TypeScript, C#, Swift, Dart, Scala, and Kotlin. Each runtime's -[Basic Serialization](#runtime-guides) page owns its API and model examples; this page explains the -rules that peers must share. +Python, C++, Go, Rust, JavaScript/TypeScript, C#, Swift, Dart, Scala, and Kotlin. Each +language-specific [Basic Serialization](#language-guides) page documents the relevant API and model +examples; this page explains the rules that peers must share. Read [Core Concepts](core-concepts.md) first for the object graph, schema, reference, and polymorphism concepts shared by xlang and native modes. ## Overview -Use xlang serialization when bytes cross runtime boundaries, including polyglot services, data +Use xlang serialization when bytes cross language boundaries, including polyglot services, data pipelines, and frontend/backend communication. It provides: - Direct serialization of native language models without requiring an IDL. @@ -37,15 +37,15 @@ pipelines, and frontend/backend communication. It provides: - Compatible schema evolution for independently deployed peers. - Optional shared-reference and circular-reference preservation. - Polymorphic values when every concrete type has a portable mapping. -- Out-of-band buffers for large binary and numeric data where the runtime supports them. +- Out-of-band buffers for large binary and numeric data where the Fory implementation supports them. -Use [Native Serialization](native.md) instead when every writer and reader uses the same supported -runtime and the object graph needs language-specific behavior such as Java serialization hooks or -Python pickle-compatible objects. +Use [Native Serialization](native.md) instead when every writer and reader uses one supported Fory +implementation family and the object graph needs language-specific behavior such as Java +serialization hooks or Python pickle-compatible objects. -### Supported Runtimes +### Supported Languages -| Runtime | Package or target | Modes | +| Language | Package or target | Modes | | --------------------- | ------------------------------------------ | ------------ | | Java | `org.apache.fory:fory-core` | xlang/native | | Python | `pyfory` | xlang/native | @@ -124,7 +124,7 @@ message Person { } ``` -Generate the required runtime targets with `foryc`; generated models use consistent field and type +Generate the required language targets with `foryc`; generated models use consistent field and type metadata across those targets. ## Type System and Type Identity @@ -141,9 +141,9 @@ carrier for every xlang type. Important cases include: - Python uses markers such as `pyfory.Int32`, `pyfory.Float16`, and `pyfory.BFloat16` when the native Python type does not express the required width. -- Java, Dart, and other runtimes use annotations or schema metadata where one host type can represent +- Java, Dart, and other languages use annotations or schema metadata where one host type can represent multiple xlang types. -- Reduced-precision `float16` and `bfloat16` values and dense arrays use runtime-specific carriers. +- Reduced-precision `float16` and `bfloat16` values and dense arrays use language-specific carriers. - `list<T>` and dense `array<T>` are distinct schemas. In compatible mode, a direct struct field may adapt between a list and dense bool/numeric array when the element domain is compatible and the actual list contains no unrepresentable null or reference-tracked element. @@ -161,22 +161,22 @@ small contract registry or use generated Fory IDL modules when multiple teams ow ### Static and Dynamic Fields -A statically known field uses its declared serializer without writing a concrete runtime type. A +A statically known field uses its declared serializer without writing a concrete type. A dynamic field carries enough type information to select the concrete registered type. Dynamic metadata is needed for interfaces, abstract types, trait objects, and other polymorphic positions; it is unnecessary for primitives and exact final types. -| Runtime | Dynamic field model | -| ------- | ----------------------------------------------------------------- | -| Java | `@ForyField(dynamic = ...)` controls automatic or forced metadata | -| Python | `pyfory.field(dynamic=...)` controls object-field metadata | -| C++ | `fory::F(...).dynamic(...)` overrides automatic detection | -| Go | Interface fields express dynamic values | -| Rust | Trait-object carriers express dynamic values | +| Language | Dynamic field model | +| -------- | ----------------------------------------------------------------- | +| Java | `@ForyField(dynamic = ...)` controls automatic or forced metadata | +| Python | `pyfory.field(dynamic=...)` controls object-field metadata | +| C++ | `fory::F(...).dynamic(...)` overrides automatic detection | +| Go | Interface fields express dynamic values | +| Rust | Trait-object carriers express dynamic values | Writing dynamic metadata costs space and type-resolution work. Disable it only when the field can never contain another concrete type. Exact annotation and registration examples belong to each -runtime's schema metadata, type registration, and polymorphism pages. +language's schema metadata, type registration, and polymorphism pages. ## Nullability and Reference Tracking @@ -189,7 +189,8 @@ Nullability and reference tracking solve different problems: The wire framing is defined by the [xlang serialization specification](../specification/xlang_serialization_spec.md). Applications -should configure the semantic behavior through runtime APIs rather than depend on flag values. +should configure the semantic behavior through their language-specific Fory APIs rather than depend +on flag values. ### Nullability @@ -227,9 +228,9 @@ Fory fory = Fory.builder() .build(); ``` -Global reference tracking enables the runtime mechanism; field metadata selects which positions +Global reference tracking enables the reference-tracking mechanism; field metadata selects which positions participate. Common field-level controls are Java and Scala `@Ref`, Go `fory:"ref"` tags, Rust -`#[fory(ref = true)]`, and C++ smart-pointer or `fory::F().ref()` metadata. Consult the runtime guide +`#[fory(ref = true)]`, and C++ smart-pointer or `fory::F().ref()` metadata. Consult the language guide because default tracking differs by carrier and language. Reference support also follows the host ownership model. For example, Rust can preserve supported @@ -242,12 +243,12 @@ element, or root type is broader. Every receiving peer must: 1. Register the same concrete type identity. 2. Provide a compatible field schema for that concrete type. -3. Mark or model the position as dynamic when the runtime cannot infer it. +3. Mark or model the position as dynamic when the Fory implementation cannot infer it. 4. Use a concrete type that has a portable xlang mapping. Host-language inheritance alone does not make a type portable. If a shape has no xlang mapping, use -the runtime's native mode for same-language traffic or define a portable model. See the runtime -polymorphism pages for interfaces, trait objects, unions, and generated-code syntax. +native mode for traffic within one Fory implementation family or define a portable model. See the +language polymorphism pages for interfaces, trait objects, unions, and generated-code syntax. ## Schema Evolution @@ -270,7 +271,7 @@ together. Normative compatibility behavior lives in the ## Zero-Copy Serialization -Some runtimes can move large binary or numeric buffers out of the main serialized byte stream. This +Some Fory implementations can move large binary or numeric buffers out of the main serialized byte stream. This avoids copying those buffers into one contiguous payload. The transport flow is: @@ -300,7 +301,7 @@ decoded = fory.deserialize(metadata, buffers=buffers) ``` Go exposes the equivalent callback-buffer flow through its serialization and buffer APIs. Use the -runtime documentation for the current method names and supported buffer carriers. +language guide for the current method names and supported buffer carriers. Out-of-band serialization helps when buffers are large and the transport can send them without an additional copy. For small arrays, callback and multi-buffer transport overhead may cost more than @@ -309,33 +310,33 @@ copying. The application owns buffer ordering, lifetime, and transport framing. ## Troubleshooting -| Symptom | Likely cause | Resolution | -| ---------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------- | -| Type is not registered | Registration missing or performed too late | Register every custom type before the first root operation | -| Type ID or name mismatch | Peers use different identities | Use the same numeric ID or the same namespace and type name | -| Integer overflow or float precision loss | Host carriers use different numeric widths | Follow the type mapping and use explicit width metadata | -| Fields decode incorrectly | Field IDs, names, or types differ | Align field metadata or regenerate all peers from the same IDL | -| Stack overflow on a cyclic graph | Reference tracking is disabled | Enable global and field-level reference tracking | -| Shared objects become duplicates | The value position does not track references | Enable reference tracking for that carrier or field | -| Unsupported host type | The type has no portable xlang representation | Use a portable model or native mode for same-language traffic | -| Schema/hash mismatch | Same-schema peers have different schemas | Align every peer or restore compatible mode | -| Failure after an upgrade | Peers run incompatible protocol versions | Align supported Fory versions and review release notes | -| Payload rejected immediately | One peer wrote native bytes and another reads xlang | Keep all peers on xlang for a cross-language contract | +| Symptom | Likely cause | Resolution | +| ---------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------- | +| Type is not registered | Registration missing or performed too late | Register every custom type before the first root operation | +| Type ID or name mismatch | Peers use different identities | Use the same numeric ID or the same namespace and type name | +| Integer overflow or float precision loss | Host carriers use different numeric widths | Follow the type mapping and use explicit width metadata | +| Fields decode incorrectly | Field IDs, names, or types differ | Align field metadata or regenerate all peers from the same IDL | +| Stack overflow on a cyclic graph | Reference tracking is disabled | Enable global and field-level reference tracking | +| Shared objects become duplicates | The value position does not track references | Enable reference tracking for that carrier or field | +| Unsupported host type | The type has no portable xlang representation | Use a portable model or native mode within one Fory implementation family | +| Schema/hash mismatch | Same-schema peers have different schemas | Align every peer or restore compatible mode | +| Failure after an upgrade | Peers run incompatible protocol versions | Align supported Fory versions and review release notes | +| Payload rejected immediately | One peer wrote native bytes and another reads xlang | Keep all peers on xlang for a cross-language contract | ### Diagnostic Checklist 1. Confirm that every peer uses xlang mode and a mutually supported Fory version. 2. Compare the registered type identity, field IDs or names, numeric widths, nullability, and reference metadata. -3. Reproduce a same-runtime round trip before testing the cross-runtime direction. +3. Reproduce a local round trip in each Fory implementation before testing the cross-language direction. 4. Test both directions for every language pair used in production. 5. Reduce the value to one type and field, then add fields back until the mismatch appears. -6. Inspect the runtime-specific troubleshooting page for generated-code, platform, or API errors. +6. Inspect the language-specific troubleshooting page for generated-code, platform, or API errors. -When diagnosing binary layout, use the specifications and runtime debug facilities. Do not treat a +When diagnosing binary layout, use the specifications and implementation-specific debug facilities. Do not treat a hex dump or internal flag value as a stable application API. -## Runtime Guides +## Language Guides - [Java](java/basic-serialization.md#cross-language-interoperability) - [Python](python/basic-serialization.md#cross-language-interoperability) @@ -352,9 +353,9 @@ hex dump or internal flag value as a stable application API. ## Related Documentation - [Xlang Serialization Format](../specification/xlang_serialization_spec.md) β normative wire format -- [Xlang Type Mapping](../specification/xlang_type_mapping.md) β exact runtime carrier mappings +- [Xlang Type Mapping](../specification/xlang_type_mapping.md) β exact host-language carrier mappings - [Fory IDL and Compiler](../compiler/index.md) β schema-first models and code generation -- [Getting Started](../start/index.md) β installation and first serialization for each runtime +- [Getting Started](../start/index.md) β installation and first serialization for each language - [Row Format](../row-format/index.md) β random-access analytical rows for trusted data ## Operational Best Practices --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
