diff --git a/docs/update-type-definition-guideline.rst b/docs/update-type-definition-guideline.rst index 0a83377..fe5f960 100644 --- a/docs/update-type-definition-guideline.rst +++ b/docs/update-type-definition-guideline.rst @@ -102,7 +102,7 @@ which produces the following type definition: "extendedTypes": [ "Facet" ] } -At a certain point, the information-system-model introduces the following Property type, which models an event. +At a certain point, the ``information-system-model`` introduces the following ``Property`` type, which models an event. .. code:: java @@ -267,9 +267,11 @@ which produces the following type definition: } -So imagine you want to update the 'EventFacet' type definition to use this property type instead of the 'date' and 'event' properties. +So imagine you want to update the ``EventFacet`` type definition to use this property type instead of the ``date`` and ``event`` properties. -To update the 'EventFacet' there are different strategies: +The objective is to obtain a facet with ``event`` property as an ``Event``. + +To update the ``EventFacet`` there are different strategies: Java Backwards Compatibility @@ -409,7 +411,6 @@ which produces the following type definition: "extendedTypes": [ "Facet" ] } - The implementation should be something like this: .. code:: java @@ -544,9 +545,10 @@ The implementation should be something like this: With this strategy, any Java client reading the event facet instantiated with the old -model will remap the 'date' and 'event' properties to an instance of 'Event' named 'event'. +model will remap the ``date`` and ``event`` properties to an instance of ``Event`` named ``event``. -We receive + +We receive: .. code:: javascript @@ -557,7 +559,7 @@ We receive "event": "certified" } -which will be serialized in turn as: +which will be serialized/deserialized in turn as: .. code:: javascript { @@ -575,8 +577,48 @@ which will be serialized 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 deserialise the new version. +there are old clients they will not be able to deserialize the new version. +With this solution the 'event' property in the server is of type ANY (an Object in Java) + + +.. code:: java + + @ISProperty(name=EVENT_PROPERTY, type=Object.class, description = .... + public Event getTheEvent(); + +The ``@ISProperty`` annotation specifies the type of the property ``type=Object.class`` instead of letting the system to get the type from the function return, i.e. ``Event``. +The type definition in JSON has: + +.. code:: javascript + + "propertyType": "Any" + + +PRO: + * the name of the variable is already ``event`` as we want as final objective. + +CONS: + * the server cannot check the validity of the variable received from an updating client. + +The future release of ``EventFacet`` will + +* remove ``type=Object.class`` from ``@ISProperty`` annotation; +* remove deprecated methods from the Java interface and its implementation: + * ``public Date getDate();`` + * ``public void setDate(Date date);`` + * ``public String getEvent();`` + * ``public void setEvent(String event);`` +* deprecate ``public Event getTheEvent();`` +* add ``public Event getEvent();`` + + + + +Java and Javascript Backwards Compatibility +---------------------------- + +This solution is Java compliant from a code perspective and the old properties are keep for old clients. .. code:: java @@ -810,6 +852,7 @@ The implementation should be the following: * * It eventually instantiate {@link Event} if null. */ + @JsonSetter("event") public void setEvent(String event) { if(event == null) { this.theEvent = new EventImpl(); @@ -838,3 +881,74 @@ The implementation should be the following: } +With this strategy, any Java client reading the event facet instantiated with the old +model will remap the 'date' and 'event' properties to an instance of 'Event' named 'theEvent'. +The old properties 'date' and 'event' properties are still available for old clients. + +We receive + +.. code:: javascript + + { + "type": "EventFacet", + "id": "d9f91175-8c33-4f68-8619-48e6feca4e47", + "date": "2024-01-08 12:52:59.907 +0100", + "event": "certified" + } + +which will be serialized/deserialized in turn as: + +.. code:: javascript + { + "type": "EventFacet", + "id": "d9f91175-8c33-4f68-8619-48e6feca4e47", + "date": "2024-01-08 12:52:59.907 +0100" + "event": "certified", + "theEvent": { + "type": "Event", + "what": "certified", + "when": "2024-01-08 11:52:59.907 +0000", + "who": null, + "where": null, + "why": null, + "how": null + } + } + +With this solution we use ``theEvent`` property in the server of type Event which validity can be checked by the server: + +PRO: + * the server can check the validity of the variable received from an updating client. + +CONS: + * the name of the variable is ``theEvent`` and only in a future step will be changed. + + + +The future release of ``EventFacet`` will + +* remove deprecated methods from the Java interface and its implementation: + * ``public Date getDate();`` + * ``public void setDate(Date date);`` + * ``public String getEvent();`` + * ``public void setEvent(String event);`` +* deprecate ``public Event getTheEvent();`` +* add ``public Event getEvent();`` + +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. + +The proposed implementation involves ``setTheEvent()``, which could potentially overwrite ``date`` 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``. +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. +