5 Das transformer-Objekt

Das Transformer-Objekt ermöglicht den Durchlauf eines XML-Dokuments oder einer IDM-Objekthierarchie, wobei während dieses Durchlaufs an einzelnen Knoten semantische Aktionen ausgeführt werden können. Auf diese Weise kann leicht eine Transformation von Daten implementiert werden, bei der z.B. entweder XML-Daten in IDM-Objekte übertragen werden oder umgekehrt mit Daten, die in IDM-Objekten stehen, ein XML-Dokument generiert wird. Da die semantischen Aktionen durch benutzerdefinierte Codes beschrieben werden, ist die Art der Transformation prinzipiell beliebig.

Definition

{ export | reexport } { model } transformer { <Bezeichner> }
{
  [ <Attributdefinition> ]
  [ <Methodendefinition> ]
}

Zur Definition einer Transformation stehen dem IDM-Programmierer folgende Mittel zur Verfügung.

Eine Transformation wird durch den Aufruf der :apply() Methode eines Transformer-Objekts gestartet. Als Parameter werden hier die Quelle und das Ziel der Transformation übergeben (z.B.: ein Doccursor-Objekt als Quelle und ein IDM-Objekt als Ziel, das dann die Daten aufnehmen soll oder diese weiter delegiert).
Während jeder Transformation möchte man durch eine festgelegte Menge von Knoten, ob es IDM-Objekte oder Knoten eines XML-Baums sind, in einer bestimmten Reihenfolge durchlaufen. Die apply Methode realisiert einen solchen Durchlauf, indem sie ausgehend vom Startknoten (Quelle) in einer Schleife die :select_next() Methode des Transformers aufruft, die den Nachfolger des aktuellen Knotens bestimmt. Der Durchlauf wird beendet, sobald die :select_next() Methode null zurückliefert. Die Default-Implementierung der :select_next() Methode definiert eine Pre-Order-Reihenfolge. Der IDM-Programmierer kann in diesem Prozess an zwei Stellen eingreifen. Zum einen kann die apply Methode überdefiniert werden, um so den Startknoten festzulegen oder die Abbruchbedingung zu verändern. Zum anderen kann die :select_next() Methode überdefiniert werden und somit die gesamte Reihenfolge, in der die Knoten besucht werden.
Nachdem sichergestellt ist, dass jeder Knoten irgendwann besucht wird, muss es eine Möglichkeit geben um festzulegen, an welchen Knoten welche semantische(n) Aktion(en) ausgeführt wird (werden). Zu diesem Zweck werden am Transformer-Objekt Mapping-Objekte als Kinder definiert. Jedes dieser Objekte definiert in seinem Attribut .name ein Muster, das zur Entscheidung herangezogen wird, ob der gerade besuchte Knoten eine Aktion auslösen soll. Eine solche Aktion wird durch die action Methode des Mapping-Objekts festgelegt, die vom IDM-Programmierer überdefiniert wird. Diese Methode bekommt als ersten Parameter den gerade besuchten Knoten und als zweiten Parameter das Ziel-Objekt, das von der apply Methode des Transformers herrührt.
Um das Bild zu vervollständigen: Das Transformer-Objekt hat ebenfalls eine action Methode. Diese Methode wird in der oben erwähnten Schleife der apply Methode für jeden besuchten Knoten aufgerufen und untersucht dabei, ob ein Muster eines der Mapping-Kinder auf den Knoten passt. Die Reihenfolge, in der das passiert, entspricht der Definitionsreihenfolge der Mappings beim Vater-Transformer. Die geerbten Mapping-Objekte werden als letzte untersucht. Wird bei der Untersuchung ein erstes passendes Mapping-Objekt gefunden, so ruft die action Methode des Transformers die action Methode dieses Mapping-Objekts auf. Diese kann dann die Daten vom aktuellen Knoten zum Ziel-Objekt übertragen. Als Rückgabewert kann diese Methode ein true zurückliefen. In diesem Fall wird angenommen, dass der Knoten komplett abgearbeitet worden ist und keine weiteren Mapping-Objekte untersucht werden sollen. Anderenfalls werden die übrigen Mappings untersucht und gegebenenfalls deren action Methoden aufgerufen, bis entweder alle Mappings abgearbeitet worden sind oder die action Methode eines von diesen true zurückgeliefert hat.

Ereignisse

keine

Kinder

Vater

Menü

keins

Methoden

:action()

:apply()

:select_next()

5.1 Attribute

5.2 Objektspezifische Attribute

.mapping[integer]

Über das .mapping Attribut kann auf die Mapping-Kinder zugegriffen werden. Das Attribut wird mit dem Objektindex indiziert (ähnlich zu child). Die Reihenfolge der Mappings in diesem Vektor bestimmt die Reihenfolge, in der während einer Transformation ein Knoten mit einzelnen Mappings verglichen wird. Die vererbten Mappings werden in diesen Vektor nicht übernommen. Während einer Transformation wird mit solchen Mappings erst zum Schluss verglichen, die direkten Instanzen haben also Vorrang. Das ist anders, als bei anderen vererbten Kindobjekten im IDM, die im Kindvektor der Vaterinstanz vorne eingefügt werden.

.root

Nach dem Aufruf der apply Methode wird in diesem Attribut der Ausgangspunkt der Transformation gespeichert. Damit kann während einer Transformation entschieden werden, ob der Ausgangspunkt wieder erreicht worden ist und die Transformation beendet werden kann.

Dabei sind folgende Fallunterscheidungen zu beachten.

Ist der Src-Parameter der apply Methode ein Document- oder Doccursor-Objekt so wird in .root ein String abgespeichert, der die entsprechende Position im XML-Baum beschreibt. Die Syntax dieses Strings entspricht der Konvention, die im .path Attribut des Doccursor-Objekts verwendet wird (siehe Objektbeschreibung zu doccursor). Vergleiche mit dem .path Attribut von Doccursor sind deswegen besonders einfach.
Ist der Src-Parameter der apply Methode ein IDM-Objekt, so wird im .root dieses Objekt gespeichert. Folglich ist in diesem Fall der Typ dieses Attributs object.

Anhand des Wertes im .root Attribut entscheiden die action und :select_next() Methoden des Transformers, was diese tun müssen (siehe hierzu die Beschreibung dieser Methoden).

Am Ende der apply Methode wird .root wieder auf void gesetzt.

Default-Wert ist void.

5.3 Objektspezifische Methoden

:apply()

Mit dieser Methode wird die Transformation angestoßen. Die Default-Implementierung des Algorithmus sieht folgendermaßen aus:

Ist der Src-Parameter ein Document- oder Doccursor-Objekt, so wird angenommen, dass Daten aus einem XML-Baum zum IDM übertragen werden sollen. Im Falle eines Document-Objekts wird ein temporäres Doccursor-Objekt erzeugt, das zur Navigation im XML-Baum benutzt wird. Im folgenden Pseudocode wurde der Einfachheit halber angenommen, dass in Src immer ein Doccursor übergeben wird.
```
:apply(anyvalue Src, anyvalue Dest)
{
  variable object NextObj;
  
  this.root ::= Src.path;
  NextObj := Src;
  while NextObj <> null do
    this:action(Src, Dest);
    NextObj := this:select_next(NextObj);
  endwhile
  this.root ::= null;
  return true;
}
```
Ist der Src-Parameter ein IDM-Objekt (außer Document- oder Doccursor-Objekt), so wird angenommen, dass Daten vom IDM nach XML bzw. sonst wohin übertragen werden sollen. Der zugrundeliegende Code ist mit dem oben aufgeführten Codefragment identisch, außer das hier in .root nicht Src.path sondern Src selbst gespeichert wird. Also:
```
this.root ::= Src;
```

Die apply Methode kann überdefiniert werden (ähnlich zu :init()).

:action()

Diese Methode wird von der apply Methode des Transformers benutzt (siehe oben). Damit wird festgestellt, ob der aktuelle Knoten auf eines der Mapping-Kinder passt und deswegen die action Methode dieses Mapping-Objekts aufgerufen werden muss.

Die action Methode kann überdefiniert werden (ähnlich zu :init()).

:select_next()

Diese Methode wird von der apply Methode des Transformers zum Durchlaufen aller Knoten eines XML-Baums oder der IDM-Objekthierarchie benutzt. (siehe oben). Die Default-Implementierung dieser Methode sieht so aus, dass das wiederholte Aufrufen der Methode einen Pre-Order-Durchlauf realisiert.

Die :select_next() Methode kann überdefiniert werden (ähnlich zu :init()).

5.4 Beispiel

Dieses Beispiel ist im Verzeichnis examples/xml zu finden.

Als XML-Dokument dient folgende Datei mit dem Namen CD-Katalog.xml“:

<?xml version="1.0" ?>
<CATALOG>
  <CD>
    <TITLE>Empire Burlesque</TITLE>
    <ARTIST>Bob Dylan</ARTIST>
    <COUNTRY>USA</COUNTRY>
    <COMPANY>Columbia</COMPANY>
    <PRICE>10.90</PRICE>
    <YEAR>1985</YEAR>
  </CD>
  <CD>
    <TITLE>Hide your heart</TITLE>
    <ARTIST>Bonnie Tyler</ARTIST>
    <COUNTRY>UK</COUNTRY>
    <COMPANY>CBS Records</COMPANY>
    <PRICE>9.90</PRICE>
    <YEAR>1988</YEAR>
  </CD>
  <CD>
    <TITLE>Maggie May</TITLE>
    <ARTIST>Rod Stewart</ARTIST>
    <COUNTRY>UK</COUNTRY>
    <COMPANY>Pickwick</COMPANY>
    <PRICE>8.50</PRICE>
    <YEAR>1990</YEAR>
  </CD>
</CATALOG>

Dann können die Daten aus dieser Datei beispielsweise wie folgt ausgelesen werden.

dialog D {}

window Wi
{
  .title "XML-CD-CATALOG";

  on close { exit(); }

  child treeview Tv
  {
    .xauto 0;
    .yauto 0;
    .style[style_lines]   true;
    .style[style_buttons] true;
    .style[style_root]    true;
    integer CdIdx := 0;

    rule NewCatalog() {
      if this.itemcount = 0 then
        this.itemcount ::= this.itemcount + 1;
      endif
      this.content[this.itemcount] := "CD-Catalog";
      this.open[this.itemcount] := true;
    }

    rule AddCD() {
      this:insert(this.itemcount+1, 4);
      this.CdIdx := this.CdIdx + 1;
      this.content[this.itemcount-3] := ""+this.CdIdx+". CD";
      this.level[this.itemcount-3] := 2;
    }

    rule AddTitle(string S input) {
      this.content[this.itemcount-2] := "Title: " + S;
      this.level[this.itemcount-2] := 3;
    }

    rule AddArtist(string S input) {
      this.content[this.itemcount-1] := "Artist: " + S;
      this.level[this.itemcount-1] := 3;
    }

    rule AddPrice(string S input) {
      this.content[this.itemcount] := "Price: " + S;
      this.level[this.itemcount] := 3;
    }
  }
}

transformer Tr
{
  !! transformer ist zur Übernahme der Daten aus einem XML-Dokument gedacht
  !! in Src ist deswegen immer ein doccursor zu erwarten

  child mapping MCatalog {
    .name "..CATALOG";

    :action() {
      Dest:NewCatalog();
      return true;
    }
  }

  child mapping MCD {
    .name "..CD";

    :action() {
      Dest:AddCD();
      return true;
    }
  }

  child mapping MTitle {
    .name "..CD.TITLE";

    :action() {
      Dest:AddTitle(Src.text);
      return true;
    }
  }

  child mapping MArtist {
    .name "..CD.ARTIST";

    :action() {
      Dest:AddArtist(Src.text);
      return true;
    }
  }

  child mapping MPrice {
    .name "..CD.PRICE";

    :action() {
      Dest:AddPrice(Src.text);
      return true;
    }
  }
}

document Doc {}

on dialog start
{
  Doc:load("CD-Katalog.xml");

  Tv.visible := false;
  Tr:apply(Doc, Tv);
  Tv.visible := true;
}