This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory-site.git
The following commit(s) were added to refs/heads/main by this push:
new 5048efb052 🔄 synced local 'docs/guide/' with remote 'docs/guide/'
5048efb052 is described below
commit 5048efb0523c085b018e7dc9d1ebe304c7bd84d3
Author: chaokunyang <[email protected]>
AuthorDate: Wed Jul 15 02:53:49 2026 +0000
🔄 synced local 'docs/guide/' with remote 'docs/guide/'
---
docs/guide/java/graalvm-support.md | 45 ++++++++++++++++++++++++++++++++++++++
docs/guide/java/index.md | 2 +-
docs/guide/java/json-support.md | 22 ++++++++++++++-----
3 files changed, 62 insertions(+), 7 deletions(-)
diff --git a/docs/guide/java/graalvm-support.md
b/docs/guide/java/graalvm-support.md
index 72c8467bc0..37095c1b52 100644
--- a/docs/guide/java/graalvm-support.md
+++ b/docs/guide/java/graalvm-support.md
@@ -44,6 +44,51 @@ shapes. Application classes still need to be registered with
Fory before seriali
Fory disables asynchronous serializer compilation in a native image because
runtime just-in-time
compilation is unavailable.
+## Fory JSON
+
+Fory JSON uses a separate Native Image workflow. It has no type-registration
API and does not
+create a `ForyJson` instance or generate JSON codecs while the image is built.
Add `@JsonType` to
+each object model that the native executable reads or writes:
+
+```java
+import org.apache.fory.json.ForyJson;
+import org.apache.fory.json.annotation.JsonType;
+
+@JsonType
+public final class User {
+ public long id;
+ public String name;
+}
+
+public class JsonExample {
+ public static void main(String[] args) {
+ ForyJson json = ForyJson.builder().build();
+ User user = json.fromJson("{\"id\":1,\"name\":\"Ada\"}", User.class);
+ System.out.println(json.toJson(user));
+ }
+}
+```
+
+The `fory-json` artifact activates its Native Image Feature automatically.
Reachable `@JsonType`
+classes gate object-model metadata. `@JsonType` is not inherited, so annotate
every concrete runtime
+model. An annotated base with a class-literal `@JsonSubTypes` table registers
those listed subtypes
+automatically. Reachable concrete `Collection` and `Map` root types are also
supported when they
+have the public no-argument constructor required by Fory JSON. Reachable
`@JsonCodec` declarations
+register their codec constructor even when the declaration target is not an
object model. A class
+referenced only by a runtime string is not reachable;
`JsonSubTypes.Type.className` is therefore
+unsupported in a native image.
+
+Native execution uses Fory JSON's interpreted object codec.
`ForyJson.builder()` automatically
+disables runtime code generation and asynchronous compilation in the native
executable, while all
+other builder options retain their normal behavior. Applications can create
differently configured
+`ForyJson` instances at runtime and do not need build-time initialization or
reflection
+configuration.
+
+Declaration-level, inherited, and nested type-use `@JsonCodec` annotations are
supported. An
+annotation codec must have the same public no-argument constructor required on
the JVM. In a named
+module, export or open its package to `org.apache.fory.json`. A codec instance
supplied through
+`registerCodec` is constructed by the application and needs no
annotation-constructor metadata.
+
## Basic Usage
### Create Fory and Register Classes
diff --git a/docs/guide/java/index.md b/docs/guide/java/index.md
index e276e6d52f..eb14921fd2 100644
--- a/docs/guide/java/index.md
+++ b/docs/guide/java/index.md
@@ -254,4 +254,4 @@ ThreadSafeFory threadLocalFory = Fory.builder()
- [Native Serialization](native-serialization.md) - Java-only serialization
features
- [JSON Support](json-support.md) - Complete Fory JSON user guide
- [Static Generated Serializers](static-generated-serializers.md) -
Annotation-processor static generated serializers for `@ForyStruct`
-- [GraalVM Support](graalvm-support.md) - Build-time serializer compilation
for native images
+- [GraalVM Support](graalvm-support.md) - Native Image support for binary
serialization and JSON
diff --git a/docs/guide/java/json-support.md b/docs/guide/java/json-support.md
index 343ed46e8f..1956b5b3c1 100644
--- a/docs/guide/java/json-support.md
+++ b/docs/guide/java/json-support.md
@@ -299,10 +299,13 @@ are rejected.
Depth, concurrency, and retained buffer limits must be positive. The buffer
setting does not limit
output size. Builder changes after `build()` do not mutate an existing runtime.
+In a GraalVM native image, runtime code generation and asynchronous
compilation are automatically
+disabled. Every other builder option keeps the behavior described above.
+
## Annotations
Fory JSON provides `JsonProperty`, `JsonPropertyOrder`, `JsonIgnore`,
`JsonAnyProperty`,
-`JsonAnyGetter`, `JsonAnySetter`, `JsonCreator`, `JsonCodec`, and
`JsonSubTypes` under
+`JsonAnyGetter`, `JsonAnySetter`, `JsonCreator`, `JsonCodec`, `JsonSubTypes`,
and `JsonType` under
`org.apache.fory.json.annotation`. They are not Jackson, Gson, or Fory
binary-protocol annotations.
```java
@@ -318,8 +321,13 @@ import org.apache.fory.json.annotation.JsonIgnore;
import org.apache.fory.json.annotation.JsonProperty;
import org.apache.fory.json.annotation.JsonPropertyOrder;
import org.apache.fory.json.annotation.JsonSubTypes;
+import org.apache.fory.json.annotation.JsonType;
```
+`JsonType` marks a reachable object model for GraalVM Native Image metadata.
It has no effect on
+ordinary JVM JSON behavior and is not inherited. See [GraalVM
Support](graalvm-support.md) for the
+complete native-image workflow.
+
### `JsonProperty`
An annotation on a field, getter, or setter configures the complete merged
logical property:
@@ -628,7 +636,8 @@ parent does not admit descendants. The annotation is read
from the declared base
inherited from another annotated base. Null is plain JSON null unless codec
precedence selects a
custom complete-value codec for the declared base, replacing the annotation.
Readers accept only
the configured shape, so changing inclusion is a wire-format change. At
GraalVM native-image
-runtime, use class literals instead of `className`.
+runtime, annotate the base with `JsonType` and use class literals instead of
`className`. Listed
+class-literal subtypes are registered automatically.
## Custom codecs
@@ -925,10 +934,11 @@ succeed. Returning a plain parent while decoding the
child fails with `ForyJsonE
names the target type, codec class, declaring type, and actual returned type.
The actual result,
not the parent's `final` status or the codec's generic signature, determines
validity.
-`@JsonCodec` is supported on ordinary JVMs. Android and GraalVM native image
ignore both declaration
-and type-use forms, avoiding partial behavior when nested runtime type
metadata is unavailable. Use
-exact `registerCodec` registration there. Native-image reflection
configuration is not a supported
-way to enable part of this annotation feature.
+`@JsonCodec` is supported on ordinary JVMs and GraalVM native images,
including inherited
+declarations and nested type uses. Native models must follow the `JsonType`
workflow described in
+[GraalVM Support](graalvm-support.md), which registers the annotation codec's
public no-argument
+constructor. Android ignores declaration and type-use forms; use exact
`registerCodec`
+registration there.
## Type validation and untrusted input
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
