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_r249039114
########## 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. + The base implementation of this method writes nothing, i.e. it assumes that the outer serializer only has nested serializers and no extra information. + * `#readOuterSnapshot(int, DataInputView, ClassLoader)`. This method reads outer serializer snapshot, Review comment: This method reads 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
