Empfangsknoten in Java erstellen

Vorbereitungen

Stellen Sie sicher, dass Sie folgende Abschnitte gelesen und verstanden haben:
Ein benutzerdefinierter Java-Knoten wird als JAR-Datei verteilt. In diesem Abschnitt werden die Schritte beschrieben, die Sie ausführen müssen, um einen Empfangsknoten mit Java zu erstellen. Folgende Schritte werden erläutert:
  1. Neues Java-Projekt erstellen
  2. Empfangsknotenklasse deklarieren
  3. Knotenkonstruktor definieren
  4. Externe Daten in einem Puffer empfangen
  5. Nachricht weitergeben
  6. Threading und Transaktionalität steuern
  7. Knotennamen deklarieren
  8. Attribute deklarieren
  9. Knotenfunktionen implementieren
  10. Standardattribute für Nachrichtenparser überschreiben (optional)
  11. Instanz des Knotens löschen

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 im linken Menü Java aus, und wählen Sie anschließend aus dem rechten Menü Java Project (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.

Empfangsknotenklasse deklarieren

Jede Klasse, durch die MbInputNodeInterface implementiert wird und im LIL-Pfad des Brokers enthalten ist, wird mit dem Broker als Empfangsknoten registriert. Bei der Implementierung von MbInputNodeInterface muss auch eine run-Methode für diese Klasse implementiert werden. Die Methode run stellt den Start des Nachrichtenflusses dar, enthält die Daten, mit denen die Nachricht formuliert wird und gibt sie im Nachrichtenfluss weiter. Der Broker ruft die Methode run auf, wenn Threads entsprechend dem angegebenen Threading-Modell verfügbar sind.

Im Folgenden finden Sie ein Beispiel für die Deklaration der Empfangsknotenklasse:

package com.ibm.jplugins;
import com.ibm.broker.plugin.*;
public class BasicInputNode extends MbInputNode implements MbInputNodeInterface
{
...
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 MbInputNode aus.
  5. Klicken Sie neben dem Textfeld 'Interface' (Schnittstelle) auf die Schaltfläche Hinzufügen, und wählen Sie MbInputNodeInterface 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 die Attribute.

Einem Empfangsknoten sind eine Reihe von Ausgabeterminals zugeordnet, er verfügt jedoch normalerweise nicht über Eingabeterminals. Verwenden Sie die Methode createOutputTerminal, um einem Knoten Ausgabeterminals hinzuzufügen, wenn eine Instanz des Knotens erstellt wird. Im Folgenden finden Sie ein Beispiel für die Erstellung eines Knotens mit drei Ausgabeterminals:

public BasicInputNode() throws MbException
{
	createOutputTerminal ("out");
	createOutputTerminal ("failure");
	createOutputTerminal ("catch");
setAttribute ("firstParserClassName","myParser");
attributeVariable = "none";
}

Externe Daten in einem Puffer empfangen

Ein Empfangsknoten kann wie jedes andere Java-Programm Daten aus allen Arten von externen Quellen, z. B. einem Dateisystem, einer Warteschlange oder einer Datenbank, empfangen, solange die Ausgabe des Knotens im richtigen Format vorliegt.

Sie müssen einen Eingabepuffer (oder einen Bitstrom) bereithalten, in dem Eingabedaten enthalten sind, und ihn einem Nachrichtenobjekt zuordnen. Dann erstellen Sie mit der Methode createMessage der Klasse MbInputNode eine Nachricht aus einer Bytefeldgruppe, und anschließend generieren Sie aus dieser Nachricht ein gültiges Nachrichten-Assembly. Weitere Informationen zu diesen Methoden finden Sie im Abschnitt Java-API. Wenn Sie beispielsweise die Eingabe aus einer Datei lesen möchten, gehen Sie wie folgt vor:

  1. Erstellen Sie einen Eingabedatenstrom, um die Daten aus der Datei zu lesen:
    FileInputStream inputStream = new FileInputStream("myfile.msg");
  2. Erstellen Sie eine Bytefeldgruppe, die dieselbe Größe wie die Eingabedatei hat:
    byte[] buffer = new byte[inputStream.available()];
  3. Lesen Sie die Daten aus der Datei in die Bytefeldgruppe ein:
    inputStream.read(buffer);
  4. Schließen Sie den Eingabedatenstrom:
    inputStream.close();
  5. Erstellen Sie eine Nachricht, die in die Warteschlange eingereiht werden soll:
    MbMessage msg = createMessage(buffer);
  6. Erstellen Sie ein neues Nachrichten-Assembly, das diese Nachricht enthalten soll:
    msg.finalizeMessage(MbMessage.FINALIZE_VALIDATE);
    MbMessageAssembly newAssembly =
    new MbMessageAssembly( assembly, msg );

Nachricht weitergeben

Wenn Sie ein Nachrichten-Assembly erstellt haben, können Sie dies an einen der Terminals des Knotens weitergeben.

Geben Sie beispielsweise Folgendes ein, um das Nachrichten-Assembly an das Ausgangsterminal weiterzugeben:
MbOutputTerminal out = getOutputTerminal("out");
out.propagate(newAssembly);
Gehen Sie zum Löschen der Nachricht folgendermaßen vor:
msg.clearMessage();

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

Threading und Transaktionalität steuern

Die Broker-Infrastruktur verarbeitet Transaktionen wie das Festschreiben einer WebSphere MQ- oder Datenbank-Arbeitseinheit, wenn die Nachrichtenverarbeitung abgeschlossen ist. Beginn der ÄnderungAllerdings befinden sich Ressourcen, die in einem benutzerdefinierten Knoten geändert wurden, nicht zwangsläufig unter transaktionsorientierter Steuerung des Brokers. Ende der Änderung

Jeder Nachrichtenfluss-Thread wird aus einem Thread-Pool zugeordnet, der für jeden Nachrichtenfluss verwaltet wird, und startet die Ausführung in der Methode run.

Der benutzerdefinierte Knoten verwendet Rückgabewerte, um anzugeben, ob eine Transaktion erfolgreich war, um zu steuern, ob Transaktionen festgeschrieben oder zurückgesetzt werden, und um zu steuern, wann der Thread an den Pool zurückgegeben wird. Alle nicht verarbeiteten Ausnahmebedingungen werden von der Broker-Infrastruktur abgefangen, und die Transaktion wird zurückgesetzt.

Sie bestimmen das Verhalten von Transaktionen und Threads, indem Sie den entsprechenden Rückgabewert verwenden:

MbInputNode.SUCCESS_CONTINUE
Die Transaktion wird festgeschrieben, und der Broker ruft die Methode run erneut mit demselben Thread auf.
MbInputNode.SUCCESS_RETURN
Die Transaktion wird festgeschrieben, und der Thread wird an den Thread-Pool zurückgegeben, wobei vorausgesetzt wird, dass dies nicht der einzige Thread für diesen Nachrichtenfluss ist.
MbInputNode.FAILURE_CONTINUE
Die Transaktion wird zurückgesetzt, und der Broker ruft die Methode run erneut mit demselben Thread auf.
MbInputNode.FAILURE_RETURN
Die Transaktion wird zurückgesetzt, und der Thread wird an den Thread-Pool zurückgegeben, wobei vorausgesetzt wird, dass dies nicht der einzige Thread für diesen Nachrichtenfluss ist.
MbInputNode.TIMEOUT
Die Methode run darf nicht unbegrenzt blockieren, während sie auf Eingabedaten wartet. Während der Nachrichtenfluss durch Benutzercode blockiert wird, können Sie den Broker nicht beenden oder neu konfigurieren. Die Methode run muss die Steuerung regelmäßig durch Rückgabe an den Broker abgeben. Wenn nach einer bestimmten Zeit (z. B. 5 Sekunden) keine Eingabedaten empfangen wurden, sollte die Rückgabe der Methode mit dem Rückkehrcode TIMEOUT erfolgen. Die Methode run des Empfangsknotens wird dann gleich wieder aufgerufen, vorausgesetzt, der Broker muss nicht neu konfiguriert oder beendet werden.
Um Multithread--Nachrichtenflüsse zu erstellen, rufen Sie die Methode dispatchThread auf, nachdem eine Nachricht erstellt wurde, aber bevor die Nachricht an ein Ausgabeterminal weitergegeben wird. Dadurch wird gewährleistet, dass nur ein Thread auf Daten wartet, während andere Threads die Nachricht verarbeiten. Neue Threads werden bis zu dem Maximalwert, der durch das Attribut 'additionalInstances' des Nachrichtenflusses angegeben wird, aus dem Thread-Pool abgerufen. Beispiel:
public int run( MbMessageAssembly assembly ) throws MbException
{
byte[] data = getDataWithTimeout();  // user supplied method
// returns null if timeout
if( data == null )
return TIMEOUT;
MbMessage msg = createMessage( data );
msg.finalizeMessage( MbMessage.FINALIZE_VALIDATE );
MbMessageAssembly newAssembly =
new MbMessageAssembly( assembly, msg );
dispatchThread();
getOutputTerminal( "out" ).propagate( newAssembly );
return SUCCESS_RETURN;
}

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 "BasicInputNode";
}
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 "ComIbmPluginsamplesBasicInputNode" zugeordnet:
package com.ibm.pluginsamples;
public class BasicInputNode extends MbInputNode implements MbInputNodeInterface
{
...

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 bereits beschrieben wird die Methode run vom Broker aufgerufen, um die Eingabenachricht zu erstellen. Diese Methode sollte alle Verarbeitungsfunktionen für den Empfangsknoten bereitstellen.

Standardattribute für Nachrichtenparser überschreiben (optional)

Eine Empfangsknotenimplementierung bestimmt normalerweise, welcher Nachrichtenparser eine Eingabenachricht anfangs analysiert. Der primitive MQEmpfangsknoten gibt beispielsweise vor, dass für die Syntaxanalyse des MQMD-Headers ein MQMD-Parser erforderlich ist. Ein benutzerdefinierter Empfangsknoten kann einen geeigneten Header oder Nachrichtenparser und den Modus, in dem die Syntaxanalyse gesteuert wird, mit Hilfe der folgenden Attribute auswählen, die standardmäßig enthalten sind und die Sie überschreiben können:

rootParserClassName
Definiert den Namen des Stamm-Parsers, der Nachrichtenformate analysiert, die vom benutzerdefinierten Empfangsknoten unterstützt werden. Der Standardwert ist GenericRoot, ein bereitgestellter Stamm-Parser, der den Broker veranlasst, Parser zuzuordnen und zu verketten. Es ist unwahrscheinlich, dass ein Knoten diesen Attributwert ändern muss.
firstParserClassName
Definiert den Namen des ersten Parsers in einer möglichen Kette von Parsern, die für die Syntaxanalyse des Bitstroms verantwortlich sind. Der Standardwert ist XML.
messageDomainProperty
Ein optionales Attribut, das den Namen des Nachrichtenparsers definiert, der für die Syntaxanalyse der Eingabenachricht erforderlich ist. Die unterstützten Werten entsprechen den vom MQEmpfangsknoten unterstützten Werten. (Weitere Informationen zum MQEmpfangsknoten finden Sie unter MQEmpfangsknoten.)
messageSetProperty
Ein optionales Attribut, das die Nachrichtengruppen-ID oder den Nachrichtengruppennamen im Feld Nachrichtengruppe definiert, aber nur wenn der MRM-Parser durch das Attribut messageDomainProperty angegeben wurde.
messageTypeProperty
Ein optionales Attribut, das die Nachrichten-ID im Feld Nachrichtenart definiert, aber nur wenn der MRM-Parser durch das Attribut messageDomainProperty angegeben wurde.
messageFormatProperty
Ein optionales Attribut, das das Format der Nachricht im Feld Nachrichtenformat definiert, aber nur wenn der MRM-Parser durch das Attribut messageDomainProperty angegeben wurde.

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 Informationen
Java-API
Bemerkungen | Marken | Downloads | Bibliothek | Unterstützung | Rückmeldung
Copyright IBM Corporation 1999, 2006 Letzte Aktualisierung: 18.05.2006
as09950_