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 c8fc07c0613cd8c102f6698616680cf0f1bde811
Author: chaokunyang <[email protected]>
AuthorDate: Tue Aug 4 05:58:23 2026 +0000

    🔄 synced local 'docs/json/' with remote 'docs/json/'
---
 docs/json/android.md         | 14 ++++++------
 docs/json/annotations.md     |  4 ++--
 docs/json/getting-started.md |  4 +++-
 docs/json/graalvm.md         |  8 +++----
 docs/json/index.md           | 51 ++++++++++++++++++++++----------------------
 docs/json/object-mapping.md  |  6 +++---
 6 files changed, 44 insertions(+), 43 deletions(-)

diff --git a/docs/json/android.md b/docs/json/android.md
index 2cca186e35..54488f5561 100644
--- a/docs/json/android.md
+++ b/docs/json/android.md
@@ -23,7 +23,7 @@ Fory JSON supports ordinary classes on Android API level 26 
and later through th
 `fory-json` artifact. Runtime JSON code generation and asynchronous 
compilation are disabled
 automatically, so `ForyJson.builder().build()` uses the interpreted object 
mapper.
 
-## Installation and Runtime Model
+## Installation and Codec Model
 
 Add Fory JSON to the application:
 
@@ -92,7 +92,7 @@ public final class Invoice {
 ## Mixins
 
 The same processor supports Fory JSON Mixins. A Mixin declares one exact 
target and is registered
-on the runtime that should use it:
+on the `ForyJson` builder that should use it:
 
 ```java
 import org.apache.fory.json.ForyJson;
@@ -109,8 +109,8 @@ ForyJson json =
 ```
 
 Compile every non-empty Mixin source with `fory-annotation-processor`. The 
processor emits exact
-R8 rules and any pair-specific target operations that the runtime can use. 
Registered codecs,
-effective type codecs, and built-in mappings keep their normal runtime 
precedence. An empty Mixin
+R8 rules and any pair-specific target operations that the built `ForyJson` 
instance can use. Registered codecs,
+effective type codecs, and built-in mappings keep their normal codec-selection 
precedence. An empty Mixin
 produces no generated output.
 
 A Mixin may place `JsonValidator` on a public abstract zero-argument `void` 
method that exactly
@@ -118,13 +118,13 @@ matches a public target method. The generated pair calls 
that target method dire
 does not need `JsonType` solely for a Mixin validator.
 
 The target does not need `JsonType` merely because it has a Mixin. `JsonMixin` 
is itself the
-processor entry point for the pair. If a target also uses `JsonType`, the 
runtime selects the
+processor entry point for the pair. If a target also uses `JsonType`, the 
built `ForyJson` instance selects the
 pair-specific companion for a non-empty registered Mixin instead of combining 
the overlay with the
 target's direct companion.
 
-Only one source is enabled for an exact target in one built runtime. A later 
registration for that
+Only one source is enabled for an exact target in one built `ForyJson` 
instance. A later registration for that
 target replaces an earlier registration on the builder, and `build()` 
snapshots the selected
-mapping. The processor may generate artifacts for multiple source 
alternatives; the runtime uses
+mapping. The processor may generate artifacts for multiple source 
alternatives; the built instance uses
 only the last registered source.
 
 Use the processor-generated R8 rules for non-empty Mixins instead of broad 
package keep rules.
diff --git a/docs/json/annotations.md b/docs/json/annotations.md
index 5d3a2dd590..9b91c3d898 100644
--- a/docs/json/annotations.md
+++ b/docs/json/annotations.md
@@ -28,7 +28,7 @@ Fory JSON APIs, not Jackson, Gson, or Fory binary-protocol 
compatibility annotat
 
 `JsonType` asks the annotation processor to generate direct property and 
creator operations plus
 exact retention rules on the JVM and Android. It is not inherited, so annotate 
each eligible
-concrete model that needs a generated companion on those runtimes. A directly 
annotated
+concrete model that needs a generated companion on those platforms. A directly 
annotated
 `JsonValue` Record also receives a companion for its value accessor and 
canonical constructor.
 Ordinary unannotated classes may still use reflection; on Android they need 
application-authored
 exact R8 rules. Android-desugared Records require processor-generated 
operations from either a
@@ -692,7 +692,7 @@ entry has a case-sensitive logical JSON name and exactly 
one trusted Java type s
 
 `className` is useful when an API JAR must not depend on an implementation 
JAR. It is resolved by
 the fixed builder class loader when the table is built. JSON input never 
supplies a Java class name
-and cannot add entries. Runtime registration and open subtype discovery are 
not supported.
+and cannot add entries. Post-build subtype registration and open subtype 
discovery are not supported.
 
 The default `PROPERTY` inclusion writes an inline discriminator as the first 
output member:
 
diff --git a/docs/json/getting-started.md b/docs/json/getting-started.md
index 6f715de28d..4c451f7438 100644
--- a/docs/json/getting-started.md
+++ b/docs/json/getting-started.md
@@ -46,7 +46,9 @@ Use the same version for every Fory module in one application.
 
 ### JDK 25 and later
 
-On JDK 25 and later, open `java.lang.invoke` to Fory core. For a classpath 
application:
+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`. For a classpath 
application:
 
 ```bash
 --add-opens=java.base/java.lang.invoke=ALL-UNNAMED
diff --git a/docs/json/graalvm.md b/docs/json/graalvm.md
index 25cc88731d..8c01c2831e 100644
--- a/docs/json/graalvm.md
+++ b/docs/json/graalvm.md
@@ -95,7 +95,7 @@ needed, and the provider package does not need to be exported 
or opened to Fory.
 methods and fields are not supported.
 
 Only configurations returned by a provider receive generated codecs. The 
default configuration is
-not generated implicitly. If a codegen-enabled runtime configuration was not 
included, Fory JSON
+not generated implicitly. If a codegen-enabled `ForyJson` configuration was 
not included, Fory JSON
 uses its prepared interpreted codecs and logs one process-wide warning 
recommending a reachable
 `@ForyJsonProvider`. `withCodegen(false)` explicitly selects interpreted 
codecs and does not request
 generated-codec lookup. Asynchronous compilation is disabled in a native 
executable.
@@ -132,17 +132,17 @@ it does for a direct `JsonType` model. A provider 
configuration generates the Mi
 target only when that exact Mixin is registered in the returned `ForyJson`.
 
 Only one source is enabled for an exact target in a built `ForyJson`. Later 
registration replaces
-an earlier source for subsequent `build()` calls; a runtime keeps the 
immutable snapshot it was
+an earlier source for subsequent `build()` calls; each built `ForyJson` 
instance keeps the immutable snapshot it was
 built with.
 
 ## Type Discovery and Construction
 
 The `fory-json` artifact activates its Native Image Feature automatically. 
`@JsonType` is not
-inherited, so annotate every concrete runtime model. An annotated base with a 
class-literal
+inherited, so annotate every concrete application model. An annotated base 
with a class-literal
 `@JsonSubTypes` table registers its listed subtypes automatically. Dedicated 
supported containers,
 including `EnumMap` and `EnumSet`, use their built-in factories. Other 
reachable concrete
 `Collection` and `Map` root types require a public no-argument constructor. A 
class referenced only
-by a runtime string is not reachable;
+by a class name resolved at runtime is not reachable;
 `JsonSubTypes.Type.className` is therefore unsupported in a native image.
 
 Do not add application reflection configuration as a replacement for the 
generated configuration.
diff --git a/docs/json/index.md b/docs/json/index.md
index 47a2e3683f..9e6dc17edf 100644
--- a/docs/json/index.md
+++ b/docs/json/index.md
@@ -21,8 +21,7 @@ license: |
 
 Fory JSON is Apache Fory's thread-safe Java JSON codec. It provides 
interpreted and
 runtime-generated codecs for Java objects, records, immutable creator-based 
classes, common JDK
-types, generic containers, custom complete-value codecs, and finite 
annotation-declared
-polymorphism.
+types, generic containers, and custom complete-value codecs.
 
 Fory JSON is a separate data format from Fory's binary native and xlang 
protocols. Use it when a
 system must exchange ordinary JSON with browsers, APIs, logs, configuration, 
or another JSON
@@ -31,34 +30,34 @@ reference identity, circular graphs, or Fory's binary-only 
features.
 
 ## Documentation map
 
-| Goal                                                             | Page      
                            |
-| ---------------------------------------------------------------- | 
------------------------------------- |
-| First runnable JSON round trip                                   | [Getting 
Started](getting-started.md) |
-| Understand Java object mapping and configuration                 | [Object 
Mapping](object-mapping.md)   |
-| Configure properties, creators, values, validators, and subtypes | 
[Annotations](annotations.md)         |
-| Extend complete values, children, and map keys                   | [Custom 
Codecs](custom-codecs.md)     |
-| Deploy on Android                                                | 
[Android](android.md)                 |
-| Build a GraalVM native image                                     | [GraalVM 
Native Image](graalvm.md)    |
-| Decode input safely                                              | 
[Security](security.md)               |
-| Diagnose failures                                                | 
[Troubleshooting](troubleshooting.md) |
+| Goal                                                           | Page        
                          |
+| -------------------------------------------------------------- | 
------------------------------------- |
+| First runnable JSON round trip                                 | [Getting 
Started](getting-started.md) |
+| Understand Java object mapping and configuration               | [Object 
Mapping](object-mapping.md)   |
+| Configure properties, creators, values, validators, and mixins | 
[Annotations](annotations.md)         |
+| Extend complete values, children, and map keys                 | [Custom 
Codecs](custom-codecs.md)     |
+| Deploy on Android                                              | 
[Android](android.md)                 |
+| Build a GraalVM native image                                   | [GraalVM 
Native Image](graalvm.md)    |
+| Decode input safely                                            | 
[Security](security.md)               |
+| Diagnose failures                                              | 
[Troubleshooting](troubleshooting.md) |
 
-## Limits and unsupported features
+## Performance
 
-Fory JSON intentionally has a smaller semantic surface than the Fory binary 
protocol and general
-Jackson object mapping:
+The Java JSON benchmark compares fory-json, Jackson, and Gson with the same 
data. Results below are
+single-threaded throughput measurements on an Apple M4 Pro with JDK 26.0.1; 
higher is better. See
+the [complete benchmark report](../benchmarks/json/java/README.md) for the 
command, environment, and
+measurement configuration.
 
-- no shared-reference identity or circular-reference protocol;
-- no open polymorphism, JSON class-name IDs, runtime subtype discovery, or 
runtime subtype table
-  extension;
-- no `InputStream` parser or incremental `OutputStream` writer on the 
`ForyJson` root API;
-- no pretty-print configuration;
-- no Jackson/Gson annotation compatibility layer;
-- no aliases, views, filters, injection, managed/back references, object 
identity annotations, or
-  root wrapping;
-- no Fory core `Expose` processing.
+![Java JSON String benchmark 
throughput](../benchmarks/json/java/string_throughput.png)
 
-Circular graphs eventually fail `maxDepth`; they are not reconstructed. Use 
Fory core's binary
-native or xlang protocol when reference identity or cycles are required.
+![Java JSON UTF-8 bytes benchmark 
throughput](../benchmarks/json/java/utf8_bytes_throughput.png)
+
+| Representation | Operation   | fory-json ops/sec | jackson ops/sec | gson 
ops/sec |
+| -------------- | ----------- | ----------------: | --------------: | 
-----------: |
+| String         | Serialize   |         7,387,465 |       2,049,368 |    
1,084,042 |
+| String         | Deserialize |         2,897,955 |       1,074,885 |      
902,772 |
+| UTF-8 bytes    | Serialize   |        10,375,498 |       1,868,614 |    
1,037,211 |
+| UTF-8 bytes    | Deserialize |         3,077,158 |       1,268,397 |      
933,079 |
 
 ## Related Java guides
 
diff --git a/docs/json/object-mapping.md b/docs/json/object-mapping.md
index 66375031d6..1563bc04d4 100644
--- a/docs/json/object-mapping.md
+++ b/docs/json/object-mapping.md
@@ -22,7 +22,7 @@ license: |
 ## Thread safety, reuse, and code generation
 
 `ForyJson` is immutable and thread-safe after `build()`. Reuse one instance 
instead of creating a
-builder and runtime for every operation. Registered and annotation-selected 
`JsonValueCodec`
+builder and `ForyJson` instance for every operation. Registered and 
annotation-selected `JsonValueCodec`
 instances and the `JsonTypeChecker` may be called concurrently and must also 
be thread-safe.
 
 Code generation and asynchronous compilation are enabled by default. Disabling 
code generation is
@@ -126,7 +126,7 @@ Collection interfaces are reconstructed with standard 
mutable implementations, s
 `TreeMap`, `ConcurrentHashMap`, or `ConcurrentSkipListMap`. 
`ArrayBlockingQueue`, `Arrays.asList`
 results, JDK immutable collections, empty/singleton/unmodifiable wrappers, 
constructor-constrained
 implementations, and unlisted Guava immutable implementations cannot be 
reconstructed. Guava
-support is optional and does not make Guava a required runtime dependency.
+support is optional and does not make Guava a required application dependency.
 
 Non-finite float and double values use the quoted strings `"NaN"`, 
`"Infinity"`, and
 `"-Infinity"`. Use explicit `BigInteger` or `BigDecimal` targets when 
arbitrary precision must be
@@ -213,7 +213,7 @@ size, only reusable writer storage retained after an 
operation.
 For class loading, type policy, nesting depth, graph-memory limits, and 
external input controls,
 see [Fory JSON Security](security.md).
 
-Builder mutation after `build()` does not modify an existing `ForyJson` 
runtime.
+Builder mutation after `build()` does not modify an existing `ForyJson` 
instance.
 
 On Android, runtime code generation and asynchronous compilation are disabled. 
In a GraalVM native
 image, runtime compilation is unavailable; configurations returned by a 
reachable


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

Reply via email to