[MOBY-dev] [RFC] Exception Reporting in bioMOBY v1.5 - INB proposal

[Martin Senger]

Thanks for the updated document. Before I express my comments to it
here is a few bits regarding RFC procedure for this proposal (assuming
that we agreed on an RFC procedure as, or close to, suggested in
previous emails:

1) I second the proposal (so it can become an RFC)

2) I suggest to resolve it (accept or refuse) before September 15 (so
this is an RFC calendar). Concretely, I propose that Mark will ask
selected voters after this date to vote on it. (BTW, I like and
support his idea to have a year-long tenure on the voting list (that's
actually very close why OMG has its Architecture Board also with
rotating, and *dedicated*, people).

Now back to the proposal, here are my comments (I suggest that those
comments that are acceptable by the INB authors, and that are not in
contradiction with the email discussion, will be incorporate and a new
draft will be circulated - perhaps already without reasoning).

Generally, I like the proposal, my comments are only about details.

1) The attribute names 'Value' and 'Description' are not
intuitive. They should express more what they are about. What about
"errorCode" (or only "code") and "errorMessage" (or only "message")?

2) I know that the article name in Simples in Collection is an
optional part of the proposal - but I agree with Mark that using there
again the term "articleName" is bad (too overloaded). What about to
use there a completely different tag, like "elementId"?

>From this change (if accepted) follows at once that the attribute name
in mobyException should not be "refArticleName" (because sometimes it
refers to a non-article name) - so why not to call it just a "ref", or
"refElement"?

3) I would like to have (in the exception API handling) a remark that
the clients are obliged to be aware that a service can also raise an
exception that will be delivered in the SOAP envelope (that is a
standard way). As I said, good clients have to do it anyway (because
your service does not have always full control what to return back) -
so I would keep this option there.

4) Just to keep in synch with other software projects, I would add one
more severity level - a simple "message" (so we would have, errors,
warnings, messages).

5) The list of codes is not always clear:
   - should the sub-phrases in 201 be distinguish by a separate code?
   - 621 (service not available) means actually that the resources the
service wishes to use are not available (because if it was a service
itself, it would not have any chance to report it, that would be a
soap exception mentioned above),
   - 622 (malformed Moby response) - what is a response here? - and
anyway, this may be difficult to catch (I know in SOAP::Lite you do
not get control only when the whole XML is parsed)
   - why do you call some codes "client-side detected errors"?

   - generally, I would put less codes and rather to define how
service providers can expressed their own service-specific codes (by
saying in which range they should put such specific codes)

6) Some typos:
   - articlename attribute should be articleName
   - "<--- BioMOBY parameters --->" is a wrong term (a "parameter" is
something else in Biomoby API)

7) Attributes in mobyException (refArticleName, or whatever name we
will agree on, and reqQuery) should be made optional - so an exception
can refer to the whole response (or to a whole query if only reqQuery
is present).


   With regards,
   Martin

-- 
Martin Senger
   email: martin.senger at gmail.com
   skype: martinsenger
International Rice Research Institute
Biometrics and Bioinformatics Unit
DAPO BOX 7777, Metro Manila
Philippines, phone: +63-2-580-5600 (ext.2324)