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. + -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. + + +| 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]
