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 536017d8227b5130a4867be08a2b7ea1ad0df65c Author: chaokunyang <[email protected]> AuthorDate: Wed May 13 05:41:34 2026 +0000 🔄 synced local 'docs/specification/' with remote 'docs/specification/' --- docs/specification/java_serialization_spec.md | 54 +++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/docs/specification/java_serialization_spec.md b/docs/specification/java_serialization_spec.md index 7906a329b6..1cba88ebc4 100644 --- a/docs/specification/java_serialization_spec.md +++ b/docs/specification/java_serialization_spec.md @@ -430,6 +430,23 @@ per-element null flags (if HAS_NULL). If `IS_SAME_TYPE` is not set, each element is written with its own class info and data (and optionally ref flags). +#### Child collection subclasses + +Optimized serializers for subclasses of supported JDK collection implementations write subclass +field layers before element payloads: + +``` +| varuint32_small7: length | [comparator_ref] | varuint32_small7: num_class_layers | +| class_layer_fields... | [elements_header | elem_class_info | elements...] | +``` + +- `comparator_ref` is present only for sorted-set and priority-queue subclasses. +- `num_class_layers` is the exact number of subclass-owned field layers written after the collection + header and before the element payload. +- Readers must reject a payload whose `num_class_layers` does not match the local serializer's layer + count. These serializers do not carry per-layer class identity in the value payload, so mismatched + layers cannot be skipped safely. + ### Maps Maps encode entry count and then a sequence of chunks. Each chunk groups entries that share key @@ -471,6 +488,23 @@ These chunks always represent exactly one entry. - `1`: Java-serialized empty `EnumMap` payload. Android uses this mode when an empty map has no public key from which to derive the enum class. Readers on Android and JVM must accept both modes. +#### Child map subclasses + +Optimized serializers for subclasses of supported JDK map implementations write subclass field +layers before map entry chunks: + +``` +| varuint32_small7: size | [comparator_ref] | varuint32_small7: num_class_layers | +| class_layer_fields... | [chunk_1 | chunk_2 | ...] | +``` + +- `comparator_ref` is present only for sorted-map subclasses. +- `num_class_layers` is the exact number of subclass-owned field layers written after the map header + and before the entry chunks. +- Readers must reject a payload whose `num_class_layers` does not match the local serializer's layer + count. These serializers do not carry per-layer class identity in the value payload, so mismatched + layers cannot be skipped safely. + ### JDK collection/map wrappers and views Java native mode may use specialized serializers for JDK collection/map wrappers and views. These @@ -514,6 +548,26 @@ serialization: - For each field, the serializer uses field metadata (nullable, trackingRef, polymorphic) to decide whether to write ref flags and/or type meta before the field value. +### Throwable values + +`Throwable` subclasses use a specialized payload that preserves stack trace, cause, message, +suppressed exceptions, and subclass-owned fields: + +``` +| stack_trace_ref | cause_ref | message_string_ref | +| varuint32: suppressed_count | suppressed_ref... | +| varuint32: extra_field_count | extra_field_name/value... | +| varuint32_small7: num_class_layers | class_layer_fields... | +``` + +- `extra_field_count` is reserved for serializer-owned extension fields and is currently written as + zero. +- `num_class_layers` is the exact number of `Throwable` subclass field layers written after the + built-in Throwable state. +- Readers must reject a payload whose `num_class_layers` does not match the local serializer's layer + count. The Throwable value payload does not carry per-layer class identity, so mismatched layers + cannot be skipped safely. + ### Extensions (EXT) Extension types are encoded by their registered serializer. Type meta is still written before the --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
