Formatters

The format of the data that is read or written is defined by a formatter. An XML formatter, for example, reads and writes XML format. A CSV formatter reads and writes comma-separated values.

A formatter interprets the arrangement of elements and attributes in different ways. In an XML configuration file, the formatter can be defined by an element whose name starts with the format type (for example, "xml" or "csv"), and ends with "-format". Formatter names are in the dmio namespace. The XML and CSV formatters, for example, are named dmio:xml-format and dmio:csv-format.

An element can also define a formatter with the formatter attribute. 

    
    <dmio:xml-format id="foo"/>
    <dmio:element formatter="foo"/>

An XML formatter reads and writes XML that mirrors the element and attribute structure. The element and attribute names are used for the XML element and attribute names. If, for example, we had elements and attributes arranged like this: 

    
    <dmio:element name="class">
      <dmio:xml-format/>
      <dmio:attribute name="name" value="class.name"/>
      <dmio:attribute name="book" value="class.book"/>
      <dmio:element name="teacher">
	<dmio:attribute name="first" value="teacher.name.first"/>
	<dmio:attribute name="last" value="teacher.name.last"/>
      </dmio:element>
    </dmio:element>

then we might have XML that looked like this: 

    
    <class name="class1" book="book1">
      <teacher first="Mabel" last="Rasmussen"/>
    </class>

A CSV formatter reads or writes each element as a row, and each attribute as a field in the row. If we had elements and attributes arranged like this: 

    
    <dmio:element>
      <dmio:csv-format/>
      <dmio:attribute value="class.pk"/>
      <dmio:attribute value="class.name"/>
      <dmio:attribute value="class.book"/>
      <dmio:attribute value="teacher.pk"/>
    </dmio:element>

then we might have output like this: 

    
    0,class1,book1,9
    1,class2,book2,6
    2,class3,book3,7
    3,class4,book4,2

Elements and Named Values

When an XML formatter writes an element, it looks to see if a value name has been set into the element (with setValueName()). If not, then the formatter simply writes the element, its attributes, and its nested elements.

Otherwise, it gets the value by name from the element. If the value is a single value (not a value list), then the formatter writes the element, attributes, and nested elements.

If the value does contain a value list, then the formatter writes the element (with attributes and nested elements), for each value in the list. Before writing the element, it sets the value into it, to be accessed by attributes and nested elements.

For example, assume in the next code fragment, that an XML formatter is writing the element named class. At some time previously, a value named semester has been given to the element. semester contains a value list named classes, which contains a list of objects, each named class.

For each class value, the formatter will write the element, first setting the class value into the element. The name attribute can look up the value named name in the class value, by referring to it as class.name. 

    
    <dmio:element name="class" value="semester.classes">
      <dmio:attribute name="name" value="class.name"/>
    </dmio:element>