Nachrichtenverarbeitungs- oder Sendeknoten in Java erstellen

Vorbereitungen

WebSphere Message Broker stellt die Quelle für die zwei benutzerdefinierten Beispielknoten 'Umschaltungsknoten' und 'TransformNode' bereit. Sie können diese Knoten in ihrem aktuellen Zustand verwenden, oder Sie können sie ändern.

Konzeptionell wird ein Nachrichtenverarbeitungsknoten zur Verarbeitung einer Nachricht und ein Sendeknoten zur Ausgabe einer Nachricht als Bitstrom verwendet. Wenn Sie jedoch einen Nachrichtenverarbeitungsknoten oder einen Sendeknoten codieren, sind sie im Wesentlichen identisch. Sie können an einem Sendeknoten Nachrichten verarbeiten, und ebenso können Sie mit einem Nachrichtenverarbeitungsknoten eine Nachricht als Bitstrom ausgeben. Der Einfachheit halber wird der Knoten in diesem Abschnitt hauptsächlich als Nachrichtenverarbeitungsknoten bezeichnet, es werden jedoch die Funktionen beider Knotentypen beschrieben.

Neues Java-Projekt erstellen

Java-Knoten können Sie in der Workbench erstellen. Dazu müssen Sie wie folgt vorgehen, um ein neues Java-Projekt zu erstellen:
  1. Wechseln Sie zur Java-Perspektive.
  2. Klicken Sie Datei > Neu > Projekt. Wählen Sie aus dem linken Menü Java aus, und wählen Sie anschließend aus dem rechten Menü Java-Projekt aus.
  3. Geben Sie dem Projekt einen Namen.

    Das Fenster 'Java Settings' (Java-Einstellungen) wird angezeigt.

  4. Wählen Sie die Registerkarte 'Libraries' (Bibliotheken) aus, und klicken Sie auf Add External JARs (Externe JAR-Dateien hinzufügen).
  5. Wählen Sie Installationsverzeichnis\classes\jplugin2.jar aus.
  6. Befolgen Sie die Eingabeaufforderungen auf den anderen Registerkarten, um andere Einstellungen für die Erstellung zu definieren.
  7. Klicken Sie auf Fertig stellen.
Anschließend können Sie 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 Methode evaluate wird vom Broker für jede Nachricht aufgerufen, die den Nachrichtenfluss durchläuft.

Im Folgenden finden Sie ein Beispiel für die Deklaration der Klasse des Nachrichtenverarbeitungsknotens:
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 in den Paket- und Klassennamenfeldern 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. Hier erstellen Sie die Terminals des Knotens und initialisieren Standardwerte für Attribute.

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 Beginn der ÄnderungevaluateEnde der Änderung-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, deshalb müssen Sie sie in eine neue Ausgabenachricht schreiben, bevor sie umgewandelt werden kann. Beginn der ÄnderungEs können Elemente aus der Eingabenachricht kopiert werden, oder es können neue Elemente in der Ausgabenachricht erstellt werden. Ende der Änderung Neue Elemente befinden sich im Allgemeinen in der Domäne eines Parsers.

Die Klasse MbMessage stellt die Kopierkonstruktoren und Methoden bereit, um das Stammelement der Nachricht abzurufen. Die Klasse MbElement bildet die Schnittstelle zu den Syntaxelementen.

Beispiel: Bei einer ankommenden Nachrichtenassembly mit eingebetteten Nachrichten, kann in der Beginn der ÄnderungevaluateEnde der Änderung-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: Beginn der Änderung
createElementAfter(String)
createElementAsFirstChild(String)
createElementAsLastChild(String)
createElementBefore(String)
createElementAsLastChildFromBitstream(byte[], String, String, String, String, int, int, int)
Ende der Änderung 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: Beginn der Änderung
createElementAfter(int)
createElementAfter(int, String, Object)
createElementAsFirstChild(int)
createElementAsFirstChild(int, String, Object)
createElementAsLastChild(int)
createElementAsLastChild(int, String, Object)
createElementBefore(int)
createElementBefore(int, String, Object)
Ende der Änderung

Nachricht weitergeben

Bevor Sie eine Nachricht weitergeben, müssen Sie entscheiden, welche Nachrichtenflussdaten Sie weitergeben möchten und welches Terminal des Knotens die Daten empfangen soll.

Beispiel:
  1. So geben Sie die Nachricht an das Ausgabeterminal "out" weiter:
    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

Sie müssen den Namen des Knotens deklarieren, da er von der Workbench identifiziert wird. Alle Knotennamen müssen mit "Node" enden. Sie deklarieren den Namen mit der folgenden Methode:

public static String getNodeName()
{
return "BasicNode";
}
Wenn diese Methode nicht deklariert wird, erstellt das Java-API-Framework einen Standardknotennamen gemäß den folgenden Regeln:
  • Der Klassenname wird an den Paketnamen angehängt.
  • Die Punkte werden entfernt, und der erste Buchstabe jedes Teils des Paket- und Klassennamens wird großgeschrieben.
Der folgenden Klasse wird beispielsweise standardmäßig der Knotenname "ComIbmPluginsamplesBasicNode" zugeordnet:
package com.ibm.pluginsamples;
public class BasicNode extends MbNode implements MbNodeInterface
{
...

Attribute deklarieren

Knotenattribute deklarieren Sie genauso wie Java-Bean-Eigenschaften. Sie müssen Getter- und Setter-Methoden für die Attribute schreiben, und das API-Framework leitet davon die Attributnamen mit Hilfe der Java-Bean-Introspektionsregeln ab. Wenn Sie beispielsweise die folgenden beiden Methoden deklarieren:

private String attributeVariable;
public String getFirstAttribute()
{
return attributeVariable;
}
publc void setFirstAttribute(String value)
{
attributeVariable = value;
}

Dann folgert der Broker daraus, dass dieser Knoten über ein Attribut mit dem Namen 'firstAttribute' verfügt. Dieser Name wird von den Namen der get- oder set-Methoden abgeleitet, nicht von internen Klassenmitgliedsvariablennamen. Attribute können nur als Zeichenfolgen angezeigt werden, deshalb müssen Sie numerische Typen in den get- oder set-Methoden in bzw. aus Zeichenfolgen konvertieren. Die folgende Methode definiert beispielsweise ein Attribut mit dem Namen 'timeInSeconds':

int seconds;
public String getTimeInSeconds()
{
return Integer.toString(seconds);
}
public void setTimeInSeconds(String value)
{
seconds = Integer.parseInt(value);
}

Knotenfunktionen implementieren

Wie im Vorigen beschrieben müssen Sie für Nachrichtenverarbeitungs- oder Sendeknoten die Methode evaluate implementieren, die in MbNodeInterface definiert ist. Diese Methode wird vom Broker für die Verarbeitung der Nachricht aufgerufen. Sie sollte alle Verarbeitungsfunktionen für den Knoten bereitstellen.

Die Methode evaluate verfügt über zwei Parameter, die vom Broker übergeben werden:
  1. Den Parameter MbMessageAssembly, der die folgenden Objekte enthält, auf die mit den entsprechenden Methoden zugegriffen wird:
    • Die ankommende Nachricht
    • Die lokale Umgebung
    • Die globale Umgebung
    • Die Ausnahmeliste
  2. Das Eingabeterminal, auf dem die Nachricht eingegangen ist.
Im folgenden Codeauszug können Sie beispielsweise sehen, wie die evaluate-Methode geschrieben werden kann: Beginn der Änderung
public void evaluate(MbMessageAssembly assembly, MbInputTerminal inTerm) throws MbException
{
// add message processing code here
getOutputTerminal("out").propagate(assembly);
}
Ende der Änderung

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

Instanz des Knotens löschen

Eine Instanz des Knotens wird in den folgenden beiden Fällen gelöscht:
  • Wenn Sie den Broker beenden.
  • Wenn Sie den Knoten oder den Nachrichtenfluss, der den Knoten enthält, entfernen und die Konfiguration erneut implementieren.
Es wird empfohlen, den Knoten über den Löschvorgang zu informieren, so dass er Bereinigungsvorgänge durchführen kann, z. B. das Schließen von Sockets. Wenn der Knoten die optionale Methode onDelete implementiert, wird diese vom Broker aufgerufen, bevor der Knoten gelöscht wird.

Die Methode onDelete wird wie folgt implementiert:

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: 18.05.2006
as09970_