Creazione di un nodo di output o di elaborazione messaggi in Java

Prima di iniziare

WebSphere Message Broker fornisce l'origine per due nodi definiti dall'utente di esempio denominati SwitchNode e TransformNode. E' possibile utilizzare tali nodi nel loro stato attuale oppure modificarli.

Concettualmente, un nodo di elaborazione messaggi viene utilizzato per elaborare un messaggio mentre un nodo di output viene utilizzato per eseguire l'output di un messaggio come un flusso di bit. Tuttavia, quando si codifica un nodo di elaborazione messaggi o un nodo di output, questi sono essenzialmente la stessa cosa. E' possibile eseguire l'elaborazione messaggi all'interno di un nodo di output e similmente è possibile eseguire l'output di un messaggio su un flusso di bit utilizzando un nodo di elaborazione messaggi. Per semplicità, questo argomento fa riferimento principalmente al nodo come un nodo di elaborazione messaggi, tuttavia, tratta la funzionalità di entrambi i tipi di nodo.

Creazione di un nuovo progetto Java

È possibile creare nodi Java dall'interno di workbench. A tal fine, è necessario creare un nuovo progetto Java, come riportato di seguito:
  1. Passare alla prospettiva Java.
  2. Fare clic su File > Nuovo > Progetto. Selezionare Java dal menu a sinistra quindi selezionare Progetto Java dal menu a destra.
  3. Assegnare un nome al progetto.

    Viene visualizzato il pannello relativo alle impostazioni Java.

  4. Selezionare la scheda relativa alle librerie e fare clic su Aggiungi JAR esterne.
  5. Selezionare install_dir\classes\jplugin2.jar.
  6. Seguire i messaggi di richiesta sulle altre schede per definire qualsiasi altra impostazione di creazione.
  7. Fare clic su Fine.
E' possibile quindi sviluppare l'origine per il nodo Java all'interno del progetto.

Dichiarazione della classe del nodo di elaborazione messaggi

Qualsiasi classe che implementa MbNodeInterface ed è contenuta nel percorso della LIL del broker viene registrata con il broker come un nodo di elaborazione messaggi. Con l'implementazione di MbNodeInterface, è necessario implementare anche un metodo evaluate per tale classe. Il metodo evaluate viene richiamato dal broker per ciascun messaggio passato mediante il flusso.

Ad esempio, per dichiarare la classe del nodo di elaborazione messaggi:
package com.ibm.jplugins;

import com.ibm.broker.plugin.*;

public class BasicNode extends MbNode implements MbNodeInterface
E' possibile procedere in tal modo nel workbench effettuando quanto riportato di seguito:
  1. Fare clic su File > Nuovo > Classe.
  2. Impostare nei campi relativi al nome di classe e al pacchetto i valori appropriati.
  3. Eliminare il testo nel campo Superclasse e fare clic sul pulsante Sfoglia.
  4. Selezionare MbNode e fare clic su OK.
  5. Fare clic sul pulsante Aggiungi in prossimità del campo di testo relativo alle interfacce e selezionare MbNodeInterface.
  6. Fare clic su Fine.

Definizione del costruttore del nodo

Quando viene creata l'istanza del nodo, viene richiamato il costruttore della classe del nodo dell'utente. Ovvero dove vengono creati i terminali del nodo e inizializzato qualsiasi valore predefinito per gli attributi.

Ad un nodo di elaborazione messaggi sono associati una serie di terminali di input e di output. I metodi createInputTerminal e createOutputTerminal vengono utilizzati per aggiungere terminali ad un nodo quando viene creata l'istanza di tale nodo. Ad esempio, per creare un nodo con un terminale di input e due terminali di output:

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

Accesso ai dati del messaggio

In molti casi, il nodo definito dall'utente ha necessità di accedere al contenuto del messaggio ricevuto sul relativo terminale di input. Il messaggio è rappresentato come una struttura ad albero degli elementi di sintassi. Vengono forniti gruppi di funzioni di utilità, da usare nel metodo evaluate, utilizzati per la gestione dei messaggi, l'accesso al buffer di messaggi, la navigazione e l'acceso all'elemento di sintassi.

La classe MbElement fornisce l'interfaccia agli elementi di sintassi. Per ulteriori informazioni dettagliate su l'API Java, fare riferimento alla documentazione Java.

Ad esempio:

  1. Per navigare nell'elemento di sintassi rilevante nel messaggio XML:
        MbElement rootElement = assembly.getMessage().getRootElement();
        MbElement switchElement = 
    			rootElement.getLastChild().getFirstChild().getFirstChild();
  2. Per selezionare il terminale indicato dal valore di questo elemento:
        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);

Trasformazione di un oggetto messaggio

Il messaggio di input ricevuto è si sola lettura quindi, prima che un messaggio possa essere trasformato, è necessario scriverlo su un nuovo messaggio di output. È possibile copiare elementi dal messaggio di input o creare nuovi elementi nel messaggio di output. I nuovi elementi sono generalmente in un dominio del programma di analisi.

La classe MbMessage fornisce i costruttori di copie ed i metodi per ottenere l'elemento root del messaggio. La classe MbElement fornisce l'interfaccia agli elementi di sintassi.

Ad esempio, dove è presente un assemblaggio di messaggi in entrata con messaggi integrati, è possibile avere il seguente codice nel metodo evaluate del nodo definito dall'utente:
  1. Per creare una nuova copia dell'assemblaggio di messaggi e dei relativi messaggi integrati:
        MbMessage newMsg = new MbMessage(assembly.getMessage());
        MbMessageAssembly newAssembly = new MbMessageAssembly(assembly, newMsg);
  2. Per navigare nell'elemento di sintassi rilevante nel messaggio XML:
        MbElement rootElement = newAssembly.getMessage().getRootElement();
        MbElement switchElement = 
    			rootElement.getFirstElementByPath("/XML/data/action");
  3. Per modificare il valore di un elemento esistente:
      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. Per aggiungere una nuova tag come child della tag switch:
        MbElement tag = switchElement.createElementAsLastChild(MbElement.TYPE_NAME,
                                                               "PreviousValue",
                                                               elementValue);
  5. Per aggiungere un attributo a questa nuova tag:
        tag.createElementAsFirstChild(MbElement.TYPE_NAME_VALUE,
                                      "NewValue",
                                      switchElement.getValue());
    
        MbOutputTerminal out = getOutputTerminal("out");
Come parte della trasformazione, potrebbe essere necessario creare un nuovo contenuto del messaggio. Per creare il contenuto di un nuovo messaggio, sono disponibili i seguenti metodi:
createElementAfter(String) 
createElementAsFirstChild(String) 
createElementAsLastChild(String) 
createElementBefore(String) 
createElementAsLastChildFromBitstream(byte[], String, String, String, String, int, int, int) 
Tali metodi devono essere utilizzati in quanto sono specifici dell'assegnazione di un programma di analisi ad una cartella della struttura ad albero del messaggio.
Quando si crea il contenuto di un messaggio, non utilizzare i seguenti metodi in quando questi non eseguono l'associazione di un programma di analisi di proprietà con la cartella:
createElementAfter(int)
createElementAfter(int, String, Object) 
createElementAsFirstChild(int) 
createElementAsFirstChild(int, String, Object) 
createElementAsLastChild(int) 
createElementAsLastChild(int, String, Object) 
createElementBefore(int) 
createElementBefore(int, String, Object) 

Distribuzione del messaggio

Prima di distribuire un messaggio è necessario decidere quali dati del flusso di messaggi si desidera distribuire e quale terminale del nodo deve ricevere tali dati.

Ad esempio:
  1. Per distribuire il messaggio al terminale di output "out":
    MbOutputTerminal out = getOutputTerminal("out");
            out.propagate(newAssembly);

Per svuotare la memoria assegnata all'albero del messaggio, richiamare la funzione clearMessage() all'interno del blocco finale try/catch.

Dichiarazione del nome del nodo

E' necessario dichiarare il nome del nodo in quanto verrà identificato dal workbench. Tutti i nomi di nodo devono terminare con "Node". Si dichiara il nome utilizzando il seguente metodo:

public static String getNodeName()
{
   return "BasicNode";
}
Se questo metodo non è dichiarato, il framework dell'API Java crea un nome di nodo predefinito utilizzando le seguenti regole:
  • Il nome di classe viene apposto al nome del pacchetto.
  • I punti vengono eliminati e la prima lettera di ciascuna parte del nome di classe e pacchetto viene posta in maiuscolo.
Ad esempio, per impostazione predefinita, alla seguente classe viene assegnato il nome di nodo "ComIbmPluginsamplesBasicNode":
package com.ibm.pluginsamples;
public class BasicNode extends MbNode implements MbNodeInterface
{
   ...

Dichiarazione degli attributi

Gli attributi del nodo vengono dichiarati nello stesso modo delle proprietà di Java Bean. E' sotto la propria responsabilità la scrittura di metodi per ottenere e impostare gli attributi e il framework dell'API deduce i nomi di attributo utilizzando le regole di introspezione Java Bean. Ad esempio, se si dichiarano i due seguenti metodi:

private String attributeVariable;

public String getFirstAttribute()
{
  return attributeVariable;
}

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

Il broker deduce che questo nodo ha un attributo denominato firstAttribute. Tale nome viene ricavato dai nomi dei metodi "get" o "set" e non dai nomi di variabile dei membri di classe interna. Gli attributi possono essere esposti solo come stringhe, è quindi necessario convertire qualsiasi tipo numerico relativo alle stringhe in tali metodi. Ad esempio, il metodo riportato di seguito definisce un attributo denominato timeInSeconds:

int seconds;

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

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

Implementazione della funzionalità del nodo

Come descritto in precedenza, per i nodi di output o di elaborazione messaggi, è necessario implementare il metodo evaluate, definito in MbNodeInterface. Questo viene richiamato dal broker per elaborare il messaggio. Tale metodo deve fornire tutta la funzione di elaborazione per il nodo.

Il metodo evaluate ha due parametri che vengono passati dal broker:
  1. MbMessageAssembly, che contiene i seguenti oggetti a cui si accede utilizzando i metodi appropriati:
    • Il messaggio in entrata
    • L'ambiente locale
    • L'ambiente globale
    • L'elenco di eccezioni
  2. Il terminale di input su cui è arrivato il messaggio.
Ad esempio, il seguente estratto di codice mostra come può essere scritto il metodo di valutazione:
public void evaluate(MbMessageAssembly assembly, MbInputTerminal inTerm) throws MbException
  {
    // aggiungere qui codice di elaborazione messaggio

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

I dati del flusso di messaggi ovvero il messaggio, l'ambiente globale, l'ambiente locale e l'elenco di eccezioni, vengono ricevuti al terminale di input del nodo.

Eliminazione di un'istanza del nodo

Un'istanza del nodo viene eliminata quando:
  • Il broker viene chiuso.
  • Viene eliminato il nodo o il flusso di messaggi contenente il nodo e si ridistribuisce la configurazione.
Durante l'eliminazione del nodo, questo potrebbe voler essere informato in modo da poter eseguire eventuali operazioni di cleanup, come la chiusura dei socket. Se il nodo implementa il metodo onDelete facoltativo, questo viene richiamato dal broker prima che il nodo venga eliminato.

Il metodo onDelete viene implementato nel modo seguente:

public void onDelete()
{
  // eseguire cleanup del nodo se necessario
}
Riferimenti correlati
Struttura dell'elenco di eccezioni
Informazioni particolari | Marchi | Download | Libreria | Supporto | Commenti
Copyright IBM Corporation 1999, 2006 Ultimo aggiornamento: ago 17, 2006
as09970_