Nachrichtenverarbeitungs- oder Sendeknoten in Java erstellen

Vorbereitungen

WebSphere Message Broker stellt die Quelle für die zwei benutzerdefinierten Beispielknoten 'Umschaltungsknoten' und 'TransformNode' bereit. Diese Knoten können in ihrem aktuellen Zustand verwendet oder von Ihnen angepasst werden.

Konzeptionell wird ein Nachrichtenverarbeitungsknoten zur Verarbeitung einer Nachricht und ein Sendeknoten zur Ausgabe einer Nachricht als Bitstrom verwendet. Beim Codieren eines Nachrichtenverarbeitungsknotens und eines Sendeknotens handelt es sich jedoch um das Gleiche. Sie können an einem Sendeknoten Nachrichten verarbeiten, und ebenso können Sie mit einem Nachrichtenverarbeitungsknoten eine Nachricht als Bitstrom ausgeben. Zur Vereinfachung wird in diesem Abschnitt von einem Nachrichtenverarbeitungsknoten gesprochen, auch wenn die Funktionen beider Knotentypen erläutert werden.

Neues Java-Projekt erstellen

Java-Knoten können Sie in der Workbench erstellen. Gehen Sie für die Erstellung des dazu erforderlichen neuen Java-Projekts folgendermaßen vor:
  1. Wechseln Sie zur Java-Perspektive.
  2. Klicken Sie Datei > Neu > Projekt. Wählen Sie im linken Menü Java aus, und wählen Sie anschließend im rechten Menü Java Project (Java-Projekt) aus.
  3. Benennen Sie das Projekt.

    Die Anzeige 'Java Settings' (Java-Einstellungen) erscheint.

  4. Wählen Sie die Registerkarte 'Libraries' (Bibliotheken) aus, und klicken Sie auf Add External JARs (Externe JARs hinzufügen).
  5. Wählen Sie Installationsverzeichnis\classes\jplugin2.jar aus.
  6. Folgen Sie den Eingabeaufforderungen in den anderen Registerkarten, um weitere Build-Einstellungen zu definieren.
  7. Klicken Sie auf Fertig stellen.
Sie können anschließend die Quelle für Ihren Java-Knoten in diesem Projekt entwickeln.

Klasse des Nachrichtenverarbeitungsknotens deklarieren

Jede Klasse, durch die MbNodeInterface implementiert wird und im LIL-Pfad des Brokers enthalten ist, wird im Broker als Nachrichtenverarbeitungsknoten registriert. Bei der Implementierung von MbNodeInterface, muss auch eine evaluate-Methode für diese Klasse implementiert werden. Die evaluate-Methode wird vom Broker für jede Nachricht aufgerufen, die durch den Fluss übermittelt wird.

Wenn Sie beispielsweise die Klasse des Nachrichtenverarbeitungsknotens deklarieren möchten, gehen Sie folgendermaßen vor:
package com.ibm.jplugins;

import com.ibm.broker.plugin.*;

public class BasicNode extends MbNode implements MbNodeInterface
In der Workbench können Sie dazu folgende Schritte ausführen:
  1. Klicken Sie auf Datei > Neu > Klasse.
  2. Legen Sie für die Namensfelder des Pakets und der Klasse die entsprechenden Werte fest.
  3. Löschen Sie den Text im Textfeld 'Superclass' (Superklasse), und klicken Sie auf die Schaltfläche Durchsuchen.
  4. Wählen Sie die Klasse 'MbNode' aus, und klicken Sie auf OK.
  5. Klicken Sie neben dem Textfeld 'Interface' (Schnittstelle) auf die Schaltfläche Hinzufügen, und wählen Sie MbNodeInterface aus.
  6. Klicken Sie auf Fertig stellen.

Knotenkonstruktor definieren

Wenn eine Instanz des Knotens erstellt wird, wird der Konstruktor der Knotenklasse des Benutzers aufgerufen. Dabei können Sie die Knotenterminals erstellen und Standardwerte für die Attribute initialisieren.

Einem Nachrichtenverarbeitungsknoten sind eine Reihe von Eingabeterminals und Ausgabeterminals zugeordnet. Die Methoden createInputTerminal und createOutputTerminal werden verwendet, um einem Knoten Terminals hinzuzufügen, wenn eine Instanz des Knotens erstellt wird. Im Folgenden finden Sie ein Beispiel für die Erstellung eines Knotens mit einem Eingabeterminal und zwei Ausgabeterminals:

public MyNode() throws MbException
{
		// create terminals here
		createInputTerminal ("in");
		createOutputTerminal ("out");
		createOutputTerminal ("failure");
}

Auf Nachrichtendaten zugreifen

In vielen Fällen muss der benutzerdefinierte Knoten auf den Inhalt der Nachricht zugreifen, die an seinem Eingabeterminal empfangen wurde. Die Nachricht wird als Baumstruktur aus Syntaxelementen dargestellt. Gruppen von Dienstprogrammfunktionen werden zur Verwendung in der evaluate-Methode bereitgestellt. Sie werden für Nachrichtenmanagement, Zugriff auf Nachrichtenpuffer sowie für Navigation der Syntaxelemente und Zugriff darauf bereitgestellt.

Die Klasse MbElement bildet die Schnittstelle zu den Syntaxelementen. Weitere Informationen zur Java-API finden Sie in der Javadoc.

Beispiel:

  1. So navigieren Sie zum relevanten Syntaxelement in der XML-Nachricht:
        MbElement rootElement = assembly.getMessage().getRootElement();
        MbElement switchElement = 
    			rootElement.getLastChild().getFirstChild().getFirstChild();
  2. So wählen Sie das Terminal aus, das durch den Wert dieses Elements angegeben wird:
        String terminalName;
        String elementValue = (String)switchElement.getValue();
        if(elementValue.equals("add"))
          terminalName = "add";
        else if(elementValue.equals("change"))
          terminalName = "change";
        else if(elementValue.equals("delete"))
          terminalName = "delete";
        else if(elementValue.equals("hold"))
          terminalName = "hold";
        else
          terminalName = "failure";
        
        MbOutputTerminal out = getOutputTerminal(terminalName);

Nachrichtenobjekt umwandeln

Die empfangene Eingabenachricht ist schreibgeschützt. Vor dem Umwandeln einer Nachricht müssen Sie diese deshalb in eine neue Ausgabenachricht schreiben. Es können Elemente aus der Eingabenachricht kopiert werden, oder es können neue Elemente in der Ausgabenachricht erstellt werden. Die neuen Elemente befinden sich normalerweise in der Domäne des Parsers.

Durch die Klasse MbMessage werden die Copy-Konstruktoren und die Methoden zum Abrufen des Stammelements der Nachricht bereitgestellt. Durch die Klasse MbElement wird die Schnittstelle für die Syntaxelemente bereitgestellt.

Beispiel: Bei einer ankommenden Nachrichtenassembly mit eingebetteten Nachrichten, kann in der evaluate-Methode Ihres benutzerdefinierten Knotens folgender Code vorhanden sein:
  1. So erstellen Sie eine neue Kopie der Nachrichtenassembly und der zugehörigen eingebetteten Nachrichten:
        MbMessage newMsg = new MbMessage(assembly.getMessage());
        MbMessageAssembly newAssembly = new MbMessageAssembly(assembly, newMsg);
  2. So navigieren Sie zum relevanten Syntaxelement in der XML-Nachricht:
        MbElement rootElement = newAssembly.getMessage().getRootElement();
        MbElement switchElement = 
    			rootElement.getFirstElementByPath("/XML/data/action");
  3. So ändern Sie den Wert eines vorhandenen Elements:
      String elementValue = (String)switchElement.getValue();
        if(elementValue.equals("add"))
          switchElement.setValue("change");
        else if(elementValue.equals("change"))
          switchElement.setValue("delete");
        else if(elementValue.equals("delete"))
          switchElement.setValue("hold");
        else
          switchElement.setValue("failure");
  4. So fügen Sie eine neue Kennung als untergeordnetes Element der Switch-Kennung hinzu:
        MbElement tag = switchElement.createElementAsLastChild(MbElement.TYPE_NAME,
                                                               "PreviousValue",
                                                               elementValue);
  5. So fügen Sie dieser neuen Kennung ein Attribut hinzu:
        tag.createElementAsFirstChild(MbElement.TYPE_NAME_VALUE,
                                      "NewValue",
                                      switchElement.getValue());
    
        MbOutputTerminal out = getOutputTerminal("out");
Als Teil der Umsetzung kann es erforderlich sein, einen neuen Nachrichtenhauptteil zu erstellen. Zum Erstellen eines neuen Nachrichtenhauptteils sind folgende Methoden verfügbar:
createElementAfter(String)
createElementAsFirstChild(String)
createElementAsLastChild(String)
createElementBefore(String)
createElementAsLastChildFromBitstream(byte[], String, String, String, String, int, int, int)
Diese Methoden sollten verwendet werden, weil sie speziell für das Zuweisen eines Parsers zu einer Nachrichtenbaumstruktur vorgesehen sind.
Beim Erstellen eines Nachrichtenhauptteils dürfen folgende Methoden nicht verwendet werden, weil sie dem Ordner keinen Parser als Eigner zuordnen:
createElementAfter(int)
createElementAfter(int, String, Object)
createElementAsFirstChild(int)
createElementAsFirstChild(int, String, Object)
createElementAsLastChild(int)
createElementAsLastChild(int, String, Object)
createElementBefore(int)
createElementBefore(int, String, Object)

Nachricht weitergeben

Vor dem Weitergeben einer Nachricht müssen Sie entscheiden, welche Nachrichtenflussdaten weitergegeben werden und welches Knotenterminal die Daten empfangen soll.

Beispiel:
  1. Gehen Sie folgendermaßen vor, um die Nachricht an das Ausgabeterminal 'out' weiterzugeben:
    MbOutputTerminal out = getOutputTerminal("out");
            out.propagate(newAssembly);

Rufen Sie zum Löschen des Speichers, der der Nachrichtenbaumstruktur zugeordnet ist, die clearMessage()-Funktion innerhalb des letzten Try-/Catch-Blocks auf.

Knotennamen deklarieren

Der Knotennamen muss so deklariert werden, wie er von der Workbench gekennzeichnet wird. Alle Knotennamen müssen die Endung "Node" haben. Deklarieren Sie die Namen mit der folgenden Methode:

public static String getNodeName()
{
   return "BasicNode";
}
Wenn diese Methode nicht deklariert ist, erstellt das Framework der Java-API einen standardmäßigen Knotennamen nach folgenden Regeln:
  • Der Klassenname wird an den Paketnamen angehängt.
  • Die Punkte werden entfernt, und der erste Buchstabe von jedem Teil des Paket- und Klassenamens wird in Großbuchstaben gesetzt.
Beispiel: Standardmäßig wird folgender Klasse der Knotenname "ComIbmPluginsamplesBasicNode" zugewiesen:
package com.ibm.pluginsamples;
public class BasicNode extends MbNode implements MbNodeInterface
{
   ...

Attribute deklarieren

Knotenattribute werden auf die gleiche Weise deklariert wie Eigenschaften von JavaBeans. Die Methoden GET und SET müssen für die Attribute geschrieben werden, und das API-Framework schließt aus den Regeln für die JavaBean-Introspektion auf die Attributnamen. Sie können beispielsweise die folgenden zwei Methoden deklarieren:

private String attributeVariable;

public String getFirstAttribute()
{
  return attributeVariable;
}

publc void setFirstAttribute(String value)
{
  attributeVariable = value;
}

Der Broker schließt daraus, dass in diesem Knoten ein Attribut mit der Bezeichnung 'firstAttribute' enthalten ist. Dieser Name wird von den Namen der Methoden zum Abrufen und Festlegen abgeleitet, und nicht von den Variablennamen von Mitgliedern interner Klassen. Attribute können nur als Zeichenfolgen festgelegt werden. Deshalb müssen numerische Werte in den Methoden zum Abrufen und Festlegen in Zeichenfolgen umgewandelt werden. In der folgenden Methode wird beispielsweise ein Attribut mit der Bezeichnung 'timeInSeconds' definiert:

int seconds;

public String getTimeInSeconds()
{
  return Integer.toString(seconds);
}

public void setTimeInSeconds(String value)
{
  seconds = Integer.parseInt(value);
}

Knotenfunktionen implementieren

Wie bereits für die Nachrichtenverarbeitung oder für Sendeknoten beschrieben, müssen Sie die Methode evaluate implementieren, die in MbNodeInterface definiert ist. Diese Methode wird vom Broker zur Verarbeitung der Nachricht aufgerufen. Durch diese Methode wird die erforderliche Verarbeitungsfunktion für den Knoten bereitgestellt.

Die Methode evaluate enthält zwei Parameter, die durch den Broker übermittelt werden:
  1. In MbMessageAssembly sind die folgenden Objekte enthalten, auf die mit den entsprechenden Methoden zugegriffen werden kann:
    • Ankommende Nachricht
    • Lokale Umgebung
    • Globale Umgebung
    • Ausnahmeliste
  2. Eingabeterminal, auf dem die Nachricht angekommen ist.
Im folgenden Codeauszug können Sie beispielsweise sehen, wie die evaluate-Methode geschrieben werden kann:
public void evaluate(MbMessageAssembly assembly, MbInputTerminal inTerm) throws MbException
  {
    // add message processing code here

    getOutputTerminal("out").propagate(assembly);
  }

Die Nachrichtenflussdaten, die aus der Nachricht, der globalen Umgebung, der lokalen Umgebung und der Ausnahmeliste bestehen, werden am Eingabeterminal des Knotens empfangen.

Knoteninstanz löschen

Eine Knoteninstanz wird durch folgende Aktionen gelöscht:
  • Beenden des Brokers.
  • Entfernen des Knotens oder des Nachrichtenflusses, in dem der Knoten enthalten ist, und erneutes Einsetzen der Konfiguration.
Beim Löschen muss der Knoten möglicherweise unterrichtet werden, damit Vorgänge zur Bereinigung, wie beispielsweise das Schließen von Sockets, ausgeführt werden können. Wenn durch den Knoten die optionale Methode onDelete implementiert wird, wird diese Aktion durch den Broker direkt vor dem Löschen des Knotens aufgerufen.

Implementieren Sie die Methode onDelete folgendermaßen:

public void onDelete()
{
  // perform node cleanup if necessary
}
Zugehörige Verweise
Struktur der Ausnahmeliste
Zugehörige Informationen
Benutzerdefinierte Java-Knoten-API
Bemerkungen | Marken | Downloads | Bibliothek | Unterstützung | Rückmeldung
Copyright IBM Corporation 1999, 2006 Letzte Aktualisierung: 23. Aug. 2006
as09970_