From 9e816ea92c72d1fb1061813ae65f83c8051196a3 Mon Sep 17 00:00:00 2001 From: Luca Frosini Date: Mon, 24 Jun 2024 16:03:22 +0200 Subject: [PATCH] improved docs --- docs/update-type-definition-guideline.rst | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/update-type-definition-guideline.rst b/docs/update-type-definition-guideline.rst index 66490d5..bc5dc09 100644 --- a/docs/update-type-definition-guideline.rst +++ b/docs/update-type-definition-guideline.rst @@ -577,9 +577,9 @@ which will be serialized/deserialized in turn as: } The problem of this solution is that if the facet is updated to the new format in the server and -there are old clients they will not be able to deserialize the new version. +if there are old clients they will not be able to work with the new version. -With this solution the 'event' property in the server is of type ANY (an Object in Java) +With this solution the ``event`` property in the server is of type ANY (an Object in Java) .. code:: java @@ -612,7 +612,9 @@ The future release of ``EventFacet`` will * deprecate ``public Event getTheEvent();`` * add ``public Event getEvent();`` - +To summarize: +This solution is capable of reading old format existing instances, +but it always updates the instances to the new format which cannot be used by an old client. Java and Javascript Backwards Compatibility @@ -941,15 +943,22 @@ Both ``event`` and ``theEvent`` will coexist until the next version. This solution has the following issue: -``date`` and ``event`` may not align with ``theEvent`` if updated from old clients. +``date`` and ``event`` may not align with ``theEvent`` if updated by old clients. -The proposed implementation involves ``setTheEvent()``, which could potentially overwrite ``date`` if invoked by Jackson beforehand. +The proposed implementation involves ``setTheEvent()``, which could potentially overwrite +``date`` and ``event`` if invoked by Jackson beforehand. Therefore, implementing this correctly requires careful consideration. -It's important to note that only old clients might disalign the ``date``. +It's important to note that only old clients might disalign the date. As a result, the most advanced values always reside in the old properties. Conversely, a new client would have already corrected and aligned them. Of course, there is no resolution for bugged new clients causing misalignments, but that's a separate issue not covered in this guide. +**To summarize**: +This solution is capable of reading old format existing instances. +New clients update the properties in both old and new formats. +It can be used by old clients, but new clients must take into account that an update +made by an old client causes misalignment of the date and event properties with the +corresponding properties contained in the ``theEvent`` property.