alpinegizmo commented on a change in pull request #7475: [FLINK-11292][doc]
Update document about how to use new CompositeType…
URL: https://github.com/apache/flink/pull/7475#discussion_r249038967
##########
File path: docs/dev/stream/state/custom_serialization.md
##########
@@ -223,15 +227,38 @@ the same `TypeSerializerSnapshot` class as their
snapshot would complicate the i
This would also be a bad separation of concerns; a single serializer's
serialization schema,
configuration, as well as how to restore it, should be consolidated in its own
dedicated `TypeSerializerSnapshot` class.
-#### 3. Use the `CompositeSerializerSnapshot` utility for serializers that
contain nested serializers
+### Extending `CompositeTypeSerializerSnapshot` for serializer snapshot with
nested serializers
-There may be cases where a `TypeSerializer` relies on other nested
`TypeSerializer`s; take for example Flink's
-`TupleSerializer`, where it is configured with nested `TypeSerializer`s for
the tuple fields. In this case,
-the snapshot of the most outer serializer should also contain snapshots of the
nested serializers.
+Before further explanation, we call the serializer, which relies on other
nested serializer(s), as "outer" serializer in this context.
+Eamples for this could be `MapSerializer`, `ListSerializer`,
`GenericArraySerializer`, etc., and take `MapSerializer` for example,
+the map-key and map-value serializers consist as the nested serializers, while
`MapSerialize` itself is the "outer" serializer.
+In this case, the snapshot of the most outer serializer should also contain
snapshots of the nested serializers.
+Besides, unlike the former two serializers, `GenericArraySerializer` also
contains some extra static information, a class of the component type,
+that needs to be persisted beyond the nested component serializer.
-The `CompositeSerializerSnapshot` can be used specifically for this scenario.
It wraps the logic of resolving
+`CompositeTypeSerializerSnapshot` is a convenient serializer snapshot class
for serializers which delegate its serialization
+to multiple nested serializers, and also useful for serializers which need to
persist some extra static information as its snapshot.
+It wraps the logic of resolving
the overall schema compatibility check result for the composite serializer.
-For an example of how it should be used, one can refer to Flink's
+
+When adding a new serializer snapshot as a subclass of
`CompositeTypeSerializerSnapshot`,
+the following three methods must be implemented:
+ * `#getCurrentOuterSnapshotVersion()`. This method defines the version of
+ current outer serializer snapshot's written binary format.
+ * `#getNestedSerializers(TypeSerializer)`. Given the outer serializer,
returns the nested serializers.
+ * `#createOuterSerializerWithNestedSerializers(TypeSerializer[])`.
+ Given the nested serializers, create an instance of the outer serializer.
+
+For serializers needing to contain some extra static information, the
following two methods must also be implemented:
+ * `#writeOuterSnapshot(DataOutputView)`. This method writes outer serializer
snapshot, i.e. any information beyond the nested serializers.
Review comment:
Insert "the":
This method writes the outer serializer snapshot ...
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
With regards,
Apache Git Services
