Fluent XML [1]

Few days ago I was writing a very boring piece of code that should generate some XML document. It was full of function calls that created nodes in the XML document and set attributes. Boooooring stuff. But even worse than that – the structure of the XML document was totally lost in the code. It was hard to tell which node is child of which and how it’s all structured.

Then I did what every programmer does when he/she should write some boring code – I wrote a tool to simplify the process. [That process usually takes more time than the original approach but at least it is interesting ;) .]

I started by writing the endcode. In other words, I started thinking about how I want to create this XML document at all. Quickly I decided on the fluent interface approach. I perused it in the OmniThreadLibrary where it proved to be quite useful.

That’s how the first draft looked (Actually, it was much longer but that’s the important part.):

xmlWsdl := CreateFluentXml
  .AddProcessingInstruction('xml', 'version="1.0" encoding="UTF-8"')
  .AddChild('definitions')
    .SetAttr('xmlns',         'http://schemas.xmlsoap.org/wsdl/')
    .SetAttr('xmlns:xs',      'http://www.w3.org/2001/XMLSchema')
    .SetAttr('xmlns:soap',    'http://schemas.xmlsoap.org/wsdl/soap/')
    .SetAttr('xmlns:soapenc', 'http://schemas.xmlsoap.org/soap/encoding/')
    .SetAttr('xmlns:mime',    'http://schemas.xmlsoap.org/wsdl/mime/');

This short fragment looks quite nice but in the full version (about 50 lines) all those SetAttr calls visually merged together with AddChild calls and the result was still unreadable (although shorter than the original code with explicit calls to XML interface).

My first idea was to merge at least some SetAttr calls into the AddChild by introducing two versions – one which takes only a node name and another which takes node name, attribute name and attribute value – but that didn’t help the code at all. Even worse – it was hard to see which AddChild calls were setting attributes and which not :(

That got me started in a new direction. If the main problem is visual clutter, I had to do something to make setting attributes stand out. Briefly I considered a complicated scheme which would use smart records and operator overloading but I couldn’t imagine a XML creating code which would use operators and be more readable than this so I rejected this approach. [It may still be a valid approach – it’s just that I cannot make it work in my head.]

Then I thought about arrays. In “classical” code I could easily add array-like support to attributes so that I could write xmlNode[attrName] := ‘some value’, but how can I make this conforming my fluent architecture?

To get or not to get

In order to be able to chain anything after the [], the indexed property hiding behind must return Self, i.e. the same interface it is living in. And because I want to use attribute name/value pairs, this property has to have two indices.

property Attrib[const name, value: XmlString]: IGpFluentXmlBuilder 
  read GetAttrib; default;

That would allow me to write such code:

.AddSibling('service')['name', serviceName]
  .AddChild('port')
    ['name', portName]
    ['binding', 'fs:' + bindingName]
  .AddChild('soap:address')['location', serviceLocation];

As you can see, attributes can be chained and I can write attribute assignment in the same line as node creation and it is still obvious which is which and who is who.

But … assignment? In a getter? Why not! You can do anything in the property getter. To make this more obvious, my code calls this ‘getter’ SetAttrib. As a nice side effect, SetAttrib is completely the same as it was defined in the first draft and can even be used insted of the [] approach.

I’ll end today’s instalment with the complete 'fluent xml builder’ interface and with sample code that uses this interface to build an XML document. Tomorrow I’ll wrap things up by describing the interface and its implementation in all boring detail.

type
  IGpFluentXmlBuilder = interface ['{91F596A3-F5E3-451C-A6B9-C5FF3F23ECCC}']
    function  GetXml: IXmlDocument;
  //
    function  Anchor(var node: IXMLNode): IGpFluentXmlBuilder;
    function  AddChild(const name: XmlString): IGpFluentXmlBuilder;
    function  AddComment(const comment: XmlString): IGpFluentXmlBuilder;
    function  AddSibling(const name: XmlString): IGpFluentXmlBuilder;
    function  AddProcessingInstruction(const target, data: XmlString): IGpFluentXmlBuilder;
    function  Back: IGpFluentXmlBuilder;
    function  Here: IGpFluentXmlBuilder;
    function  Parent: IGpFluentXmlBuilder;
    function  SetAttrib(const name, value: XmlString): IGpFluentXmlBuilder;
    property Attrib[const name, value: XmlString]: IGpFluentXmlBuilder
      read SetAttrib; default;
    property Xml: IXmlDocument read GetXml;
  end; { IGpFluentXmlBuilder }

  xmlWsdl := CreateFluentXml
    .AddProcessingInstruction('xml', 'version="1.0" encoding="UTF-8"')
    .AddChild('definitions')
      ['xmlns',           'http://schemas.xmlsoap.org/wsdl/']
      ['xmlns:xs',        'http://www.w3.org/2001/XMLSchema']
      ['xmlns:soap',      'http://schemas.xmlsoap.org/wsdl/soap/']
      ['xmlns:soapenc',   'http://schemas.xmlsoap.org/soap/encoding/']
      ['xmlns:mime',      'http://schemas.xmlsoap.org/wsdl/mime/']
      ['name',            serviceName]
      ['xmlns:ns1',       'urn:' + intfName]
      ['xmlns:fs',        'http://online.com/soap/']
      ['targetNamespace', 'http://online.com/soap/']
      .AddChild('message')['name', 'fs:' + baseName + 'Request'].Anchor(nodeRequest)
      .AddSibling('message')['name', 'fs:' + baseName + 'Response'].Anchor(nodeResponse)
      .AddSibling('portType')['name', baseName]
      .Here
        .AddChild('operation')['name', baseName]
          .AddChild('input')['message', 'fs:' + baseName + 'Request']
          .AddSibling('output')['message', 'fs:' + baseName + 'Response']
      .Back
      .AddSibling('binding')
      .Here
        ['name', bindingName]
        ['type', 'fs:' + intfName]
        .AddChild('soap:binding')
          ['style', 'rpc']
          ['transport', 'http://schemas.xmlsoap.og/soap/http']
          .AddChild('operation')['name', baseName]
            .AddChild('soap:operation')
              ['soapAction', 'urn:' + baseName]
              ['style', 'rpc']
            .AddSibling('input')
              .AddChild('soap:body')
                ['use', 'encoded']
                ['encodingStyle', 'http://schemas.xmlsoap.org/soap/encoding/']
                ['namespace', 'urn:' + intfName + '-' + baseName]
              .Parent
            .AddSibling('output')
            .AddChild('soap:body')
              ['use', 'encoded']
              ['encodingStyle', 'http://schemas.xmlsoap.org/soap/encoding/']
              ['namespace', 'urn:' + intfName + '-' + baseName]
      .Back
      .AddSibling('service')['name', serviceName]
        .AddChild('port')
          ['name', portName]
          ['binding', 'fs:' + bindingName]
          .AddChild('soap:address')['location', serviceLocation];

What do you think? Does my approach make any sense?