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 5950136fe0 🔄 synced local 'docs/guide/' with remote 'docs/guide/'
5950136fe0 is described below
commit 5950136fe073b349fc98da3f08f35c0d82fc6949
Author: chaokunyang <[email protected]>
AuthorDate: Wed Jul 15 19:15:42 2026 +0000
🔄 synced local 'docs/guide/' with remote 'docs/guide/'
---
docs/guide/java/android-support.md | 22 +++++++++------
docs/guide/java/graalvm-support.md | 33 ++++++++++++++++-------
docs/guide/java/json-support.md | 18 ++++++++-----
docs/guide/java/static-generated-serializers.md | 2 +-
docs/guide/kotlin/static-generated-serializers.md | 2 +-
5 files changed, 52 insertions(+), 25 deletions(-)
diff --git a/docs/guide/java/android-support.md
b/docs/guide/java/android-support.md
index 25bf7a5b2f..8891329f1c 100644
--- a/docs/guide/java/android-support.md
+++ b/docs/guide/java/android-support.md
@@ -81,8 +81,9 @@ Child codecs act on one direct level only. For example,
`elementCodec` on `Money
`Money[]`, and `elementCodec` on `AtomicReferenceArray<Money>` handles each
`Money`. Use a complete
`value` codec when deeper custom behavior is required.
-`@JsonType` is optional. Add the annotation processor and mark application
models with `JsonType`
-when the build should generate exact R8 rules:
+Add the annotation processor and mark application object models with
`JsonType` to generate direct
+field, getter, setter, Record constructor, and `JsonCreator` operations
together with exact R8
+rules:
```kotlin
dependencies {
@@ -99,7 +100,8 @@ public final class Invoice {
}
```
-Applications that omit `JsonType` can supply equivalent exact rules
themselves. Retain every model
+Ordinary non-Record classes that omit `JsonType` can supply equivalent exact
rules themselves.
+Retain every model
constructor, field, method, generic signature, declaration annotation, and
parameter annotation used
by Fory JSON, plus the public no-argument constructor of every
annotation-selected codec. For the
previous `Invoice` example:
@@ -118,8 +120,7 @@ previous `Invoice` example:
```
The same exact-rule approach supports every `JsonCodec` member; it is not
limited to complete-value
-codecs. `JsonType` only automates rule generation on Android and is not
required for codec
-selection.
+codecs. `JsonType` is not required for codec selection on an ordinary class.
For `@JsonType` models, the generated R8 rules also retain `JsonValue` fields
and effective methods,
fixed `JsonRawValue` and `JsonBase64` fields and getters, their runtime
annotations, and the Base64
@@ -131,8 +132,14 @@ name that method explicitly.
Android Fory JSON requires a retained no-argument constructor for an ordinary
mutable class; it may
be non-public when Android reflection can make it accessible. `JsonCreator`
constructor-backed
classes follow the normal creator rules instead. Retain every field and method
used for reflection,
-or use an application codec when a model cannot satisfy those requirements.
Fory JSON Record
-mapping is not supported on Android.
+or use an application codec when a model cannot satisfy those requirements.
+
+Android-desugared Records require a direct `@JsonType` annotation and the
annotation processor.
+Manual R8 rules alone cannot reconstruct Record component order because
Android does not provide
+the Java Record reflection APIs. This also applies to a Record whose complete
representation is a
+`JsonValue` String: the generated companion identifies the propagated
component accessor and calls
+an annotated one-String canonical constructor directly. Generated child codecs
act on one level
+exactly as they do on the JVM; use a complete value codec for deeper nested
behavior.
## Static Generated Serializers
@@ -207,7 +214,6 @@ The following JVM features are not supported on Android:
- Native-address serialization APIs and native-address `MemoryBuffer` wrapping.
- Raw unsafe memory copy APIs.
- `java/fory-format` row-format APIs.
-- Fory JSON Record mapping.
## ByteBuffer
diff --git a/docs/guide/java/graalvm-support.md
b/docs/guide/java/graalvm-support.md
index 9c389774f2..216c42942c 100644
--- a/docs/guide/java/graalvm-support.md
+++ b/docs/guide/java/graalvm-support.md
@@ -46,9 +46,20 @@ 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:
+Fory JSON uses a separate Native Image workflow. Add the Fory annotation
processor to the
+application compiler path:
+
+```xml
+<annotationProcessorPaths>
+ <path>
+ <groupId>org.apache.fory</groupId>
+ <artifactId>fory-annotation-processor</artifactId>
+ <version>${fory.version}</version>
+ </path>
+</annotationProcessorPaths>
+```
+
+Then add `@JsonType` to each concrete object model that the native executable
reads or writes:
```java
import org.apache.fory.json.ForyJson;
@@ -69,16 +80,19 @@ public class JsonExample {
}
```
-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
+The processor generates direct property and creator operations. The
`fory-json` artifact activates
+its Native Image Feature automatically and retains the generated factories and
required 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, but each
+concrete object subtype needs its own direct `@JsonType` to receive generated
operations. 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
+Native execution uses Fory JSON's interpreted readers and writers with the
generated property and
+creator operations. `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
@@ -93,7 +107,8 @@ on the JVM and Android.
one-String `JsonCreator` constructors and public static factories. Fixed
`JsonRawValue` fields and
getters support trusted raw String values, and fixed `JsonBase64` fields and
getters support Base64
`byte[]` values as on the JVM. Annotate each reachable owning model with
`JsonType` so Native Image
-retains these members and the Base64 codec constructor.
+retains these members and the Base64 codec constructor. A directly annotated
`JsonValue` Record
+uses its generated component accessor and canonical constructor operations.
`JsonAnyProperty` and `JsonAnyGetter` flatten their Map into the enclosing
object. Use
`@JsonCodec(valueCodec = ...)` on that field or getter to customize each
dynamic value. A second
diff --git a/docs/guide/java/json-support.md b/docs/guide/java/json-support.md
index 53a61e7a4e..bacad8bd35 100644
--- a/docs/guide/java/json-support.md
+++ b/docs/guide/java/json-support.md
@@ -328,10 +328,15 @@ import org.apache.fory.json.annotation.JsonType;
import org.apache.fory.json.annotation.JsonValue;
```
-`JsonType` marks a reachable object model for GraalVM Native Image metadata.
On Android it enables
-processor-generated R8 rules. It has no effect on ordinary JVM JSON behavior
and is not inherited.
-See [GraalVM Support](graalvm-support.md) and
-[Android Support](android-support.md) for the platform workflows.
+`JsonType` asks the annotation processor to generate direct property and
creator operations plus
+the exact retention rules for an eligible concrete object model. A directly
annotated
+`JsonValue` Record also receives a companion so its value accessor and
canonical constructor work
+after Android desugaring. The same generated companion is used on the JVM,
Android, and GraalVM
+Native Image. The annotation is not inherited; a concrete subtype needs its
own direct annotation
+to receive a companion. See
+[GraalVM Support](graalvm-support.md) and [Android
Support](android-support.md) for setup.
+A directly annotated model that uses the default object codec requires that
generated companion;
+the runtime reports a configuration error if the processor output is missing.
### `JsonProperty`
@@ -999,8 +1004,9 @@ type-declaration codec is used for a more specific target,
every decoded value m
assignable to that target.
The annotation has the same FIELD, METHOD, and PARAMETER behavior on the JVM,
Android, and GraalVM
-Native Image. Android applications may use `JsonType` for generated exact R8
rules or provide the
-equivalent rules themselves. GraalVM object models follow the `JsonType`
workflow in
+Native Image. Ordinary Android classes may omit `JsonType` and provide
equivalent exact rules;
+Android-desugared Records, including `JsonValue` Records, require `JsonType`
and the processor.
+GraalVM object models follow the `JsonType` workflow in
[GraalVM Support](graalvm-support.md).
## Type validation and untrusted input
diff --git a/docs/guide/java/static-generated-serializers.md
b/docs/guide/java/static-generated-serializers.md
index fa14f6bd24..f3da9f0daa 100644
--- a/docs/guide/java/static-generated-serializers.md
+++ b/docs/guide/java/static-generated-serializers.md
@@ -82,7 +82,7 @@ The processor generates serializer classes in the same Java
package as the annot
- `Order_ForyNativeSerializer` for Java native mode.
For a static nested type such as `Outer.Inner`, the generated top-level
classes are
-`Outer_Inner_ForySerializer` and `Outer_Inner_ForyNativeSerializer`.
+`Outer_d_Inner_ForySerializer` and `Outer_d_Inner_ForyNativeSerializer`.
## Field Debug Tracing
diff --git a/docs/guide/kotlin/static-generated-serializers.md
b/docs/guide/kotlin/static-generated-serializers.md
index 08c3f27f8c..875fbee46a 100644
--- a/docs/guide/kotlin/static-generated-serializers.md
+++ b/docs/guide/kotlin/static-generated-serializers.md
@@ -286,7 +286,7 @@ Generated Schema IDL modules use the same path. They call
The generated serializer is emitted in the same package as the target class.
Its name is `<target>_ForySerializer`. For nested binary names, `$` is encoded
-as `_`; source underscores are encoded as `_u_`.
+as `_d_`; source underscores are encoded as `_u_`.
These names are an implementation detail. They matter for diagnostics and
Android shrinking, but user code should only register target classes.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
