XMLUmsetzungsknoten

Dieses Thema enthält folgende Abschnitte:

Zweck

Der XMLUmsetzungsknoten wird zur Umwandlung einer XML-Nachricht in ein anderes XML-Nachrichtenformat verwendet. Hierbei gelten die Regeln, die von einer XSL-Formatvorlage (XSL = eXtensible Stylesheet Language) bereitgestellt werden.

Sie haben drei Möglichkeiten für die Angabe der Adresse der Formatvorlage, die für diese Umwandlung verwendet werden soll:

  1. Sie können die Knoteneigenschaften verwenden. Auf diese Weise wird sichergestellt, dass die Umwandlung, die über diese einzelne Formatvorlage definiert wurde, auf jede Nachricht angewandt wird, die von diesem Knoten verarbeitet wird.
  2. Sie können den Inhalt der XML-Daten in der Nachricht selbst verwenden. Auf diese Weise wird die Nachricht gemäß einer Formatvorlage umgewandelt, die von der Nachricht selbst definiert wird. Dieses Verhalten gilt nur für XSL- und XML-Dateien, die sich in einem Nachrichtenflussprojekt befinden.
  3. Sie können in dem Ordner 'Lokale Umgebung' (LocalEnvironment), der der Nachricht zugeordnet ist, einen Wert festlegen. Auf diese Weise steht eine dynamische Formatvorlagenauswahl zur Verfügung, da Sie diesen Wert (in einem Rechenknoten) nach Erhalt der Nachricht innerhalb des Nachrichtenflusses festlegen müssen. Daher können Sie verschiedene Eingaben verwenden, um zu bestimmen, welche Formatvorlage für diese Nachricht verwendet werden soll - beispielsweise den Inhalt der Nachrichtendaten oder einen Wert in einer Datenbank.

Für die Umwandlung wird ein XSLT-Compiler (eXtensible Stylesheet Language for Transformations) verwendet, wenn die Formatvorlage Teil der Nachricht ist und der Wert für die Knotencachestufe (Knoteneigenschaft Cachestufe für Formatvorlage) größer als null ist.

Der XMLUmsetzungsknoten wird im Workbench durch folgendes Symbol dargestellt:

Symbol für den XMLUmsetzungsknoten

Diesen Knoten in einem Nachrichtenfluss verwenden

Zur Veranschaulichung der Verwendung dieses Knotens betrachten wir beispielsweise zwei Nachrichtenagenturen, die regelmäßig Informationen austauschen. Bei der einen Agentur könnte es sich um einen Fernsehsender, bei der anderen um eine Zeitung handeln. Die Informationen ähneln sich zwar, beide verwenden jedoch unterschiedliches Vokabular. Dieser Knoten kann ein Format in ein anderes umwandeln, indem er die Regeln der angegebenen Formatvorlage anwendet. Wenn Sie die Formatvorlage in der Nachricht angeben (entweder die XML-Daten oder die lokale Umgebung), kann derselbe Knoten beide Umwandlungen vornehmen.

Ausführliche Informationen zur Verwendung der XML-Umsetzungsknoten finden Sie im Beispielprogramm 'XMLT'.

XMLUmsetzungsknoten konfigurieren

Sobald Sie eine Instanz des XMLUmsetzungsknotens in einen Nachrichtenfluss eingereiht haben, können Sie diese konfigurieren. Klicken Sie in der Editoransicht mit der rechten Maustaste auf den Knoten, und klicken Sie auf Eigenschaften. Die Basiseigenschaften des Knotens werden angezeigt.

Alle obligatorischen Eigenschaften, für die ein Wert eingegeben werden muss (diejenigen, für die kein Standardwert definiert ist), sind im Eigenschaftendialog mit einem Stern markiert.

Konfigurieren Sie den XMLUmsetzungsknoten wie folgt:

  1. Wählen Sie die entsprechenden Werte für die Eigenschaften Auswahlpriorität in XML-Einbettung, Auswahlpriorität in Nachrichtenumgebung und Auswahlpriorität in Brokerknotenattribut aus. Mit den gesetzten Werten legen Sie fest, in welcher Reihenfolge die alternativen Positionen nach den Formatvorlageninformationen durchsucht werden. Die Einstellung für die höchste Priorität lautet 1. Es gilt folgende Standardreihenfolge:
    1. Auswahlpriorität in XML-Einbettung, folglich mit dem Standardwert 1. Der Knoten durchsucht die XML-Daten nach der Position der Formatvorlage. Die XML-Daten können beispielsweise Folgendes enthalten:
      <?xml-stylesheet type="text/xsl" href="foo.xsl"?>
    2. Auswahlpriorität in Nachrichtenumgebung, folglich mit dem Standardwert 2. Der Knoten durchsucht die der Nachricht zugeordnete LocalEnvironment-Baumstruktur nach den Informationen zur Formatvorlage, die im Element 'ComIbmXslXmltStylesheetname' gespeichert sind.

      Da dieser Knoten über ein SupportPac für Version 2.1 zur Verfügung gestellt wurde und das Element 'ComIbmXslMqsiStylesheetname' als Name der Formatvorlage verwendet wurde, überprüft der Knoten beide Elemente. Sind beide Elemente vorhanden, hat der Wert in 'ComIbmXslXmltStylesheetname' Vorrang.

    3. Auswahlpriorität in Brokerknotenattribut, folglich mit dem Standardwert 3. Der Knoten verwendet die Knoteneigenschaften Name der Formatvorlage und Verzeichnis der Formatvorlage zum Ermitteln der richtigen Werte.

    Obwohl für jede Eigenschaft mehr als ein Wert gesetzt werden kann, sollte dies unterlassen werden. Falls Sie sich dennoch dafür entscheiden, gilt die oben aufgeführte Prioritätenreihenfolge für den Knoten.

    Wird der Wert 'Ignorieren' gesetzt, durchsucht der Knoten die entsprechende Position nicht auf Informationen zur Formatvorlage. Werden alle drei Eigenschaften auf 'Ignorieren' gesetzt, wird ein Laufzeitfehler generiert.

  2. Soll die Formatvorlage über die Knoteneigenschaften definiert werden, geben Sie den entsprechenden Wert für Name der Formatvorlage ein. Werden die Formatvorlagen an der Position mit der höchsten Priorität gefunden (festgelegt über die zuvor gesetzten Prioritätswerte), wird dieser Wert ignoriert.

    Eine Principal-Formatvorlage können Sie auf zwei Arten angeben:
    1. Drücken Sie im Arbeitsbereich auf die Schaltfläche Durchsuchen, die sich beim Eigenschaftsfeld Name der Formatvorlage befindet. Die erkannten Principal-Formatvorlagen und alle zugehörigen untergeordneten Formatvorlagen mit relativem Verweis werden beim Hinzufügen eines Nachrichtenflusses zu einer BAR-Datei automatisch zu der BAR-Datei hinzugefügt (solange die Formatvorlagen und übergeordneten Formatvorlagen verfügbar sind).
    2. Für die Ermittlung einer bereits implementierten oder einer zu implementierenden Formatvorlage kann nur die Eigenschaft Name der Formatvorlage verwendet werden; die Eigenschaft Verzeichnis der Formatvorlage muss leer sein.
  3. Wurde die Position der Formatvorlage vollständig angegeben, wird die Eigenschaft Verzeichnis der Formatvorlage nicht berücksichtigt. Falls nicht, wird der Wert dieser Eigenschaft am Anfang der Spezifikation eingefügt, unabhängig davon, an welcher Stelle der Wert gefunden wurde.
  4. Geben Sie für die Eigenschaft Cachestufe für Formatvorlage die Anzahl der kompilierten oder syntaktisch analysierten Formatvorlagen ein, die in der Knoteninstanz gespeichert werden sollen. Standardwert ist 5. Der Formatvorlagencache bleibt über die gesamte Lebensdauer des Knotens erhalten. Der Cache wird erst gelöscht, wenn der Knoten aus dem Nachrichtenfluss entfernt, der Nachrichtenfluss gelöscht oder die Ausführungsgruppe gestoppt wird. Wird eine Formatvorlage geändert, hat die (zuletzt) geänderte Version Vorrang vor der zwischengespeicherten Version. Soll der Cache aktualisiert werden, verwenden Sie den Befehl mqsireload.
  5. Über die Eigenschaft 'Output Character Set' (Ausgabezeichensatz) im Eigenschaften-Dialognavigator legen Sie fest, in welcher Reihenfolge der Knoten nach gültigen Standorten mit den Zeichensätzen sucht, die für die Ausgabenachricht verwendet werden. Die Einstellung für die höchste Priorität lautet 1. Es gilt folgende Standardreihenfolge:
    1. Auswahlpriorität in Nachrichtenumgebung, folglich mit dem Standardwert 1. Der Knoten durchsucht die der Nachricht zugeordnete LocalEnvironment-Baumstruktur nach den Informationen zum Zeichensatz, die im Element 'ComIbmXslXmltOutputcharset' gespeichert sind.

      Beispiel: Geben Sie den Wert 1208 als Zeichenfolge für dieses Element an, wenn die Ausgabe der Umwandlung in UTF-8 codiert werden soll.

      Da dieser Knoten über ein SupportPac für Version 2.1 zur Verfügung gestellt wurde und das Element 'ComIbmXslMqsiOutputcharset' als Name für den Ausgabezeichensatz verwendet wurde, überprüft der Knoten beide Elemente. Sind beide Elemente vorhanden, hat der Wert in 'ComIbmXslXmltOutputcharset' Vorrang.

    2. Auswahlpriorität in Brokerknotenattribut, folglich mit dem Standardwert 2. Der Knoten ermittelt auf Grundlage der Eigenschaft Ausgabezeichensatz den korrekten Wert.

      Für Ausgabezeichensatz muss ein numerischer Wert festgelegt werden. Beispiel: Geben Sie den Wert 1200 ein, wenn die Ausgabe der Umwandlung in UTF-16 codiert werden soll.

    Obwohl für jede Eigenschaft mehr als ein Wert gesetzt werden kann, sollte dies unterlassen werden. Falls Sie sich dennoch dafür entscheiden, gilt die oben aufgeführte Prioritätenreihenfolge für den Knoten.

    Wird der Wert 0 gesetzt, durchsucht der Knoten die entsprechende Position nicht auf Informationen zum Zeichensatz.

    Kann der Knoten den Ausgabezeichensatz nicht auf Grundlage einer dieser Quellen ermitteln, weil entweder kein Wert gesetzt ist oder die Auswahlprioritäten auf 0 gesetzt sind, wird der Standardwert 1208 (UTF8) verwendet. (Die XSL-Spezifikation gibt an, dass der Ausgabezeichensatz in der Formatvorlage angegeben werden kann. Der XMLUmsetzungsknoten ignoriert diesen Wert jedoch.)

  6. Aktivieren Sie 'Detail-Trace' im Eigenschaften-Dialognavigator, falls Sie einen Trace der Aktionen des XMLUmsetzungsknotens erstellen möchten. Der Standardwert für die Eigenschaft Detail-Trace lautet Off. Zum Aktivieren des Trace setzen Sie die Eigenschaft auf On.

    Die Tracedaten werden in der Tracedatei XMLTTrace.log gespeichert:

    • Auf z/OS-Systemen befindet sich diese Datei unter <Brokerverzeichnis>/output; dabei ist <Brokerverzeichnis> das Verzeichnis, in dem der Broker installiert wurde.
    • Auf Windows-Systemen befindet sich die Datei im Verzeichnis <Broker-Arbeitspfad>\common\log.
    • Auf UNIX-Systemen befindet sich die Datei im Verzeichnis <Broker-Arbeitspfad>\common\log.

    Wird für einen XMLUmsetzungsknoten ausgewählt, dass ein ausführlicher Trace durchgeführt wird, wird dies für alle Knoten in derselben Ausführungsgruppe übernommen.

    Anmerkung: Diese Eigenschaft wird nicht mehr unterstützt. Jeder relevante Trace wird in den Benutzertrace verschoben, vorausgesetzt, der Debug-Benutzertrace ist aktiviert. Die Einstellung von Detail-Trace im XMLUmsetzungsknoten wirkt sich nicht auf Benutzertraces aus.
  7. Wählen Sie im Eigenschaften-Dialognavigator die Option "Beschreibung" aus, um eine kurze und/oder ausführliche Beschreibung einzugeben.
  8. Klicken Sie auf Übernehmen, um die Änderungen am XMLUmsetzungsknoten vorzunehmen, ohne das Dialogfeld mit den Eigenschaften zu schließen. Klicken Sie auf OK, um die Änderungen zu übernehmen und das Dialogfeld mit den Eigenschaften zu schließen.

    Klicken Sie auf Abbrechen, um das Dialogfeld zu schließen und alle Änderungen zu verwerfen, die Sie an den Eigenschaften vorgenommen haben.

Wird im Zusammenhang mit großen XML-Nachrichten der Fehler generiert, dass nicht mehr genügend Speicher vorhanden ist, kann mit Hilfe des Befehls mqsireportproperties der aktuelle Wert des Java-Heapspeicher für die XSLT-Steuerkomponente angezeigt und mit dem Befehl mqsichangeproperties vergrößert werden:
mqsireportproperties Brokername -e Kennung_der_Ausführungsgruppe -o ComIbmJVMManager -n jvmMaxHeapSize
mqsichangeproperties Brokername -e Kennung_der_Ausführungsgruppe -o ComIbmJVMManager -n jvmMaxHeapSize -v Neue_Größe
Ersetzen Sie Brokername, Kennung_der_Ausführungsgruppe und Neue_Größe durch die entsprechenden Werte.

Der Wert für Neue_Größe richtet sich nach der physischen Hauptspeichermenge Ihres Computers sowie danach, wie häufig Sie Java verwenden. Empfohlen wird ein Wert zwischen 512 MB und 1 GB.

Terminals und Eigenschaften

In der nachfolgenden Tabelle werden die Terminals des XMLUmsetzungsknotens beschrieben.

Terminal Beschreibung:
Eingangsterminal Das Eingangsterminal, das die Nachricht zur Verarbeitung durch einen Knoten annimmt.
Failure Das Ausgabeterminal, an das die Originalnachricht weitergeleitet wird, wenn während der Umwandlung ein Fehler auftritt.
Out Das Ausgabeterminal, an das eine erfolgreich umgewandelte Nachricht weitergeleitet wird.

In der nachfolgenden Tabelle werden die Knoteneigenschaften beschrieben. Die Spalte M zeigt an, ob die Eigenschaft obligatorisch ist (markiert mit einem Sternchen im Eigenschaftendialog, ob Sie einen Wert eingeben müssen, wenn kein Standardwert definiert ist). Die Spalte C zeigt an, ob die Eigenschaft konfigurierbar ist (Sie können den Wert ändern, wenn Sie der BAR-Datei den Nachrichtenfluss hinzufügen, um ihn einzusetzen).

In der nachfolgenden Tabelle werden die Formatvorlageneigenschaften des XMLUmsetzungsknotens beschrieben.

Eigenschaft M C Standardwert Beschreibung:
Auswahlpriorität in XML-Einbettung Ja Nein 1 Die Prioritätsstufe zum Suchen der Formatvorlage in den XML-Daten.
Auswahlpriorität in Nachrichtenumgebung Ja Nein 2 Die Priorität zum Suchen der Formatvorlage in der LocalEnvironment-Baumstruktur der aktuellen Nachricht.
Auswahlpriorität in Brokerknotenattribut Ja Nein 3 Die Priorität zum Suchen der Formatvorlage als Eigenschaft des Knotens.
Name der Formatvorlage Nein Ja   Der Name der Formatvorlage; wird beim Suchen der Spezifikation für die Formatvorlage in den Knoteneigenschaften verwendet.
Verzeichnis der Formatvorlage Nein Ja   Der Pfad der Formatvorlage. Wird bei allen Methoden zum Bestimmen der Position verwendet.
Cachestufe für Formatvorlage Nein Nein 5 Die Anzahl der kompilierten oder syntaktisch analysierten Formatvorlagen, die in der Knoteninstanz gespeichert werden sollen.

In der nachfolgenden Tabelle werden die Ausgabezeichensatzeigenschaften des XMLUmsetzungsknotens beschrieben.

Eigenschaft M C Standardwert Beschreibung:
Auswahlpriorität in Nachrichtenumgebung Ja Nein 1 Die Priorität zum Suchen der Ausgabezeichensatz-ID in der LocalEnvironment-Baumstruktur der aktuellen Nachricht.
Auswahlpriorität in Brokerknotenattribut Ja Nein 2 Die Priorität zum Suchen der Ausgabezeichensatz-ID als Eigenschaft des Knotens.
Ausgabezeichensatz Nein Nein   Der numerische Wert für den Ausgabezeichensatz.

In der nachfolgenden Tabelle werden die Detail-Trace-Eigenschaften des XMLUmsetzungsknotens beschrieben.

Eigenschaft M C Standardwert Beschreibung:
Trace-Einstellung Ja Nein Off Gibt an, ob die Tracefunktion aktiv ist. Ist sie aktiv, werden Tracedaten mit niedriger Detailtiefe in einer Datei gespeichert.

In der nachfolgenden Tabelle werden die Beschreibungseigenschaften des XMLUmsetzungsknotens beschrieben.

Eigenschaft M C Standardwert Beschreibung:
Kurzbeschreibung Nein Nein   Kurze Beschreibung des Knotens
Ausführliche Beschreibung Nein Nein   Text, der den Zweck des Knotens im Nachrichtenfluss beschreibt

Beginn der ÄnderungWenn zu Beginn des Hauptteils der Eingabenachricht eine XML-Codierungsdeklaration enthalten ist, wird diese Codierung vom XMLUmsetzungsknoten ignoriert und für die Decodierung der Nachricht immer die CodedCharSetId im Eigenschaftenordner verwendet. Ende der Änderung

Implementierung von implementierten Formatvorlagen oder XML-Dateien

Gehen Sie zur Verwendung von implementierten Formatvorlagen oder XML-Dateien folgendermaßen vor:
  1. Stellen Sie sicher, dass Sie die richtigen Dateinamenerweiterungen verwenden: Für die Implementierung von Formatvorlagen ist die Dateierweiterung '.xsl' oder '.xslt' und für XML-Dateien '.xml' erforderlich.
  2. Importieren Sie die Dateien in den Eclipse-Arbeitsbereich: Alle Formatvorlagen und XML-Dateien, die implementiert werden sollen, müssen in das Projekt eines Eclipse-Arbeitsbereichs importiert werden. Standortabhängige untergeordnete Formatvorlagen oder XML-Dateien, die implementiert werden sollen, müssen in die richtige Verzeichnisstruktur geschrieben werden, die relativ zu den zugehörigen übergeordneten Formatvorlagen ist. Im Eclipse-Arbeitsbereich sollten sich keine standortabhängigen untergeordneten Formatvorlagen befinden, die nicht implementiert werden sollen.
  3. Stellen Sie sicher, dass alle Verweise auf die Dateien relativ sind: Bei allen Verweisen auf eine Principal-Formatvorlage, die in der lokalen Umgebung eines Nachrichtenflusses, in einem XML-Eingabedokument, in der Eigenschaft Name der Formatvorlage des XMLUmsetzungsknotens oder in einer übergeordneten Formatvorlage vorkommen kann, muss es sich um einen relativen Verweis handeln. Ein Verweis auf eine Principal-Formatvorlage sollte relativ zu dem Stammverzeichnis des relevanten Projekts des Eclipse-Arbeitsbereichs sein. Beispielsweise muss ein Verweis auf eine Principal-Formatvorlage im Eclipse-Arbeitsbereich 'C:\\Projekt1\a\b.xsl' als 'a/b.xsl' (oder './a/b.xsl') angegeben werden. Ausnahme: Bei der Angabe einer Principal-Formatvorlage als Eigenschaft Name der Formatvorlage in einem XMLUmsetzungsknoten können Sie auch einen absoluten Pfad verwenden, der auf die richtige Verzeichnisstruktur im Eclipse-Arbeitsbereich verweist. Wenn die Principal-Formatvorlage gefunden wurde, setzt das System die Knoteneigenschaft automatisch auf den richtigen relativen Wert (und führt eine automatische Implementierung der Principal-Formatvorlagen und der standortabhängigen untergeordneten Formatvorlagen aus, die im relevanten Eclipse-Arbeitsbereichsprojekt verfügbar sind). Alle Verweise auf standortabhängige untergeordnete Formatvorlagen (oder XML-Dateien) einer Principal-Formatvorlage müssen relativ zum Standort der zugehörigen übergeordneten Formatvorlagen sein. Wenn beispielsweise die Formatvorlage '//Projekt1/a/b.xsl' auf die Formatvorlage '//Projekt1/a/c/d.xsl' verweist, muss der Verweis zu 'c/d.xsl' (oder './c/d.xsl') geändert werden.
  4. Bearbeitung von nicht implementierten untergeordneten Formatvorlagen oder XML-Dateien: Wenn Sie eine Formatvorlage (oder XML-Datei) mit einem relativen Verweis haben, die nicht implementiert werden soll, deren übergeordnetes Element jedoch implementiert werden soll, müssen Sie sicherstellen, dass sie an die richtige Position unter '/XSL/external' ('/XML/external') gestellt wird. Ein Broker ordnet die in der Ausführungsgruppe implementierte Speicherbaumstruktur sowie die Baumstrukturen '/XSL/external' und '/XML/external' einander automatisch zu. Wenn also beispielseise 'b/c.xml' im implementierten Speicher des Brokers nicht gefunden wird, führt der Broker im Verzeichnis '/XML/external/a/b' automatisch eine Suche nach einem Verweis auf das Dokument ('b/c.xml') in der implementierten Principal-Formatvorlage 'a/style.xsl' durch. Relative Pfadverweise müssen auch für Dateien verwendet werden, die bereits implementiert wurden, die im Arbeitsbereich aber noch nicht verfügbar sind.
  5. Dateien implementieren: Es müssen nur Formatvorlagen oder XML-Dateien manuell implementiert werden, die vom System noch nicht berücksichtigt wurden (durch die Tools werden Warnungen zu diesen Dateien ausgegeben). Fügen Sie die Dateien bei der manuellen Implementierung zu einem Brokerarchiv hinzu (siehe Einem Brokerarchiv Dateien hinzufügen und Schlüsselwörter zu XSL-Formatvorlagen hinzufügen), um implementieren Sie das Brokerarchiv. Eine Formatvorlage oder XML-Datei muss für alle Nachrichtenflüsse der gleichen Ausführungsgruppe nur einmal und für jede Ausführungsgruppe mindestens einmal implementiert werden. Es ist nicht erforderlich, Formatvorlagen oder XML-Dateien in der BAR-Datei zu implementieren, die Nachrichtenflüsse mit Verweisen auf die Formatvorlagen oder XML-Dateien enthält. Für die Formatvorlagen und XML-Dateien in einer BAR-Datei sind außerdem keine Verweise durch Nachrichtenflüsse erforderlich. Bei der Speicherung eines Nachrichtenflusses in einer BAR-Datei wird jedoch eine Warnung ausgegeben, wenn sich in dieser BAR-Datei keine untergeordneten Formatvorlagen oder XML-Dateien befinden. Sie müssen daher sicherstellen, dass diese untergeordneten Formatvorlagen oder XML-Dateien auf dem Broker verfügbar sind. Ein Broker berücksichtigt keine Eclipse-Projekte. Deshalb kann eine implementierte Formatvorlage, die zu einem Projekt gehört, von einer anderen Formatvorlage überschrieben werden, wenn beide über den gleichen Verzeichnispfad und Dateinamen verfügen, selbst wenn sie zu verschiedenen Projekten gehören. Durch eine Implementierung werden ohne Warnung alle vorhandenen älteren Versionen der Dateien, die implementiert werden, überschrieben. Dies gilt auch für automatisch implementierte Formatvorlagen.
Bemerkungen | Marken | Downloads | Bibliothek | Unterstützung | Rückmeldung
Copyright IBM Corporation 1999, 2006 Letzte Aktualisierung: 18.05.2006
ac12490_