== Was ist das == Flat2xml ist eine API, die dafür gut sein soll, Listen von Objekten in der<br> attributzentrierten XML-Form darzustellen.
Die Konvertierungsvorschriften werden selber auch in der XML-Form definiert.
Diese legen fest: *das XML-Format, d.h. die Tags mit den Atttributen und der hierarchischen Anordnung *wie werden die Daten berechnet bzw. wie werden den Attributen die Werte zugewiesen. *Woher kommen die Werte.
==API-Schnittstelle== Die Schnittstelle besteht aus zwei Komponenten: *Flat2XML-Konvertierungsvorschrift *Java-Schnittstelle
Die Syntax, Semantik, Tipps etc für die Vorschriften werden weiter möglichst<br> ausführlich erklärt.
Die Java-Schnittstelle ist denkbar einfach und wird hoffentlich wenn überhaupt,<br> dann nur unwesentliche Änderungen erfahren.
===Java-Schnittstelle=== Die homogene Liste myVector sei gegeben.<br> Sie soll in der XML-Form dargestellt werden.
Man erzeugt eine Instanz der Klasse Flat2XMLConvertor.<br> Der Flat2XMLConvertor-Konstruktor hat folgende Parameter: *Pfad zu der Flat2XML-Konvertierungsvorschrift *ein Gebilde namens ProcessRelief, anhand dessen man definiert **was das Ausgabeziel ist **welche (beliebige) Parameter dem Prozess mitgegeben werden **wie auf die Ereignisse während der Konvertierung reagiert wird. *DebugSwitch
===Für Anwender relevante Klassen=== ===Interface ProcessRelief=== Der Sinn des Interfaces ist paar Zeilen weiter oben erklärt.<br> Durch das Implementieren von print() und println() legt man fest,<br> wohin der XML-Strom geschrieben wird.
Zur Zeit gibt es: * einen DefaultRelief, der einen java.io.Writer oder einen java.io.OutputStream bekommen kann, in die er den XML-Strom schreibt. *einen DCSProcessRelief, der auf den DCS-Server die Daten schreibt.
Ein wesentlicher Punkt soll noch erwähnt werden. Das Interface definiert die<br> Methode Object getParameter(String name).<br> Diese kann von den Berechnungen (Vorschrift) aufgerufen werden, wodurch man die<br> Möglichkeit hat, die Konvertierung zu steuern oder ihr zusätzliche Informationen mitzugeben.
Die Implementierungen von ProcessRelief bekommen einen Flat2XMLListener.
Flat2XMLListener hat folgende drei Methoden: *void onWarning(String message, Object o, Throwable t); :Diese Methode wird vom Konvertierungsprozess aufgerufen, wenn eine zulässige, :aber doch nicht ganz glatte Situation zustande kommt. *void onError(String message, Object o, Throwable t); :Wird aufgerufen, wenn ein Fehler bei der Berechnung auftrit oder die :Berechnungen eine Situation ergeben, die durch die Konvertierungsvorschrift :als fehlerhafte zu defenieren ist. *void onProcess(Object o); :Listenelement o kommt in die Verarbeitung rein.
Es ist gut denkbar, dass die aufrufenden Stellen dieses Interface implementieren,<br> weil sie wissen, wie auf die beschriebenen Ereignisse zu reagieren ist.<br> Im einfachsten Fall kann die Reaktion das Protokolieren sein.
===Konvertierungsvorschrift=== Wie schon erwähnt, die Vorschriften werden in der XML-Form verfasst.
Detailierte Erklärung ist in der Datei Flat2XMLDefinition.txt.
An der Stelle seien nur paar allgemeine Worte gesagt.
Angenommen, die zu verarbeitende Liste enthält Elemente vom Typ<br> Wohnung und man wolle als Ergebnis die XML-Ausgabe im folgenden Format haben:
<code>
<Wohnung preis="120000" flaeche="82"> <Zimmer zweck="Kinderzimmer" flaeche="18" ausrichtung="sued" balkon="false"/> <Zimmer zweck="Schlafzimmer" flaeche="15" ausrichtung="nord" balkon="false"/> </Wohnung>
</code>
Die Tags Wohnung und Zimmer kommen zustande durch folgende Fragmente in der<br> Flat2Xml-Definition
<code>
<object name="Wohnung"> <parameter name="zweck"/> <parameter name="flaeche"/> <parameter name="ausrichtung"/> <parameter name="balkon"/> </object>
</code>
Die Definitionen von Parametern sind nicht vollständig, sie beschreiben nicht,<br> wie die Werte berechnet werden. Dieses Thema ist der Gegenstand der o.g.<br> Flat2XMLDefinition.txt-Datei.