141 lines
4.3 KiB
Plaintext
141 lines
4.3 KiB
Plaintext
@c This document is part of the Liza Data Collection Framework manual.
|
|
@c Copyright (C) 2017 R-T Specialty, LLC.
|
|
@c
|
|
@c Permission is granted to copy, distribute and/or modify this document
|
|
@c under the terms of the GNU Free Documentation License, Version 1.3
|
|
@c or any later version published by the Free Software Foundation;
|
|
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
|
|
@c Texts. A copy of the license is included in the section entitled ``GNU
|
|
@c Free Documentation License''.
|
|
|
|
@node Client
|
|
@chapter Client
|
|
@maintstart
|
|
@footnote{
|
|
The client is largely managed by a single class,
|
|
@srcref{src/client/Client.js, Client},
|
|
which has grown out of control.
|
|
@code{Client} mediates essentially the entire system.
|
|
Code is to be extracted out of this class as it is touched.
|
|
|
|
The other system mammoth is @code{Ui} (@pxref{Program UI}).}
|
|
@maintend
|
|
|
|
@helpwanted
|
|
|
|
@menu
|
|
* Error Handling::
|
|
* Saving to Server:: Posting bucket diff to the Server.
|
|
@end menu
|
|
|
|
|
|
@node Error Handling
|
|
@section Error Handling
|
|
|
|
@maintenance{
|
|
The complexity of this system and integration into legacy
|
|
layers has caused maintenance trouble in the past.
|
|
Each of the error checking layers need to be integrated
|
|
to reduce complexity.}
|
|
|
|
@cindex Error
|
|
@cindex Failure
|
|
There are three layers of error checking:@footnote{
|
|
Primarily for legacy reasons.
|
|
They are being consolodated as the system is touched.}
|
|
|
|
@enumerate
|
|
@item Required field checking@mdash{
|
|
}whether all required questions have been answered.
|
|
@item Type Validation@mdash{
|
|
}verify that questions contain valid data according to their
|
|
declared type. @ref{Validation}.
|
|
@item Assertions@mdash{
|
|
}arbitrary checks on data.
|
|
@ref{Assertions}.
|
|
@end enumerate
|
|
|
|
@cindex Required Field
|
|
@cindex Field, Required
|
|
@cindex Field, Fixed
|
|
@cindex Error, Fixed
|
|
@cindex Error, Required
|
|
@cindex Fixed, Error
|
|
Required fields fail serially@mdash{
|
|
}the system will notify the user of the required field,
|
|
and direct him/her to it (usually through scrolling).
|
|
A field is marked as @dfn{fixed} according to the rules
|
|
in @ref{Managing Error State}.
|
|
|
|
|
|
@menu
|
|
* Managing Error State:: Determining when failures should be marked as ``fixed''
|
|
@end menu
|
|
|
|
|
|
@node Managing Error State
|
|
@subsection Managing Error State
|
|
|
|
@cindex Failure Stack
|
|
@cindex Error Stack
|
|
Each failure caused by assertions is associated with a
|
|
@dfn{failure stack}.
|
|
The stack represents the trail of assertions that have run,
|
|
containing the ids of all values asserted against.
|
|
When any field or classification changes that is represented on the
|
|
failure stack,
|
|
the failure for the failed field associated with that failure stack
|
|
is cleared.
|
|
|
|
@exnotice{
|
|
If an assertion for some question @var{foo} first checked the value
|
|
of bucket field @var{bar},
|
|
and within its failure checked the value @var{c:predicate},
|
|
the failure stack would contain both of those ids.
|
|
If either @var{bar} or the @var{predicate} classification changed,
|
|
the question @var{foo} would have its error cleared.}
|
|
|
|
Error state is managed by
|
|
@srcref{src/validate/ValidStateMonitor.js, ValidStateMonitor}.
|
|
|
|
|
|
|
|
@node Saving to Server
|
|
@section Saving to Server
|
|
@helpwanted
|
|
|
|
@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
|
|
@example
|
|
// 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}.
|