ISSUE: Naming of error object encoding

[Mark Taylor]

On Wed, 30 Apr 2008, Mike Fitzpatrick wrote:

> On Wed, Apr 30, 2008 at 5:57 AM, Thomas Boch <boch at newb6.u-strasbg.fr>
> wrote:
>
>> In section 3.8, the error object is currently made up of a map with the
>> following keys : errortxt, usertxt, debugtxt and code.
>>
>> The naming of those keys could be improved by prefixing them with
>> "error." or even with "samp.error."
>
>
> I believe in an earlier draft it was explicitly stated that a message
> Response was
> not itself a Message (something I argued against).  The latest draft however
> is a
> little ambiguous on the matter, saying only that a  Response should be a
> map
> (which may be empty of sending back only an OK, but should contain those
> keys
> if an error).

In the Nomenclature section (2.1) it says

    "In the terminology of this document, a Response is not itself a
     Message."

>     I would take things a step further and suggest that the error map that
> is returned
> BE a Message map containing a status Mtype (e.g. status.error) and where the
> errortxt is a required param and the rest are optional.  In this case, a
> successful
> request could reply by setting only the 'success' argument and still have an
> empty
> map, but we could have a richer set of error returns that perhaps aren't all
> fatal.
> For example, a status.warning Mtype might still reply as a success but pass
> back
> a warning message, or a status.invalidParam could signal a specific
> and universally understood error condition.

I'm not necessarily against supplying a status in message responses;
a "status" (or "error.status" or "samp.error.status" or whatever)
key could be added to those suggested above and could take values
such as "error", "warning" and others from a well-known vocabulary
which we supply, possibly allowing users to extend it for their 
own purposes.

However, I think it would be unhelpful to label this status as an MType,
since such statuses only make sense as something returned from a Message
rather than sent unprovoked.  Also, if the status in the reply to 
a Message is an MType, it suggests that any MType is allowed in that 
slot.  Does this mean you can only receive a response from a message if 
you happen to be subscribed to the MType that it has when it is 
returned?  Given that an MType is documented to require some returned
value, does it mean that you have to reply to the response?
What are you supposed to do if you get a "spectrum.load" MType 
in the response to a message with a "get.param" MType? 
If you say that the only MTypes which can be allowed in those slots
are "status.*" ones, I don't see the advantage of these being MTypes
rather than just some separate controlled vocabulary.

>    My main objections to this simple set of keys are that 1) we allow only
> an OK/FAIL
> type of response, and 2) the 'errortxt' is allowed to be free-form (okay if
> all you want
> to do it pop up a dialog,  not okay  if an  app needs to parse the message
> for information).

Fair objections.

> 2) the 'errortxt' is allowed to be free-form (okay if all you want
>    to do it pop up a dialog,  not okay  if an  app needs to
>    parse the message

as I said above, by all means propose some key for a non-free-form, 
parsable value, and values it can take, to go along with the others 
proposed for the error response map.

> 1) we allow only an OK/FAIL type of response

I think you're suggesting that you might want to return whatever
is the return value from the message (as determined by the MType)
but also have the ability to flag a Warning or some other non-OK
status rather than assume that if a value is returned then the 
status must be OK.

The existing framework could be adapted to that - by allowing an
error object and the result object to coexist in the same map
(and possibly remove the "success" argument of the reply() and
receiveResponse() calls so that the notion of an absolute success
or failure is abolished altogether).

However, I'd argue against it as providing an unnecesary feature.
Procedure calls in most modern programming languages get by with
call semantics in which either the thing succeeds (and you can 
look at the return value to find out the result) or it fails 
(and throws and exception which you can examine to find out what
went wrong); no fuzzy third way is provided for.  This is the 
model I have in mind for the synch and asynch call/response
patterns, and I don't think that we need anything with more
flexibility than that.

Mark

-- 
Mark Taylor   Astronomical Programmer   Physics, Bristol University, UK
m.b.taylor at bris.ac.uk +44-117-928-8776 http://www.star.bris.ac.uk/~mbt/