Mike Gerwitz

Activist for User Freedom

path: root/doc
diff options
authorMike Gerwitz <mike.gerwitz@rtspecialty.com>2018-03-07 13:20:21 -0500
committerMike Gerwitz <mike.gerwitz@rtspecialty.com>2018-03-07 13:46:05 -0500
commitc33adee21d9812ec131fb4e7b2bf34f93b505285 (patch)
treee1a78d1ddefe8f7f8d084b7bf12074c2e374ec6b /doc
parent8a01d5fd2e302842f5243965df62a9606fc68c2d (diff)
client: Truncate diff posted to server after first null
Before this change, since `undefined' is encoded as `null' when serialized, there was no way for the server to disambiguate between unmodified values and a truncation point. For example: [ undefined, undefined, null, null, null ] The above array represents two unmodified and three removed indexes. But this is serialzed into JSON as: [ null, null, null, null, null ] It isn't possible for the server to determine what the truncation point is from that diff. The solution is to therefore truncate the array _before_ sending it to the server, providing a trailing null to indicate that a truncation has occurred: [ null, null, null ] The above means that the first two indexes are unmodified, and that index 2 and later should all be truncated. * doc/client.texi (Saving to Server): New section. * src/client/transport/XhttpQuoteTransport.js (_truncateDiff): New method to perform truncation. (getBucketDataJson): Use it. * test/client/transport/XhttpQuoteTransportTest.js: New file with respective test case.
Diffstat (limited to 'doc')
1 files changed, 42 insertions, 0 deletions
diff --git a/doc/client.texi b/doc/client.texi
index 8955264..615c376 100644
--- a/doc/client.texi
+++ b/doc/client.texi
@@ -25,6 +25,7 @@
* Error Handling::
+* Saving to Server:: Posting bucket diff to the Server.
@end menu
@@ -96,3 +97,44 @@ When any field or classification changes that is represented on the
Error state is managed by
@srcref{src/validate/ValidStateMonitor.js, ValidStateMonitor}.
+@node Saving to Server
+@section Saving to Server
+@cindex Saving
+@cindex Bucket Diff
+@cindex Bucket Truncation
+@cindex Serialization
+To save changes,
+ the client posts only the bucket diff (@pxref{Bucket Diff}) to the
+ Server (@pxref{Server}).
+Because JSON serialization encodes @code{undefined} values as @code{null}
+ (as noted in @ref{Bucket Diff}),
+ and only the null in the tail position marks the truncation point,
+ the Client first truncates the array to include only the first
+ @code{null}.@footnote{
+ The server would otherwise remove only the last index,
+ even if multiple indexes were removed.}
+An example is shown in @ref{f:client-diff}.
+@float Figure, f:client-diff
+ // given (two unchanged, three removed)
+ [ undefined, undefined, null, null, null ]
+ // encodes into JSON as (bad; represents four unchanged, one removed)
+ [ null, null, null, null, null ]
+ // Client truncates to (two unchanged, >=2 removed)
+ [ null, null, null ]
+@end example
+@caption{Client diff truncation}
+@end float
+This conversion is handled by
+ @srcrefjs{client/transport,XhttpQuoteTransport}.
+Examples can be found in the respective test case
+ @testrefjs{client/transport,XhttpQuoteTransport}.