On Jun 9, 2010, at 3:36 PM, Darryl L. Pierce wrote:
On Wed, Jun 09, 2010 at 11:59:00AM +0200, Andrew Beekhof wrote:
I've written up the following document:
https://fedorahosted.org/matahari/wiki/Requests
to describe the XML documents sent to and returned from Matahari over virtio-serial.
Please take a few minutes to review and provide feedback on this format.
I would lean towards dropping the <args> scaffolding. We had them in pacemaker originally but removed them later because they didn't add any value and were annoying when packing and unpacking messages.
Fair point. Though I still would rather err on the side of using a container tag when multiples of a tag are returned. Then the rules for return different types of tags (such as a <value> and an <array> if we go down that path) are in the <responses> tag and not the <matahari> tag.
Sure. I think this is what they're doing for the REST stuff and being consistent is good.
Also, I'm not sure about:
<response name="hostname">webserver01.priv.virt.mydomain.org</response>
Will all response elements have obvious names?
I modeled the XML along the lines of SOAP. Each value returned is mapped to a name so the client can extract them, since more than one value can be returned as you mention below.
ok
What about returning tuples? Some of the searches in the cluster and packaging sections need to return tuples like: (filename, linenum) and (provider, type)
This would be solved when we tackle how we return arrays. I have a solution in mind that should answer both this question and the previous one about arrays.
<matahari request-id="abc123" type="response"> <responses> <response name="hostname">web.farkledoodle.com</response> <response name="addresses" response-type="array"> <element>192.168.1.1</element> <element>192.168.1.2</element> </response> <response name="interfaces" response-type="array"> <element> <value name="name">eth0</value> <value name="mac">00:11:22:33</value> </element> <element> <value name="name">eth1</value> <value name="mac">11:22:33:44</value> </element> </response> </array> </responses> </matahari>
In the above example, an array is identified by the response-type attribute. By default this value is "scalar" and only the child text tag is the value. But if the response-type is "array" then one of more element tags are parsed and the child text for those are the values of the array.
In the case of an array of tuples, then each element tag can have one or more value tags that are the name to value mapping for those tuples. So that would solve the above case where you name filename and linenum, or provider and type, returned within an array.
Thoughts?
Apart from dropping the response-type field, I think its pretty good. For consistency though, it might be preferable to always use the third form - even when returning a single hostname. This would simplify the packing and unpacking logic.
So: <response name="hostlist"> <element> <value name="hostname">web.farkledoodle.com</value> </element> </response>
instead of: <response name="hostname">web.farkledoodle.com</response>
Now "//value[@name=hostname]" works regardless of how many results come back or if other data was also included.
I used "value" for the tag within the element tag to avoid recursion. But maybe we _want_ to have that type of deep nesting of values?
Do you have a particular use case in mind? I think avoiding recursion, at least initially, would be a good thing.
That would allow us to model larger object graphs as needed without imposing any artificial limitation now. Maybe rather than <responses> and <response> we could use <values> and <value> instead?
-- Darryl L. Pierce, Sr. Software Engineer @ Red Hat, Inc. Delivering value year after year. Red Hat ranks #1 in value among software vendors. http://www.redhat.com/promo/vendor/