[MOBY] [MOBY-l] Input XML syntax

[Mark Wilkinson]

On Wed, 2003-10-22 at 18:23, Ken Steube wrote:
> OK, I'm getting serious about figuring out input XML syntax: four
> questions.

you certainly are!  ...and you are finding all sorts of documentation
errors - thank you for that!

> 1) In the API examples of collections are given in a couple places as
> 
>   <Collection/>
>     <Object namespace="Genbank/gi" id="163483"/>
>     <Object namespace="Genbank/gi" id="244355"/>
>     <Object namespace="Genbank/gi" id="533253"/>
>     <Object namespace="Genbank/gi" id="745290"/>
>   </Collection>
> 
> But shouldn't they have Simple tags?
> 
>   <Collection articleName="NameOfArticle">
>     <Simple><Object namespace="Genbank/gi" id="163483"/></Simple>
>     <Simple><Object namespace="Genbank/gi" id="244355"/></Simple>
>     <Simple><Object namespace="Genbank/gi" id="533253"/></Simple>
>     <Simple><Object namespace="Genbank/gi" id="745290"/></Simple>
>   </Collection>

they absolutely should.  I just fixed the API docs on the Wiki.


> 2) There is an articleName on Collection as shown above in one of the
> examples, but the articleName really belongs instead on the queryInput
> tag in the case of named arguments.  Or it may be on any MOBY data
> object and I don't think articleName is useful anywhere else.  Is that
> right?

Actually, that was incorrect in the documentation also.  The articleName
attribute belongs to the Simple/Collection element, not to the
queryInput element.  This is because in a single invocation of the
service (i.e. a single queryInput) there may be multiple named
parameters of the Simple/Collection type.  thus the queryInput itself is
not named, but the articles it contains are.


> 3) Is it OK for a queryInput to have multiple Simples as shown below?  I
> think not...they should be separate queryInputs or should be in a
> collection.
> 
> <queryInput>
>   <Simple>...</Simple>
>   <Simple>...</Simple>
> </queryInput>

no, this is not allowed.  In the CommonSubs module, I do make allowances
for this error by passing an array back from parsing the content of a
Simple article, but it *should* always be an array of length 1, and in
my example services I enforce this by taking only element $array[0] from
the array and using that as the input.  Whether or not other service
providers will allow for this is up to them, but I would discourage it,
since it isn't correct message structure.

> 4) If I receive two queryInputs it should be as if I ran the service
> two separate times and concatenated the response XML together. Right?
> Which is different than running the service once with two inputs.

correct.  Two queryInput elements is equivalent to "clicking the execute
button twice", but passing the result back in a single message.

Nota Bene - we are making one dramatic change to the message structure
as a consequence of the MOBY meeting - the queryInput elements will now
be *numbered*, and the queryResponse elements will be enumerated with
the same number as the queryInput that they result from.  This will
allow service providers to run operations in parallel without having to
worry about outputting the results in the same order as the inputs. 
This will also rid us of the Invocation object, whose original task was
to make this correlation (but it failed miserably in that regard).  I
will make this change to the API documentation shortly.  Most of this
will be handled by the CommonSubs routines, but there will be some
necessity for modification of existing services... unfortunately...

M