[hyades-dev] Notes on Choreography document

[Allan K Pratt <apratt@xxxxxxxxxx>]

I have more comments on the latest Choreography document:

I still can't get behind the whole Variable / VariableGroup structure as 
it appears in this API. There are five ways to get an instance of a 
Variable: from getRootVariableGroup, from getVariableGroup, and from 
getAllVariables and its two friends. Will all these mechanisms return the 
same Variable instance for a given variable? The document doesn't say. But 
it matters: if one piece of code uses getRootVariableGroup and another 
uses getVariable, and either piece uses getVariableValue, will the other 
piece see its value change? If I *want* that behavior, but the Variable 
instances can be different, then I need to do some processing to coalesce 
multiple instances with the same id into a single instance.

What are the possible error conditions for setVariableValue? I see the 
declaration that it throws BadTypeException but I think we need a 
BadValueException too. 

Does setVariableValues act as a transaction, throwing an exception and 
applying none of the changes if there is any error? The alternative is to 
set those which have legal values, and leave the others alone; but this 
can result in an inconsistent configuration. In either case, does the 
exception report which variable(s) in the array had bad values? Remember, 
we're driving a generic UI, so we don't have client-side verification of 
values, so we need to use the exception to provide user feedback as to 
what's wrong.

I see a problem that is caused by setVariableValue taking a Variable as 
its argument, with its new "value" object already in place. What if that 
value is invalid? Remember, we've got a generic UI that doesn't know what 
range of values is valid for a Variable. If the user enters an invalid 
value and clicks "Apply," the UI will write the new value into the 
Variable object and call setVariableValue. This can throw 
BadValueException, but now the old value is lost. I guess the UI should 
keep the old value(s) around and restore them if setVariableValue(s) 
throws an exception. This should be noted in the document as guidance to 
UI writers.

I think the description of "event_based" is too fuzzy. This spec will be 
useless if it doesn't describe the behavior more exactly, so agent writers 
and UI writers know what to expect. Otherwise a client writer and an agent 
writer can have different ideas about the result of calling a variable 
"event based." I think you could say "when the event_based flag is true, 
that indicates that the UI should render the Variable as a button: 
pressing it causes a setVariableValue call, but the actual value is 
immaterial: the fact that the value is being set causes the agent to take 
some action." We could have more than one type of event_based button: one 
is as I just described, and another is rendered as a pushbutton that's 
"in" or "out" - a toggle. When false, say, the button is "out," and 
pushing it sets it to true and changes the UI state. By contrast, a 
Boolean variable could be rendered as a checkmark and not take effect 
until the user hits an "Apply" button, which causes all changes to be sent 
at once.

<UI design aside regarding the need for an "Apply" button>

On one call Antony described his imagined UI this way: for an integer 
variable, the user can type a new value, and "when they click away" the 
new value is sent. In my opinion that is not a good user experience. The 
first reason is that it leaves users wondering what to do to make their 
change take effect, while an Apply button is explicit. The second reason 
is that two changes can get commingled: if a Boolean is rendered as a 
checkmark, I suppose you'd send the change as soon as I clicked in the 
square. If I also had a pending integer change, they would both be sent. 
If the integer change was invalid, the experience is that I click on a 
checkmark and see an error message about an integer.

If the settings were all checkboxes and buttons, this wouldn't be an 
issue. But we also have boxes into which the user types a string, int, or 
double, so we need an action to know when the user is finished. I don't 
have a Human Interface background and I can't cite studies to back this 
up, but "Click anywhere outside the field's box to make your change take 
effect" doesn't seem like an easy thing to convey to a user. I can't think 
of anything in Eclipse that works that way, either, though Eclipse is 
hardly a paragon of UI design.

<End of UI design aside.>

-- Allan Pratt, apratt@xxxxxxxxxx
Rational software division of IBM