This is an automated email from the ASF dual-hosted git repository. chaokunyang pushed a commit to branch fix_graalvm_doc in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit cb66557527cabf777d16fcddedaa405664f2f9d4 Author: 慕白 <[email protected]> AuthorDate: Mon Apr 20 15:26:25 2026 +0800 docs: move GraalVM guide under Java docs --- .../{graalvm_support.md => graalvm-support.md} | 2 +- docs/guide/java/index.md | 2 +- docs/introduction/overview.md | 2 +- .../guide/java/graalvm-support.md} | 8 +- .../current/guide/java/index.md | 1 + .../current/introduction/overview.md | 2 +- .../guide/java/graalvm-support.md} | 8 +- .../version-0.17/guide/java/index.md | 1 + .../version-0.17/introduction/overview.md | 2 +- versioned_docs/version-0.17/guide/graalvm_guide.md | 329 --------------------- .../version-0.17/guide/java/graalvm-support.md | 6 +- versioned_docs/version-0.17/guide/java/index.md | 1 + .../version-0.17/introduction/overview.md | 2 +- 13 files changed, 20 insertions(+), 346 deletions(-) diff --git a/docs/guide/java/graalvm_support.md b/docs/guide/java/graalvm-support.md similarity index 99% rename from docs/guide/java/graalvm_support.md rename to docs/guide/java/graalvm-support.md index 607211ec3..1e12589a6 100644 --- a/docs/guide/java/graalvm_support.md +++ b/docs/guide/java/graalvm-support.md @@ -1,7 +1,7 @@ --- title: GraalVM Support sidebar_position: 13 -id: graalvm_support +id: graalvm-support license: | Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with diff --git a/docs/guide/java/index.md b/docs/guide/java/index.md index 95eccf6e2..baf60f741 100644 --- a/docs/guide/java/index.md +++ b/docs/guide/java/index.md @@ -209,4 +209,4 @@ ThreadSafeFory threadLocalFory = Fory.builder() - [Type Registration](type-registration.md) - Class registration and security - [Custom Serializers](custom-serializers.md) - Implement custom serializers - [Cross-Language Serialization](cross-language.md) - Serialize data for other languages -- [GraalVM Support](graalvm_support.md) - Build-time serializer compilation for native images +- [GraalVM Support](graalvm-support.md) - Build-time serializer compilation for native images diff --git a/docs/introduction/overview.md b/docs/introduction/overview.md index a1e86f49a..6c11eebd1 100644 --- a/docs/introduction/overview.md +++ b/docs/introduction/overview.md @@ -123,7 +123,7 @@ All protocols share the same optimized codebase, allowing improvements in one pr | **Rust** | Rust implementation and patterns | [Rust Guide](https://github.com/apache/fory/blob/main/docs/guide/rust/) | [View](../guide/rust) | | **Go** | Go implementation and usage | [Go Guide](https://github.com/apache/fory/blob/main/docs/guide/go/) | [View](../guide/go) | | **Scala** | Scala integration and best practices | [Scala Guide](https://github.com/apache/fory/blob/main/docs/guide/scala/) | [View](../guide/scala) | -| **GraalVM** | Native image support and AOT compilation | [GraalVM Guide](https://github.com/apache/fory/blob/main/docs/guide/graalvm_guide.md) | [View](../guide/graalvm_guide.md) | +| **GraalVM** | Native image support and AOT compilation | [GraalVM Support](https://github.com/apache/fory/blob/main/docs/guide/java/graalvm-support.md) | [View](../guide/java/graalvm-support.md) | | **Development** | Building and contributing to Fory | [Development](https://github.com/apache/fory/blob/main/docs/guide/DEVELOPMENT.md) | [View](../guide/DEVELOPMENT) | ### Protocol Specifications diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/graalvm_guide.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/graalvm-support.md similarity index 98% rename from i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/graalvm_guide.md rename to i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/graalvm-support.md index cd466b6bf..d560786cf 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/graalvm_guide.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/graalvm-support.md @@ -1,7 +1,7 @@ --- -title: GraalVM 指南 -sidebar_position: 19 -id: graalvm_serialization +title: GraalVM 支持 +sidebar_position: 13 +id: graalvm-support license: | Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with @@ -94,7 +94,7 @@ Args = --initialize-at-build-time=com.example.Example - **私有内部类/记录** - **动态代理序列化** -这意味着在大多数应用中都不再需要手工维护 `reflect-config.json`。你自己的 `native-image.properties` 仍只需要配置在构建时初始化的引导类，例如： +这意味着在大多数应用中都不再需要手工维护 `reflect-config.json`。您自己的 `native-image.properties` 仍只需要配置在构建时初始化的引导类，例如： ```properties Args = --initialize-at-build-time=com.example.Example diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/index.md index 4888dee0e..b6d3884fe 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/index.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/java/index.md @@ -202,3 +202,4 @@ ThreadSafeFory threadLocalFory = Fory.builder() - [类型注册](type-registration.md) - 类注册和安全性 - [自定义序列化器](custom-serializers.md) - 实现自定义序列化器 - [跨语言序列化](cross-language.md) - 为其他语言序列化数据 +- [GraalVM 支持](graalvm-support.md) - 面向原生镜像的构建期序列化器编译 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/overview.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/overview.md index e2d46e870..b9090a0b6 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/overview.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/overview.md @@ -123,7 +123,7 @@ Apache Fory™ 实现了针对不同场景优化的多个二进制协议： | **Rust** | Rust 实现和模式 | [Rust 指南](https://github.com/apache/fory/blob/main/docs/guide/rust/) | [查看](../guide/rust) | | **Go** | Go 实现和用法 | [Go 指南](https://github.com/apache/fory/blob/main/docs/guide/go/) | [查看](../guide/go) | | **Scala** | Scala 集成和最佳实践 | [Scala 指南](https://github.com/apache/fory/blob/main/docs/guide/scala/) | [查看](../guide/scala) | -| **GraalVM** | 原生镜像支持和 AOT 编译 | [GraalVM 指南](https://github.com/apache/fory/blob/main/docs/guide/graalvm_guide.md) | [查看](../guide/graalvm_guide.md) | +| **GraalVM** | 原生镜像支持和 AOT 编译 | [GraalVM 支持](https://github.com/apache/fory/blob/main/docs/guide/java/graalvm-support.md) | [查看](../guide/java/graalvm-support.md) | | **开发** | 构建和贡献 Fory | [开发指南](https://github.com/apache/fory/blob/main/docs/guide/DEVELOPMENT.md) | [查看](../guide/DEVELOPMENT) | ### 协议规范 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/graalvm_guide.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/java/graalvm-support.md similarity index 98% rename from i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/graalvm_guide.md rename to i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/java/graalvm-support.md index cd466b6bf..d560786cf 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/graalvm_guide.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/java/graalvm-support.md @@ -1,7 +1,7 @@ --- -title: GraalVM 指南 -sidebar_position: 19 -id: graalvm_serialization +title: GraalVM 支持 +sidebar_position: 13 +id: graalvm-support license: | Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with @@ -94,7 +94,7 @@ Args = --initialize-at-build-time=com.example.Example - **私有内部类/记录** - **动态代理序列化** -这意味着在大多数应用中都不再需要手工维护 `reflect-config.json`。你自己的 `native-image.properties` 仍只需要配置在构建时初始化的引导类，例如： +这意味着在大多数应用中都不再需要手工维护 `reflect-config.json`。您自己的 `native-image.properties` 仍只需要配置在构建时初始化的引导类，例如： ```properties Args = --initialize-at-build-time=com.example.Example diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/java/index.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/java/index.md index 4888dee0e..b6d3884fe 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/java/index.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/guide/java/index.md @@ -202,3 +202,4 @@ ThreadSafeFory threadLocalFory = Fory.builder() - [类型注册](type-registration.md) - 类注册和安全性 - [自定义序列化器](custom-serializers.md) - 实现自定义序列化器 - [跨语言序列化](cross-language.md) - 为其他语言序列化数据 +- [GraalVM 支持](graalvm-support.md) - 面向原生镜像的构建期序列化器编译 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/introduction/overview.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/introduction/overview.md index e2d46e870..b9090a0b6 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/introduction/overview.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.17/introduction/overview.md @@ -123,7 +123,7 @@ Apache Fory™ 实现了针对不同场景优化的多个二进制协议： | **Rust** | Rust 实现和模式 | [Rust 指南](https://github.com/apache/fory/blob/main/docs/guide/rust/) | [查看](../guide/rust) | | **Go** | Go 实现和用法 | [Go 指南](https://github.com/apache/fory/blob/main/docs/guide/go/) | [查看](../guide/go) | | **Scala** | Scala 集成和最佳实践 | [Scala 指南](https://github.com/apache/fory/blob/main/docs/guide/scala/) | [查看](../guide/scala) | -| **GraalVM** | 原生镜像支持和 AOT 编译 | [GraalVM 指南](https://github.com/apache/fory/blob/main/docs/guide/graalvm_guide.md) | [查看](../guide/graalvm_guide.md) | +| **GraalVM** | 原生镜像支持和 AOT 编译 | [GraalVM 支持](https://github.com/apache/fory/blob/main/docs/guide/java/graalvm-support.md) | [查看](../guide/java/graalvm-support.md) | | **开发** | 构建和贡献 Fory | [开发指南](https://github.com/apache/fory/blob/main/docs/guide/DEVELOPMENT.md) | [查看](../guide/DEVELOPMENT) | ### 协议规范 diff --git a/versioned_docs/version-0.17/guide/graalvm_guide.md b/versioned_docs/version-0.17/guide/graalvm_guide.md deleted file mode 100644 index e0135d7e8..000000000 --- a/versioned_docs/version-0.17/guide/graalvm_guide.md +++ /dev/null @@ -1,329 +0,0 @@ ---- -title: GraalVM Guide -sidebar_position: 19 -id: serialization -license: | - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---- - -## GraalVM Native Image - -GraalVM `native image` compiles Java code into native executables ahead-of-time, resulting in faster startup and lower memory usage. However, native images don't support runtime JIT compilation or reflection without explicit configuration. - -Apache Fory™ works excellently with GraalVM native image by using **codegen instead of reflection**. All serializer code is generated at build time, eliminating the need for reflection configuration files in most cases. - -## How It Works - -Fory generates serialization code at GraalVM build time when you: - -1. Create Fory as a **static** field -2. **Register** all classes in a static initializer -3. Call `fory.ensureSerializersCompiled()` to compile serializers -4. Configure the class to initialize at build time via `native-image.properties` - -**The main benefit**: You don't need to configure [reflection json](https://www.graalvm.org/latest/reference-manual/native-image/metadata/#specifying-reflection-metadata-in-json) or [serialization json](https://www.graalvm.org/latest/reference-manual/native-image/metadata/#serialization) for most serializable classes. - -Note: Fory's `asyncCompilationEnabled` option is automatically disabled for GraalVM native image since runtime JIT is not supported. - -## Basic Usage - -### Step 0: Add the GraalVM Support Dependency - -Add `fory-graalvm-feature` to your application dependencies when building a native image: - -```xml -<dependency> - <groupId>org.apache.fory</groupId> - <artifactId>fory-graalvm-feature</artifactId> - <version>${fory.version}</version> -</dependency> -``` - -This dependency already ships GraalVM feature metadata in `META-INF/native-image`, so adding it -automatically enables `org.apache.fory.graalvm.feature.ForyGraalVMFeature` during native-image -builds. - -### Step 1: Create Fory and Register Classes - -```java -import org.apache.fory.Fory; - -public class Example { - // Must be static field - static Fory fory; - - static { - fory = Fory.builder().build(); - fory.register(MyClass.class); - fory.register(AnotherClass.class); - // Compile all serializers at build time - fory.ensureSerializersCompiled(); - } - - public static void main(String[] args) { - byte[] bytes = fory.serialize(new MyClass()); - MyClass obj = (MyClass) fory.deserialize(bytes); - } -} -``` - -### Step 2: Configure Build-Time Initialization - -Create `resources/META-INF/native-image/your-group/your-artifact/native-image.properties`: - -```properties -Args = --initialize-at-build-time=com.example.Example -``` - -## What `fory-graalvm-feature` Handles - -After you add the `fory-graalvm-feature` dependency, Fory automatically registers the extra -GraalVM metadata needed by advanced cases such as: - -- **Private constructors** (classes without accessible no-arg constructor) -- **Private inner classes/records** -- **Dynamic proxy serialization** - -This removes the need for manual `reflect-config.json` in most applications. Your own -`native-image.properties` still only needs to configure your build-time initialized bootstrap -class, for example: - -```properties -Args = --initialize-at-build-time=com.example.Example -``` - -| Scenario | Without Feature | With Feature | -| ------------------------------- | ---------------------------- | ------------------ | -| Public classes with no-arg ctor | ✅ Works | ✅ Works | -| Private constructors | ❌ Needs reflect-config.json | ✅ Auto-registered | -| Private inner records | ❌ Needs reflect-config.json | ✅ Auto-registered | -| Dynamic proxies | ❌ Needs manual config | ✅ Auto-registered | - -### Example with Private Record - -```java -public class Example { - // Private inner record - requires ForyGraalVMFeature - private record PrivateRecord(int id, String name) {} - - static Fory fory; - - static { - fory = Fory.builder().build(); - fory.register(PrivateRecord.class); - fory.ensureSerializersCompiled(); - } -} -``` - -### Example with Dynamic Proxy - -```java -import org.apache.fory.util.GraalvmSupport; - -public class ProxyExample { - public interface MyService { - String execute(); - } - - public interface Audited { - String traceId(); - } - - static Fory fory; - - static { - fory = Fory.builder().build(); - // Register the exact interface list used by Proxy.newProxyInstance(...) - GraalvmSupport.registerProxySupport(MyService.class, Audited.class); - fory.ensureSerializersCompiled(); - } -} -``` - -Use `registerProxySupport(MyService.class)` for a single-interface proxy. For proxies that implement -multiple interfaces, pass the full interface list in the same order used to create the proxy. With -`fory-graalvm-feature` on the classpath, this replaces manual `proxy-config.json` entries for those -registered proxy shapes. - -## Thread-Safe Fory - -For multi-threaded applications, use `ThreadLocalFory`: - -```java -import org.apache.fory.Fory; -import org.apache.fory.ThreadLocalFory; -import org.apache.fory.ThreadSafeFory; - -public class ThreadSafeExample { - public record Foo(int f1, String f2, List<String> f3) {} - - static ThreadSafeFory fory; - - static { - fory = new ThreadLocalFory(builder -> { - Fory f = builder.build(); - f.register(Foo.class); - f.ensureSerializersCompiled(); - return f; - }); - } - - public static void main(String[] args) { - Foo foo = new Foo(10, "abc", List.of("str1", "str2")); - byte[] bytes = fory.serialize(foo); - Foo result = (Foo) fory.deserialize(bytes); - } -} -``` - -## Troubleshooting - -### "Type is instantiated reflectively but was never registered" - -If you see this error: - -``` -Type com.example.MyClass is instantiated reflectively but was never registered -``` - -**Solution**: Register the class with Fory (don't add to reflect-config.json): - -```java -fory.register(MyClass.class); -fory.ensureSerializersCompiled(); -``` - -If the class has a private constructor, either: - -1. Make sure `fory-graalvm-feature` is already on the native-image classpath, or -2. Create a `reflect-config.json` for that specific class - -## Framework Integration - -For framework developers integrating Fory: - -1. Provide a configuration file for users to list serializable classes -2. Load those classes and call `fory.register(Class<?>)` for each -3. Call `fory.ensureSerializersCompiled()` after all registrations -4. Configure your integration class for build-time initialization - -## Benchmark - -Performance comparison between Fory and GraalVM JDK Serialization: - -| Type | Compression | Speed | Size | -| ------ | ----------- | ---------- | ---- | -| Struct | Off | 46x faster | 43% | -| Struct | On | 24x faster | 31% | -| Pojo | Off | 12x faster | 56% | -| Pojo | On | 12x faster | 48% | - -See [Benchmark.java](https://github.com/apache/fory/blob/main/integration_tests/graalvm_tests/src/main/java/org/apache/fory/graalvm/Benchmark.java) for benchmark code. - -### Struct Benchmark - -#### Class Fields - -```java -public class Struct implements Serializable { - public int f1; - public long f2; - public float f3; - public double f4; - public int f5; - public long f6; - public float f7; - public double f8; - public int f9; - public long f10; - public float f11; - public double f12; -} -``` - -#### Benchmark Results - -No compression: - -``` -Benchmark repeat number: 400000 -Object type: class org.apache.fory.graalvm.Struct -Compress number: false -Fory size: 76.0 -JDK size: 178.0 -Fory serialization took mills: 49 -JDK serialization took mills: 2254 -Compare speed: Fory is 45.70x speed of JDK -Compare size: Fory is 0.43x size of JDK -``` - -Compress number: - -``` -Benchmark repeat number: 400000 -Object type: class org.apache.fory.graalvm.Struct -Compress number: true -Fory size: 55.0 -JDK size: 178.0 -Fory serialization took mills: 130 -JDK serialization took mills: 3161 -Compare speed: Fory is 24.16x speed of JDK -Compare size: Fory is 0.31x size of JDK -``` - -### Pojo Benchmark - -#### Class Fields - -```java -public class Foo implements Serializable { - int f1; - String f2; - List<String> f3; - Map<String, Long> f4; -} -``` - -#### Benchmark Results - -No compression: - -``` -Benchmark repeat number: 400000 -Object type: class org.apache.fory.graalvm.Foo -Compress number: false -Fory size: 541.0 -JDK size: 964.0 -Fory serialization took mills: 1663 -JDK serialization took mills: 16266 -Compare speed: Fory is 12.19x speed of JDK -Compare size: Fory is 0.56x size of JDK -``` - -Compress number: - -``` -Benchmark repeat number: 400000 -Object type: class org.apache.fory.graalvm.Foo -Compress number: true -Fory size: 459.0 -JDK size: 964.0 -Fory serialization took mills: 1289 -JDK serialization took mills: 15069 -Compare speed: Fory is 12.11x speed of JDK -Compare size: Fory is 0.48x size of JDK -``` diff --git a/docs/guide/graalvm_guide.md b/versioned_docs/version-0.17/guide/java/graalvm-support.md similarity index 99% rename from docs/guide/graalvm_guide.md rename to versioned_docs/version-0.17/guide/java/graalvm-support.md index e0135d7e8..1e12589a6 100644 --- a/docs/guide/graalvm_guide.md +++ b/versioned_docs/version-0.17/guide/java/graalvm-support.md @@ -1,7 +1,7 @@ --- -title: GraalVM Guide -sidebar_position: 19 -id: serialization +title: GraalVM Support +sidebar_position: 13 +id: graalvm-support license: | Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with diff --git a/versioned_docs/version-0.17/guide/java/index.md b/versioned_docs/version-0.17/guide/java/index.md index e4b7d05ac..4f45c37d1 100644 --- a/versioned_docs/version-0.17/guide/java/index.md +++ b/versioned_docs/version-0.17/guide/java/index.md @@ -208,3 +208,4 @@ ThreadSafeFory threadLocalFory = Fory.builder() - [Type Registration](type-registration.md) - Class registration and security - [Custom Serializers](custom-serializers.md) - Implement custom serializers - [Cross-Language Serialization](cross-language.md) - Serialize data for other languages +- [GraalVM Support](graalvm-support.md) - Build-time serializer compilation for native images diff --git a/versioned_docs/version-0.17/introduction/overview.md b/versioned_docs/version-0.17/introduction/overview.md index a1e86f49a..6c11eebd1 100644 --- a/versioned_docs/version-0.17/introduction/overview.md +++ b/versioned_docs/version-0.17/introduction/overview.md @@ -123,7 +123,7 @@ All protocols share the same optimized codebase, allowing improvements in one pr | **Rust** | Rust implementation and patterns | [Rust Guide](https://github.com/apache/fory/blob/main/docs/guide/rust/) | [View](../guide/rust) | | **Go** | Go implementation and usage | [Go Guide](https://github.com/apache/fory/blob/main/docs/guide/go/) | [View](../guide/go) | | **Scala** | Scala integration and best practices | [Scala Guide](https://github.com/apache/fory/blob/main/docs/guide/scala/) | [View](../guide/scala) | -| **GraalVM** | Native image support and AOT compilation | [GraalVM Guide](https://github.com/apache/fory/blob/main/docs/guide/graalvm_guide.md) | [View](../guide/graalvm_guide.md) | +| **GraalVM** | Native image support and AOT compilation | [GraalVM Support](https://github.com/apache/fory/blob/main/docs/guide/java/graalvm-support.md) | [View](../guide/java/graalvm-support.md) | | **Development** | Building and contributing to Fory | [Development](https://github.com/apache/fory/blob/main/docs/guide/DEVELOPMENT.md) | [View](../guide/DEVELOPMENT) | ### Protocol Specifications --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
