Writing exporters

Here are basic rules for writing an exporter. I will present some examples in the XSLT language because I assume it will be used mostly to write an exporter.

First step of processing an XML is the transformation with an exporter. Of course this step is optional - source document nametree may be transported directly to coordinator if the coordinator accepts nametree's namespace. However if you intend to use an exporter, here are some conditions that must be met:

  • The exporter transforms a single nametree - elements from exactly one namespace. Elements can contain attributes from other namespaces though.
  • The exporter can produce XML with multiple namespaces. In such case the output document is split into the nametrees and handled separately by following exporters or a coordinator. The exporter may produce multiple namespaced XML only if it produces DOM/SAX/STAX result (Object and Stream results does not have notion of a namespace).
  • Elements in source XML may contain special attribute gene:id having namespace "dom://baka.sk/xml/gene" as specified in the GENE_ID_ATTRIBUTE_QNAME property. This attribute with its value should be copied to result element spawned from transforming the source element. If the transformation fails to do so, that part of document will not be backwards identifiable, rendering this part as read-only in WYSIWYG editors for example. You may generate IDs for text nodes aswell, for example by packaging the text in some kind of inline element having ID of the text.
  • You may encounter the 'generef' processing instruction in the source document. It marks the entrypoint to nametree with another namespace. Just copy it into the target document.
  • If a text/cdata value is modified (string operations as concatenation, etc.) in the process of transformation, it should lose the gene:id attribute.
  • Exporter must not produce entity nodes. This does not apply for XSLT scripts: they are not able to do so.
  • The exporter must not expect all elements to have IDs. If the exporter processes output of some previous exporter (please see the processingSource parameter for details) it must not create IDs for text nodes - these IDs already are generated by first exporter in the exporter chain. However, if you need an ID of a text node (for example to create a reference to the node), you may use the following algorithm:

    Most commonly used method to transport the ID of a text is to enclose it in an element with its ID being set as the value of the gene:id attribute. Thus, if the text node's parent element's ID is synthetic then there is a high probability that it is the ID of text we are searching for.