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 aeb93217a43e906f34889a0f95d9decbd1b1e06f Author: chaokunyang <[email protected]> AuthorDate: Thu Jun 4 11:33:57 2026 +0000 🔄 synced local 'docs/guide/' with remote 'docs/guide/' --- docs/guide/cpp/custom-serializers.md | 4 ++-- docs/guide/cpp/native-serialization.md | 6 +++--- docs/guide/csharp/custom-serializers.md | 6 ++++++ docs/guide/csharp/index.md | 2 +- docs/guide/csharp/type-registration.md | 19 ++++++++++++++----- docs/guide/csharp/xlang-serialization.md | 4 ++-- docs/guide/dart/basic-serialization.md | 3 +-- docs/guide/dart/code-generation.md | 5 ++--- docs/guide/dart/configuration.md | 4 ++-- docs/guide/dart/custom-serializers.md | 5 ++--- docs/guide/dart/index.md | 10 ++++------ docs/guide/dart/schema-evolution.md | 4 ++-- docs/guide/dart/troubleshooting.md | 2 +- docs/guide/dart/type-registration.md | 13 ++++++------- docs/guide/dart/web-platform-support.md | 3 +-- docs/guide/dart/xlang-serialization.md | 5 ++--- docs/guide/go/troubleshooting.md | 2 +- docs/guide/go/type-registration.md | 4 ++-- docs/guide/java/basic-serialization.md | 3 +-- docs/guide/java/type-registration.md | 10 +++++++--- docs/guide/java/xlang-serialization.md | 2 +- docs/guide/javascript/schema-evolution.md | 2 +- docs/guide/javascript/schema-metadata.md | 8 +++++--- docs/guide/javascript/type-registration.md | 15 +++------------ docs/guide/javascript/xlang-serialization.md | 2 +- docs/guide/kotlin/android-support.md | 2 +- docs/guide/kotlin/static-generated-serializers.md | 2 +- docs/guide/python/basic-serialization.md | 4 ++-- docs/guide/python/configuration.md | 12 ++++++------ docs/guide/python/custom-serializers.md | 4 ++-- docs/guide/python/schema-evolution.md | 4 ++-- docs/guide/python/troubleshooting.md | 4 ++-- docs/guide/python/type-registration.md | 6 +++--- docs/guide/python/xlang-serialization.md | 4 ++-- docs/guide/rust/basic-serialization.md | 4 ++-- docs/guide/rust/index.md | 10 +++++----- docs/guide/rust/native-serialization.md | 6 +++--- docs/guide/rust/type-registration.md | 7 ++++--- docs/guide/rust/xlang-serialization.md | 4 ++-- docs/guide/swift/type-registration.md | 8 ++------ docs/guide/swift/xlang-serialization.md | 2 +- docs/guide/xlang/field-nullability.md | 2 +- docs/guide/xlang/getting-started.md | 17 ++++++++--------- docs/guide/xlang/index.md | 2 +- docs/guide/xlang/serialization.md | 10 +++++----- docs/guide/xlang/troubleshooting.md | 2 +- 46 files changed, 129 insertions(+), 130 deletions(-) diff --git a/docs/guide/cpp/custom-serializers.md b/docs/guide/cpp/custom-serializers.md index 093d265d84..60b969ae61 100644 --- a/docs/guide/cpp/custom-serializers.md +++ b/docs/guide/cpp/custom-serializers.md @@ -157,8 +157,8 @@ if (!result.ok()) { // Or register with type name for named type systems fory.register_extension_type<MyExt>("my_ext"); -// Or with namespace and type name -fory.register_extension_type<MyExt>("com.example", "MyExt"); +// Or with a namespace prefix +fory.register_extension_type<MyExt>("com.example.MyExt"); ``` ## Complete Example diff --git a/docs/guide/cpp/native-serialization.md b/docs/guide/cpp/native-serialization.md index 0189d72a78..fcc9399bbe 100644 --- a/docs/guide/cpp/native-serialization.md +++ b/docs/guide/cpp/native-serialization.md @@ -104,11 +104,11 @@ Register structs with stable IDs or names before serialization: ```cpp fory.register_struct<Order>(100); -fory.register_struct<Order>("example", "Order"); +fory.register_struct<Order>("example.Order"); ``` -Use numeric IDs for compact payloads. Use namespace/type-name registration when independent teams -coordinate type identity by names. +Use numeric IDs for compact payloads. Use name registration when independent teams coordinate type +identity by names; add a namespace prefix with `.` when needed. ## C++ Object Surface diff --git a/docs/guide/csharp/custom-serializers.md b/docs/guide/csharp/custom-serializers.md index 9e7ef768f3..4db844dfe9 100644 --- a/docs/guide/csharp/custom-serializers.md +++ b/docs/guide/csharp/custom-serializers.md @@ -64,6 +64,12 @@ byte[] payload = fory.Serialize(value); Point decoded = fory.Deserialize<Point>(payload); ``` +Use the named overload when peers identify the type by name instead of a numeric ID: + +```csharp +fory.Register<Point, PointSerializer>("com.example.Point"); +``` + ## Serializer Behavior Notes - `WriteData` / `ReadData` only handle payload content. diff --git a/docs/guide/csharp/index.md b/docs/guide/csharp/index.md index 9d2e30f247..d2b7f8ecf5 100644 --- a/docs/guide/csharp/index.md +++ b/docs/guide/csharp/index.md @@ -79,7 +79,7 @@ User decoded = fory.Deserialize<User>(payload); - `Serialize<T>(in T value)` / `Deserialize<T>(...)` - `Serialize<object?>(...)` / `Deserialize<object?>(...)` for dynamic payloads -- `Register<T>(uint typeId)` and namespace/name registration APIs +- `Register<T>(uint typeId)` and name registration APIs - `Register<T, TSerializer>(...)` for custom serializers ## Documentation diff --git a/docs/guide/csharp/type-registration.md b/docs/guide/csharp/type-registration.md index fd1e088546..2434bcac98 100644 --- a/docs/guide/csharp/type-registration.md +++ b/docs/guide/csharp/type-registration.md @@ -33,19 +33,27 @@ fory.Register<Order>(101); ## Register by Type Name -Use namespace + type name registration when you prefer symbolic mappings. +Use name registration when you prefer symbolic mappings. The single-string overload accepts the +full user-facing name and splits it at the last dot. ```csharp Fory fory = Fory.Builder().Build(); -fory.Register<User>("com.example", "User"); +fory.Register<User>("com.example.User"); ``` -You can also use the short overload: +Names without dots use an empty namespace: ```csharp fory.Register<User>("User"); ``` +The split overload is also available when you already have the namespace and final type name +separately: + +```csharp +fory.Register<User>("com.example", "User"); +``` + ## Register a Custom Serializer ```csharp @@ -53,10 +61,10 @@ Fory fory = Fory.Builder().Build(); fory.Register<MyType, MyTypeSerializer>(200); ``` -Namespace-based custom serializer registration is also supported: +Name-based custom serializer registration is also supported: ```csharp -fory.Register<MyType, MyTypeSerializer>("com.example", "MyType"); +fory.Register<MyType, MyTypeSerializer>("com.example.MyType"); ``` ## Thread-Safe Registration @@ -73,6 +81,7 @@ fory.Register<Order>(101); - Register user-defined types on both writer and reader sides. - Keep ID/name mappings consistent across services and languages. +- For the split overloads, `typeName` must be non-empty and must not contain dots. - Register before high-volume serialization workloads to avoid runtime misses. ## Related Topics diff --git a/docs/guide/csharp/xlang-serialization.md b/docs/guide/csharp/xlang-serialization.md index d47b44dedb..d9e3492b30 100644 --- a/docs/guide/csharp/xlang-serialization.md +++ b/docs/guide/csharp/xlang-serialization.md @@ -52,10 +52,10 @@ fory.Register<Person>(100); Use the same ID mapping on all languages. -## Register by Namespace/Type Name +## Register by Name ```csharp -fory.Register<Person>("com.example", "Person"); +fory.Register<Person>("com.example.Person"); ``` ## Xlang Example diff --git a/docs/guide/dart/basic-serialization.md b/docs/guide/dart/basic-serialization.md index cabe692f51..5af05f8c5e 100644 --- a/docs/guide/dart/basic-serialization.md +++ b/docs/guide/dart/basic-serialization.md @@ -53,8 +53,7 @@ void main() { PersonForyModule.register( fory, Person, - namespace: 'example', - typeName: 'Person', + name: 'example.Person', ); final person = Person() diff --git a/docs/guide/dart/code-generation.md b/docs/guide/dart/code-generation.md index 8b3404bba5..85fca10db7 100644 --- a/docs/guide/dart/code-generation.md +++ b/docs/guide/dart/code-generation.md @@ -64,7 +64,7 @@ This emits a `.fory.dart` file next to your source file. Re-run this command any ## Step 3 — Register and Use -The generator creates a namespace (named after your file) with a `register` function. Call it before serializing: +The generator creates a Fory module class (named after your file) with a `register` function. Call it before serializing: ```dart final fory = Fory(); @@ -78,8 +78,7 @@ Or use a stable name instead of a numeric ID (useful for cross-language scenario ModelsForyModule.register( fory, User, - namespace: 'example', - typeName: 'User', + name: 'example.User', ); ``` diff --git a/docs/guide/dart/configuration.md b/docs/guide/dart/configuration.md index 52bd45c1c3..d7ce0e295f 100644 --- a/docs/guide/dart/configuration.md +++ b/docs/guide/dart/configuration.md @@ -54,7 +54,7 @@ final fory = Fory(); When `compatible: true`: - Adding or removing fields on one side does not break the other. -- Peers must still use the same `namespace` + `typeName` (or numeric `id`) to identify types. +- Peers must still use the same `name` (or numeric `id`) to identify types. When `compatible: false`: @@ -112,7 +112,7 @@ final fory = Fory(maxBinarySize: 8 * 1024 * 1024); When Fory is used to communicate between services written in different languages: - Keep compatible mode enabled on all sides if any side needs schema evolution. -- Use the same numeric IDs or `namespace + typeName` pairs on every side. +- Use the same numeric IDs or `name` values on every side. - Match the `compatible` setting on both the writing and reading side — mismatching modes will fail. ## Security diff --git a/docs/guide/dart/custom-serializers.md b/docs/guide/dart/custom-serializers.md index 6fad7a5608..4e76736411 100644 --- a/docs/guide/dart/custom-serializers.md +++ b/docs/guide/dart/custom-serializers.md @@ -66,8 +66,7 @@ final fory = Fory(); fory.registerSerializer( Person, const PersonSerializer(), - namespace: 'example', - typeName: 'Person', + name: 'example.Person', ); ``` @@ -130,7 +129,7 @@ Skipping this step causes back-references to that object to resolve to `null`. ## Tips - Use `context.buffer` for direct byte reads/writes in hot paths. -- Register the serializer with the same identity (`id` or `namespace + typeName`) on every side. +- Register the serializer with the same identity (`id` or `name`) on every side. ## Related Topics diff --git a/docs/guide/dart/index.md b/docs/guide/dart/index.md index 131ce0c3a2..c2d7df6178 100644 --- a/docs/guide/dart/index.md +++ b/docs/guide/dart/index.md @@ -83,14 +83,12 @@ void main() { PersonForyModule.register( fory, Color, - namespace: 'example', - typeName: 'Color', + name: 'example.Color', ); PersonForyModule.register( fory, Person, - namespace: 'example', - typeName: 'Person', + name: 'example.Person', ); final person = Person() @@ -111,7 +109,7 @@ Generate the companion file before running the program: dart run build_runner build --delete-conflicting-outputs ``` -`PersonForyModule` is generated by `build_runner`. The `namespace` and `typeName` values are how peers in other languages identify the same type; keep them stable once your service is in production. +`PersonForyModule` is generated by `build_runner`. The `name` value is how peers in other languages identify the same type; keep it stable once your service is in production. Use `.` inside `name` to add a namespace prefix. ## API Overview @@ -132,7 +130,7 @@ dart run build_runner build --delete-conflicting-outputs | ----------------------------------------------- | --------------------------------------------------------------- | | [Configuration](configuration.md) | Runtime options, compatible mode, and safety limits | | [Basic Serialization](basic-serialization.md) | `serialize`, `deserialize`, generated registration, root graphs | -| [Code Generation](code-generation.md) | `@ForyStruct`, build runner, and generated namespaces | +| [Code Generation](code-generation.md) | `@ForyStruct`, build runner, and generated modules | | [Xlang Serialization](xlang-serialization.md) | Interoperability rules and field alignment | | [Schema Metadata](schema-metadata.md) | `@ForyField`, field IDs, nullability, references, polymorphism | | [Type Registration](type-registration.md) | ID-based vs name-based registration and registration rules | diff --git a/docs/guide/dart/schema-evolution.md b/docs/guide/dart/schema-evolution.md index 53c0a82ba9..51777b8372 100644 --- a/docs/guide/dart/schema-evolution.md +++ b/docs/guide/dart/schema-evolution.md @@ -73,7 +73,7 @@ If you add field IDs after payloads are already in production, existing stored m - Reuse an existing field ID for a different field. - Change a field's type to an incompatible type (e.g., `@ForyField(type: Int32Type()) int` → `String`). -- Change the registration identity (`id`, `namespace`, or `typeName`) of a type after messages are in production. +- Change the registration identity (`id` or `name`) of a type after messages are in production. - Change a field's logical meaning without changing its ID. ## Xlang Notes @@ -81,7 +81,7 @@ If you add field IDs after payloads are already in production, existing stored m Evolution only works when **all** runtimes that exchange messages agree on: 1. The same `compatible` setting. -2. The same type registration identity (numeric ID or `namespace + typeName`). +2. The same type registration identity (numeric ID or `name`). 3. The logical meaning of field IDs. Test rolling-upgrade scenarios with real round trips before deploying. diff --git a/docs/guide/dart/troubleshooting.md b/docs/guide/dart/troubleshooting.md index 769b132122..b4e71d7b38 100644 --- a/docs/guide/dart/troubleshooting.md +++ b/docs/guide/dart/troubleshooting.md @@ -72,7 +72,7 @@ Symptoms: fields come back as default values or wrong types after a round trip t Checklist: -1. Same registration identity on both sides (same numeric ID **or** same `namespace + typeName`). +1. Same registration identity on both sides (same numeric ID **or** same `name`). 2. Stable `@ForyField(id: ...)` assigned before the first payload was produced. 3. Compatible numeric widths — use `@ForyField(type: Int32Type())` in Dart when the peer field is `int` (Java), `int32` (Go), or `int` (C#). 4. `Timestamp` / `LocalDate` instead of raw `DateTime` for date/time fields. diff --git a/docs/guide/dart/type-registration.md b/docs/guide/dart/type-registration.md index cd94c1489d..e91698c19d 100644 --- a/docs/guide/dart/type-registration.md +++ b/docs/guide/dart/type-registration.md @@ -40,7 +40,7 @@ The same number must be used in every other language: fory.register(User.class, 100); ``` -### Strategy 2: Namespace + Type Name +### Strategy 2: Name More self-describing. Good when multiple teams or packages define types independently and numeric ID coordination is impractical. @@ -48,12 +48,12 @@ More self-describing. Good when multiple teams or packages define types independ ModelsForyModule.register( fory, User, - namespace: 'example', - typeName: 'User', + name: 'example.User', ); ``` -Every runtime that reads or writes this type must use the same `namespace` and `typeName`. +Every runtime that reads or writes this type must use the same name. Use `.` inside `name` +to add a namespace prefix. > **Do not mix strategies for the same type.** If one side uses a numeric ID > and the other uses a name, deserialization will fail. @@ -73,8 +73,7 @@ For types that you cannot annotate with `@ForyStruct()`, pass a serializer insta fory.registerSerializer( ExternalType, const ExternalTypeSerializer(), - namespace: 'example', - typeName: 'ExternalType', + name: 'example.ExternalType', ); ``` @@ -89,7 +88,7 @@ See [Custom Serializers](custom-serializers.md) for how to implement a serialize ## Xlang Requirements -The same numeric ID or `namespace + typeName` pair must be used in every runtime that reads or writes the type. See [Xlang Serialization](xlang-serialization.md) for examples. +The same numeric ID or name must be used in every runtime that reads or writes the type. See [Xlang Serialization](xlang-serialization.md) for examples. ## Related Topics diff --git a/docs/guide/dart/web-platform-support.md b/docs/guide/dart/web-platform-support.md index 21280648c4..3a469037b0 100644 --- a/docs/guide/dart/web-platform-support.md +++ b/docs/guide/dart/web-platform-support.md @@ -61,8 +61,7 @@ void main() { AccountForyModule.register( fory, Account, - namespace: 'example', - typeName: 'Account', + name: 'example.Account', ); final bytes = fory.serialize(Account()..name = 'web'); diff --git a/docs/guide/dart/xlang-serialization.md b/docs/guide/dart/xlang-serialization.md index e146c129da..58e98e131c 100644 --- a/docs/guide/dart/xlang-serialization.md +++ b/docs/guide/dart/xlang-serialization.md @@ -53,8 +53,7 @@ Better when multiple teams define types independently: ModelsForyModule.register( fory, Person, - namespace: 'example', - typeName: 'Person', + name: 'example.Person', ); ``` @@ -158,7 +157,7 @@ _ = f.Deserialize(bytesFromDart, &person) Fory matches fields by name or by stable field ID. For robust cross-language interop: -1. Use the same type identity on every side (same numeric ID or same `namespace + typeName`). +1. Use the same type identity on every side (same numeric ID or same `name`). 2. Assign stable `@ForyField(id: ...)` values to all fields before shipping the first payload. 3. Keep field names consistent or rely on IDs, since Dart typically uses `lowerCamelCase` while Go uses `PascalCase` for exported fields and C# often uses `PascalCase` properties. 4. Use explicit numeric field metadata: `@ForyField(type: Int32Type())` in Dart for Java `int`, Go `int32`, and C# `int`; `double` in Dart for 64-bit floats; `double` plus `Float16Type` or `Bfloat16Type` for 16-bit floats; `Float32` for 32-bit; `Int64` / `Uint64` for full-range 64-bit values. diff --git a/docs/guide/go/troubleshooting.md b/docs/guide/go/troubleshooting.md index 5af317b053..54e352ca76 100644 --- a/docs/guide/go/troubleshooting.md +++ b/docs/guide/go/troubleshooting.md @@ -287,7 +287,7 @@ f.RegisterStructByName(User{}, "example.User") fory.register(User.class, "example.User"); // Python -fory.register(User, typename="example.User") +fory.register_type(User, name="example.User") ``` ## Performance Issues diff --git a/docs/guide/go/type-registration.md b/docs/guide/go/type-registration.md index d651fb1a9b..356815939e 100644 --- a/docs/guide/go/type-registration.md +++ b/docs/guide/go/type-registration.md @@ -208,7 +208,7 @@ fory.register(User.class, "example.User"); **Python**: ```python -fory.register(User, typename="example.User") +fory.register_type(User, name="example.User") ``` **Rust**: @@ -223,7 +223,7 @@ struct User { } let mut fory = Fory::default(); -fory.register_by_name::<User>("example", "User")?; +fory.register_by_name::<User>("example.User")?; ``` ## Best Practices diff --git a/docs/guide/java/basic-serialization.md b/docs/guide/java/basic-serialization.md index 3e652ddf83..3950481786 100644 --- a/docs/guide/java/basic-serialization.md +++ b/docs/guide/java/basic-serialization.md @@ -54,8 +54,7 @@ xlang payloads. ## Register Custom Types Register application classes with the same type identity on every peer. Numeric IDs are compact and -fast, while namespace/type-name registration is easier to coordinate across independently owned -services. +fast, while name registration is easier to coordinate across independently owned services. ```java import org.apache.fory.annotation.ForyField; diff --git a/docs/guide/java/type-registration.md b/docs/guide/java/type-registration.md index 15270c7ee9..148762c874 100644 --- a/docs/guide/java/type-registration.md +++ b/docs/guide/java/type-registration.md @@ -49,13 +49,17 @@ Internal type IDs 0-32 are reserved for built-in xlang types. Java native built- ### Register by Name -Register class by ID will have better performance and smaller space overhead. But in some cases, management for a bunch of type IDs is complex. In such cases, registering class by name using API `register(Class<?> cls, String namespace, String typeName)` is recommended: +Register class by ID has better performance and smaller space overhead. But in some cases, +management for a bunch of type IDs is complex. In such cases, registering class by name using API +`register(Class<?> cls, String name)` is recommended. Use `.` inside the name to add a namespace +prefix: ```java -fory.register(Foo.class, "demo", "Foo"); +fory.register(Foo.class, "demo.Foo"); ``` -If there are no duplicate names for types, `namespace` can be left as empty to reduce serialized size. +If there are no duplicate names for types, use a name without a namespace prefix to reduce +serialized size. **Do not use this API to register class since it will increase serialized size a lot compared to registering class by ID.** diff --git a/docs/guide/java/xlang-serialization.md b/docs/guide/java/xlang-serialization.md index 8d6ea9d521..523735d661 100644 --- a/docs/guide/java/xlang-serialization.md +++ b/docs/guide/java/xlang-serialization.md @@ -129,7 +129,7 @@ class Person: fory = pyfory.Fory(xlang=True, ref=True) # Register with the same name as Java. -fory.register_type(Person, typename="example.Person") +fory.register_type(Person, name="example.Person") person = fory.deserialize(bytes_from_java) print(f"{person.name}, {person.age}") # Output: Bob, 25 diff --git a/docs/guide/javascript/schema-evolution.md b/docs/guide/javascript/schema-evolution.md index 3d6479e353..4f9e0eac6a 100644 --- a/docs/guide/javascript/schema-evolution.md +++ b/docs/guide/javascript/schema-evolution.md @@ -91,7 +91,7 @@ const fixedType = Type.struct( ## Xlang Requirement -Compatible mode only protects you from schema differences in the _fields_ of a type. You still need the same type identity (same numeric ID or same `namespace + typeName`) on every side. See [Xlang Serialization](xlang-serialization.md). +Compatible mode only protects you from schema differences in the _fields_ of a type. You still need the same type identity (same numeric ID or same `typeName`) on every side. See [Xlang Serialization](xlang-serialization.md). ## Related Topics diff --git a/docs/guide/javascript/schema-metadata.md b/docs/guide/javascript/schema-metadata.md index 73da7106af..46979e5df0 100644 --- a/docs/guide/javascript/schema-metadata.md +++ b/docs/guide/javascript/schema-metadata.md @@ -25,8 +25,8 @@ schema evolution behavior. ## Type Identity -Structs and enums can use a numeric ID or a namespace/name pair. Pick one identity strategy for a -type and use it consistently in every runtime that reads or writes the payload. +Structs and enums can use a numeric ID or a name. Pick one identity strategy for a type and use it +consistently in every runtime that reads or writes the payload. ```ts import { Type } from "@apache-fory/core"; @@ -40,7 +40,7 @@ const byId = Type.struct( ); const byName = Type.struct( - { namespace: "example", typeName: "user" }, + { typeName: "example.user" }, { id: Type.int64(), name: Type.string(), @@ -48,6 +48,8 @@ const byName = Type.struct( ); ``` +Use `.` inside `typeName` to add a namespace prefix. + ## Decorator Metadata Decorators keep the schema next to a TypeScript class declaration: diff --git a/docs/guide/javascript/type-registration.md b/docs/guide/javascript/type-registration.md index 921d314655..3c15677db3 100644 --- a/docs/guide/javascript/type-registration.md +++ b/docs/guide/javascript/type-registration.md @@ -61,17 +61,8 @@ const fory = new Fory(); const { serialize, deserialize } = fory.register(userType); ``` -You can also split namespace and type name explicitly: - -```ts -const userType = Type.struct( - { namespace: "example", typeName: "user" }, - { - id: Type.int64(), - name: Type.string(), - }, -); -``` +Use `.` inside `typeName` to add a namespace prefix. Fory splits the namespace from +the final type-name segment. > **Do not mix strategies for the same type across runtimes.** If one side > uses a numeric ID and the other uses a name, deserialization will fail. @@ -163,7 +154,7 @@ Use **names** when: ## Xlang -For a message to round-trip between JavaScript and another runtime, both sides must use the same identity for a given type: same numeric ID, or same `namespace + typeName`. See [Xlang Serialization](xlang-serialization.md). +For a message to round-trip between JavaScript and another runtime, both sides must use the same identity for a given type: same numeric ID, or same `typeName`. Use `.` inside `typeName` to add a namespace prefix. See [Xlang Serialization](xlang-serialization.md). ## Related Topics diff --git a/docs/guide/javascript/xlang-serialization.md b/docs/guide/javascript/xlang-serialization.md index 17f1413b02..24927efc4f 100644 --- a/docs/guide/javascript/xlang-serialization.md +++ b/docs/guide/javascript/xlang-serialization.md @@ -33,7 +33,7 @@ Things to keep in mind: For a message to survive a round trip between JavaScript and another runtime: -1. **Same type identity** on both sides — same numeric ID, or same `namespace + typeName`. +1. **Same type identity** on both sides — same numeric ID, or same `typeName`. 2. **Compatible field types** — a `Type.int32()` field in JavaScript matches Java `int`, Go `int32`, C# `int`. 3. **Same nullability** — if one side marks a field nullable, the other should too. 4. Compatible schema evolution on both sides. JavaScript enables it by default. diff --git a/docs/guide/kotlin/android-support.md b/docs/guide/kotlin/android-support.md index 6ab7feb452..38535a9d24 100644 --- a/docs/guide/kotlin/android-support.md +++ b/docs/guide/kotlin/android-support.md @@ -68,7 +68,7 @@ val fory = ForyKotlin.builder() .requireClassRegistration(true) .build() -fory.register<User>("example", "User") +fory.register<User>("example.User") ``` Do not reference generated serializer classes from application code. The runtime diff --git a/docs/guide/kotlin/static-generated-serializers.md b/docs/guide/kotlin/static-generated-serializers.md index 97f8150e1e..a19d770696 100644 --- a/docs/guide/kotlin/static-generated-serializers.md +++ b/docs/guide/kotlin/static-generated-serializers.md @@ -268,7 +268,7 @@ val fory = ForyKotlin.builder() .requireClassRegistration(true) .build() -fory.register<User>("example", "User") +fory.register<User>("example.User") ``` `ForyKotlin.builder()` installs the Kotlin runtime bootstrap for the Fory diff --git a/docs/guide/python/basic-serialization.md b/docs/guide/python/basic-serialization.md index 8048aa8ec3..eaa997b25e 100644 --- a/docs/guide/python/basic-serialization.md +++ b/docs/guide/python/basic-serialization.md @@ -58,7 +58,7 @@ class Person: metadata: Dict[str, str] fory = pyfory.Fory(xlang=True, ref=True) -fory.register(Person, typename="example.Person") +fory.register(Person, name="example.Person") person = Person("Bob", 25, [88, 92, 85], {"team": "engineering"}) data = fory.serialize(person) result = fory.deserialize(data) @@ -88,7 +88,7 @@ For arbitrary Python object graphs, local classes, functions, and methods, use ## Performance Tips 1. **Disable `ref=True` if not needed**: Reference tracking has overhead -2. **Use type_id instead of typename**: Integer IDs are faster than string names +2. **Use type_id instead of name**: Integer IDs are faster than string names 3. **Reuse Fory instances**: Create once, use many times 4. **Enable Cython**: Make sure `ENABLE_FORY_CYTHON_SERIALIZATION=1` diff --git a/docs/guide/python/configuration.md b/docs/guide/python/configuration.md index 7a16bbee0f..6adacd0dd1 100644 --- a/docs/guide/python/configuration.md +++ b/docs/guide/python/configuration.md @@ -83,8 +83,8 @@ fory.register(MyClass, type_id=123) fory.register(MyClass, type_id=123, serializer=custom_serializer) # Type registration by name -fory.register(MyClass, typename="my.package.MyClass") -fory.register(MyClass, typename="my.package.MyClass", serializer=custom_serializer) +fory.register(MyClass, name="my.package.MyClass") +fory.register(MyClass, name="my.package.MyClass", serializer=custom_serializer) ``` ## Xlang And Native Mode Comparison @@ -107,7 +107,7 @@ Xlang mode is the default and restricts payloads to types compatible across Fory import pyfory fory = pyfory.Fory(xlang=True, ref=True) -fory.register(MyDataClass, typename="com.example.MyDataClass") +fory.register(MyDataClass, name="com.example.MyDataClass") data = fory.serialize(MyDataClass(field1="value", field2=42)) ``` @@ -140,7 +140,7 @@ fory = pyfory.Fory( max_depth=20, ) -fory.register(UserModel, typename="example.User") +fory.register(UserModel, name="example.User") ``` ### Native Mode With Dynamic Types @@ -179,8 +179,8 @@ fory = pyfory.Fory( max_depth=50, ) -fory.register(UserModel, typename="example.User") -fory.register(OrderModel, typename="example.Order") +fory.register(UserModel, name="example.User") +fory.register(OrderModel, name="example.Order") ``` Use dynamic native-mode deserialization (`strict=False`) only for trusted Python-only payloads: diff --git a/docs/guide/python/custom-serializers.md b/docs/guide/python/custom-serializers.md index 520f0d484a..a3499a74bc 100644 --- a/docs/guide/python/custom-serializers.md +++ b/docs/guide/python/custom-serializers.md @@ -127,8 +127,8 @@ fory = pyfory.Fory(xlang=False) # Register with type_id fory.register(MyClass, type_id=100, serializer=MySerializer(fory.type_resolver, MyClass)) -# Register with typename (for xlang) -fory.register(MyClass, typename="com.example.MyClass", serializer=MySerializer(fory.type_resolver, MyClass)) +# Register with name (for xlang) +fory.register(MyClass, name="com.example.MyClass", serializer=MySerializer(fory.type_resolver, MyClass)) ``` ## Related Topics diff --git a/docs/guide/python/schema-evolution.md b/docs/guide/python/schema-evolution.md index 9ad7306787..182d54c90f 100644 --- a/docs/guide/python/schema-evolution.md +++ b/docs/guide/python/schema-evolution.md @@ -65,7 +65,7 @@ class User: age: pyfory.Int32 f = pyfory.Fory(xlang=True) -f.register(User, typename="User") +f.register(User, name="User") data = f.dumps(User("Alice", 30)) # Version 2: Add new field (backward compatible) @@ -89,7 +89,7 @@ print(user.email) # "[email protected]" ## Best Practices 1. **Always provide default values** for new fields -2. **Use typename for cross-language compatibility** +2. **Use name for cross-language compatibility** 3. **Test schema changes** before deploying 4. **Document schema versions** for your team diff --git a/docs/guide/python/troubleshooting.md b/docs/guide/python/troubleshooting.md index d81d2fe9de..5147f536d0 100644 --- a/docs/guide/python/troubleshooting.md +++ b/docs/guide/python/troubleshooting.md @@ -49,7 +49,7 @@ print(pyfory.ENABLE_FORY_CYTHON_SERIALIZATION) # Should be True ```python # Use explicit type registration with consistent naming f = pyfory.Fory(xlang=True) -f.register(MyClass, typename="com.package.MyClass") # Use same name in all languages +f.register(MyClass, name="com.package.MyClass") # Use same name in all languages ``` ### Circular Reference Errors or Duplicate Data @@ -95,7 +95,7 @@ class User: name: str age: pyfory.Int32 -f.register(User, typename="User") +f.register(User, name="User") data = f.dumps(User("Alice", 30)) # Version 2: Add new field (backward compatible) diff --git a/docs/guide/python/type-registration.md b/docs/guide/python/type-registration.md index be662ca963..79472b6fae 100644 --- a/docs/guide/python/type-registration.md +++ b/docs/guide/python/type-registration.md @@ -38,7 +38,7 @@ class User: name: str age: pyfory.Int32 -fory.register(User, typename="example.User") +fory.register(User, name="example.User") ``` For Python native mode, numeric type IDs are the compact same-language @@ -56,8 +56,8 @@ fory.register(MyClass, type_id=100) Use the registration form that matches the payload contract: ```python -# Xlang: stable namespace/type-name identity -fory.register(MyClass, typename="com.example.MyClass") +# Xlang: stable name identity +fory.register(MyClass, name="com.example.MyClass") # Native mode: compact numeric identity fory.register(MyClass, type_id=100) diff --git a/docs/guide/python/xlang-serialization.md b/docs/guide/python/xlang-serialization.md index a16da3b7b7..9149b6b4a8 100644 --- a/docs/guide/python/xlang-serialization.md +++ b/docs/guide/python/xlang-serialization.md @@ -49,7 +49,7 @@ class Person: name: str age: pyfory.Int32 -f.register(Person, typename="example.Person") +f.register(Person, name="example.Person") person = Person("Charlie", 35) binary_data = f.serialize(person) @@ -89,7 +89,7 @@ struct Person { let mut fory = Fory::builder().xlang(true).build(); -fory.register_by_name::<Person>("example", "Person"); +fory.register_by_name::<Person>("example.Person"); let person: Person = fory.deserialize(&binary_data)?; ``` diff --git a/docs/guide/rust/basic-serialization.md b/docs/guide/rust/basic-serialization.md index d8e7aa81d8..516523dfd6 100644 --- a/docs/guide/rust/basic-serialization.md +++ b/docs/guide/rust/basic-serialization.md @@ -55,8 +55,8 @@ struct Address { } let mut fory = Fory::builder().xlang(true).build(); -fory.register_by_name::<Address>("example", "Address").unwrap(); -fory.register_by_name::<Person>("example", "Person").unwrap(); +fory.register_by_name::<Address>("example.Address").unwrap(); +fory.register_by_name::<Person>("example.Person").unwrap(); let person = Person { name: "John Doe".to_string(), diff --git a/docs/guide/rust/index.md b/docs/guide/rust/index.md index 66a56bef1a..4d9173092d 100644 --- a/docs/guide/rust/index.md +++ b/docs/guide/rust/index.md @@ -36,11 +36,11 @@ The Rust implementation provides versatile and high-performance serialization wi ## Crates -| Crate | Description | Version | -| --------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- | -| [`fory`](https://github.com/apache/fory/blob/main/rust/fory) | High-level API with derive macros | [](https://crates.io/crates/fory) | -| [`fory-core`](https://github.com/apache/fory/blob/main/rust/fory-core/) | Core serialization engine | [](https://crates.io/crates/fory-core) | -| [`fory-derive`](https://github.com/apache/fory/blob/main/rust/fory-derive/) | Procedural macros | [](https://crates.io/crates/fory-derive) | +| Crate | Description | Version | +| --------------------------------------------------------------------------- | --------------------------------- | --------------------------------------------- | +| [`fory`](https://github.com/apache/fory/blob/main/rust/fory) | High-level API with derive macros | [1.1.0](https://crates.io/crates/fory) | +| [`fory-core`](https://github.com/apache/fory/blob/main/rust/fory-core/) | Core serialization engine | [1.1.0](https://crates.io/crates/fory-core) | +| [`fory-derive`](https://github.com/apache/fory/blob/main/rust/fory-derive/) | Procedural macros | [1.1.0](https://crates.io/crates/fory-derive) | ## Quick Start diff --git a/docs/guide/rust/native-serialization.md b/docs/guide/rust/native-serialization.md index 133b022b93..978a307cbd 100644 --- a/docs/guide/rust/native-serialization.md +++ b/docs/guide/rust/native-serialization.md @@ -84,11 +84,11 @@ Register application structs and enum-like types before serialization: ```rust fory.register::<Order>(100)?; -fory.register_by_name::<Order>("example", "Order")?; +fory.register_by_name::<Order>("example.Order")?; ``` -Use explicit numeric IDs for compact payloads and stable deployments. Use namespace/type-name -registration when independent teams coordinate type identity by names. +Use explicit numeric IDs for compact payloads and stable deployments. Use named registration +when independent teams coordinate type identity by names; add a namespace prefix with `.` when needed. ## Rust Object Surface diff --git a/docs/guide/rust/type-registration.md b/docs/guide/rust/type-registration.md index 301cd1f756..d2830b99f0 100644 --- a/docs/guide/rust/type-registration.md +++ b/docs/guide/rust/type-registration.md @@ -49,13 +49,14 @@ let decoded: User = fory.deserialize(&bytes)?; ## Register by Name -For cross-language compatibility, register with namespace and type name: +For cross-language compatibility, register with a stable name. Use `.` to separate a +namespace prefix from the type name: ```rust let mut fory = Fory::builder().xlang(true).build(); // Register with symbolic type identity -fory.register_by_name::<MyStruct>("com.example", "MyStruct")?; +fory.register_by_name::<MyStruct>("com.example.MyStruct")?; ``` ## Register Custom Serializer @@ -69,7 +70,7 @@ fory.register_serializer::<CustomType>(100)?; ## Registration Consistency -Rust registration APIs use explicit IDs or explicit namespace/type names. Keep the same registration mapping on serializer and deserializer peers: +Rust registration APIs use explicit IDs or explicit names. Keep the same registration mapping on serializer and deserializer peers: ```rust // Serializer side diff --git a/docs/guide/rust/xlang-serialization.md b/docs/guide/rust/xlang-serialization.md index a823a7218a..c152cd5fd5 100644 --- a/docs/guide/rust/xlang-serialization.md +++ b/docs/guide/rust/xlang-serialization.md @@ -36,7 +36,7 @@ let mut fory = Fory::builder().xlang(true).build(); fory.register::<MyStruct>(100)?; // Or use name-based registration -fory.register_by_name::<MyStruct>("com.example", "MyStruct")?; +fory.register_by_name::<MyStruct>("com.example.MyStruct")?; ``` ## Type Registration for Xlang @@ -56,7 +56,7 @@ fory.register::<User>(100)?; // Same ID in Java, Python, etc. For more flexible type naming: ```rust -fory.register_by_name::<User>("com.example", "User")?; +fory.register_by_name::<User>("com.example.User")?; ``` ## Xlang Example diff --git a/docs/guide/swift/type-registration.md b/docs/guide/swift/type-registration.md index 8021535e5a..10d8d639c7 100644 --- a/docs/guide/swift/type-registration.md +++ b/docs/guide/swift/type-registration.md @@ -52,16 +52,12 @@ fory.register(User.self, id: 1) try fory.register(User.self, name: "com.example.User") ``` -`name` is split by `.`: +`name` is split by the last `.`: - namespace: `com.example` - type name: `User` -### Explicit namespace + name - -```swift -try fory.register(User.self, namespace: "com.example", name: "User") -``` +Simple names such as `User` use an empty namespace. Empty names and names ending in `.` are invalid. ## Consistency Rules diff --git a/docs/guide/swift/xlang-serialization.md b/docs/guide/swift/xlang-serialization.md index e32c835192..fed407b6a5 100644 --- a/docs/guide/swift/xlang-serialization.md +++ b/docs/guide/swift/xlang-serialization.md @@ -45,7 +45,7 @@ fory.register(Order.self, id: 100) ### Name-based registration ```swift -try fory.register(Order.self, namespace: "com.example", name: "Order") +try fory.register(Order.self, name: "com.example.Order") ``` ## Xlang Rules diff --git a/docs/guide/xlang/field-nullability.md b/docs/guide/xlang/field-nullability.md index 1566efab26..b10c06dc3e 100644 --- a/docs/guide/xlang/field-nullability.md +++ b/docs/guide/xlang/field-nullability.md @@ -132,7 +132,7 @@ class Person: bio: Optional[str] = None # Can be None fory = pyfory.Fory(xlang=True) -fory.register_type(Person, typename="example.Person") +fory.register_type(Person, name="example.Person") ``` ### Rust diff --git a/docs/guide/xlang/getting-started.md b/docs/guide/xlang/getting-started.md index 04aeca73fa..d2532b4ad9 100644 --- a/docs/guide/xlang/getting-started.md +++ b/docs/guide/xlang/getting-started.md @@ -237,7 +237,7 @@ fory.register(Person.class, "example.Person"); **Python:** ```python -fory.register_type(Person, typename="example.Person") +fory.register_type(Person, name="example.Person") ``` **Go:** @@ -259,7 +259,7 @@ struct Person { let mut fory = Fory::builder().xlang(true).build(); fory - .register_by_name::<Person>("example", "Person") + .register_by_name::<Person>("example.Person") .expect("register Person"); ``` @@ -279,15 +279,15 @@ const { serialize, deserialize } = fory.register(personType); **C++:** ```cpp -fory.register_struct<Person>("example", "Person"); +fory.register_struct<Person>("example.Person"); // For enums, use register_enum: -// fory.register_enum<Color>("example", "Color"); +// fory.register_enum<Color>("example.Color"); ``` **C#:** ```csharp -fory.Register<Person>("example", "Person"); +fory.Register<Person>("example.Person"); ``` **Dart:** @@ -296,15 +296,14 @@ fory.Register<Person>("example", "Person"); PersonForyModule.register( fory, Person, - namespace: 'example', - typeName: 'Person', + name: 'example.Person', ); ``` **Swift:** ```swift -try fory.register(Person.self, namespace: "example", name: "Person") +try fory.register(Person.self, name: "example.Person") ``` **Scala:** @@ -441,7 +440,7 @@ class Person: age: pyfory.Int32 fory = pyfory.Fory(xlang=True) -fory.register_type(Person, typename="example.Person") +fory.register_type(Person, name="example.Person") with open("person.bin", "rb") as f: data = f.read() diff --git a/docs/guide/xlang/index.md b/docs/guide/xlang/index.md index dd1f9393d0..6bc39564ac 100644 --- a/docs/guide/xlang/index.md +++ b/docs/guide/xlang/index.md @@ -102,7 +102,7 @@ class Person: age: pyfory.Int32 fory = pyfory.Fory(xlang=True) -fory.register_type(Person, typename="example.Person") +fory.register_type(Person, name="example.Person") # Receive bytes from Java person = fory.deserialize(bytes_from_java) diff --git a/docs/guide/xlang/serialization.md b/docs/guide/xlang/serialization.md index fd20751f82..409f91cf53 100644 --- a/docs/guide/xlang/serialization.md +++ b/docs/guide/xlang/serialization.md @@ -242,8 +242,8 @@ class SomeClass2: if __name__ == "__main__": f = pyfory.Fory(xlang=True) - f.register_type(SomeClass1, typename="example.SomeClass1") - f.register_type(SomeClass2, typename="example.SomeClass2") + f.register_type(SomeClass1, name="example.SomeClass1") + f.register_type(SomeClass2, name="example.SomeClass2") obj1 = SomeClass1(f1=True, f2={-1: 2}) obj = SomeClass2( f1=obj1, @@ -399,10 +399,10 @@ fn complex_struct() { let mut fory = Fory::builder().xlang(true).build(); fory - .register_by_name::<Animal>("example", "foo2") + .register_by_name::<Animal>("example.foo2") .expect("register Animal"); fory - .register_by_name::<Person>("example", "foo") + .register_by_name::<Person>("example.foo") .expect("register Person"); let bin = fory.serialize(&person).expect("serialize success"); let obj: Person = fory.deserialize(&bin).expect("deserialize success"); @@ -462,7 +462,7 @@ class SomeClass: f3: Dict[str, str] fory = pyfory.Fory(xlang=True, ref=True) -fory.register_type(SomeClass, typename="example.SomeClass") +fory.register_type(SomeClass, name="example.SomeClass") obj = SomeClass() obj.f2 = {"k1": "v1", "k2": "v2"} obj.f1, obj.f3 = obj, obj.f2 diff --git a/docs/guide/xlang/troubleshooting.md b/docs/guide/xlang/troubleshooting.md index de2430e06c..b2eb10b252 100644 --- a/docs/guide/xlang/troubleshooting.md +++ b/docs/guide/xlang/troubleshooting.md @@ -44,7 +44,7 @@ Error: Type 'example.Person' is not registered ```python # Python - fory.register_type(Person, typename="example.Person") + fory.register_type(Person, name="example.Person") ``` 2. Check for typos or case differences in type names --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
