Dividiamo i passaggi sempre tra producer e consumer, prima quindi vediamo come installare il servizio sul server delle applicazioni integrato sulla macchina, poi come creare un client scritto in RPG che interroghi il servizio.
IL PRODUCER.
Di cosa abbiamo bisogno:
- Una macchina IBMi con IAS versione 8.1 (io ho usato la versione del sistema operativo V7R1).
Ricordate il war prodotto da Maven nel progetto Eclipse? Nella cartella target... MTOMService.war, proprio quello. Bene, prendiamolo e trasferiamolo sull'IFS del nostro sistema, in qualunque modo e in qualunque cartella vogliate.
Ad esempio io uso FileZilla e ho caricato il file su /tmp
Ora dovremmo collegarci al server amministrativo della nostra macchina, prima però verifichiamo che sia operativo, altrimenti avviamolo con:
STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)
Quindi apriamo il browser e indirizziamolo verso:
http://<host_nostra_macchina_IBMi>:2001/HTTPAdmin
e accediamo con un utente amministrativo.
Ci viene mostrata la lista dei server presenti nel sistema, dobbiamo creare un server delle applicazioni (come Tomcat) che ospiti la nostra servlet, per cui clicchiamo su "Crea server delle applicazioni":
Questo link è molto più semplice, rispetto a quello del DCM... valli a capire...
Scegliamo di usare la versione 8.1 del server:
e andiamo avanti accettando i default che ci vengono proposti, se non avevamo creato altri server delle applicazioni dovremmo avere il server INTAPPSVR in ascolto sulla porta 10000 della macchina.
Stop. Dopo lo riavviamo con il tasto play.
Spostiamoci su terminale, dobbiamo modificare una configurazione prima di farlo ripartire, modifichiamo questo file:
EDTF STMF('/www/INTAPPSVR/lwi/conf/overrides/i5javaopts.javaopt')
Inserendo questa riga:
-Dcom.ibm.websphere.webservices.DisableIBMJAXWSEngine=true
In questo modo istruiamo la JVM a non far partire il server con il supporto nativo JAX-WS.
Ora possiamo ritornare alla gestione del server e farlo ripartire (vedi sopra).
Clicchiamo sul link "Gestisci applicazioni installate", vediamo che per ora è presente una fantomatica quanto solinga "Guida di Eclipse", premiamo sul tasto Installa per aggiungere la nostra applicazione e chiediamo di importare il nostro war caricato prima:
Accettiamo tutti i default, infine vedremo la nostra applicazione fare compagnia alla "Guida di Eclipse" (?).
Facciamo click sul nome della nostra applicazione per interrogarla, si apre una nuova finestra del browser e... errore 404! Vi ricordate che va aggiusto services alla fine del link, vero?
La lista dei servizi messi a disposizione!
Possiamo copiare il link al nostro WSDL per creare un ambiente di test nel solito SoapUI, ma penso che sia arrivato il momento di fare da soli e creare un client in RPG.
IL CONSUMER.
Cosa ci occorre:
- HTTPAPI di S. Klement (versione usata 1.37)
- WSDL2RPG di T. Raddatz (la versione 1.16.5, che ha introdotto il supporto a MTOM, seppur sperimentale)
Preparativi.
Installiamo le due utility, magari con il supporto a HTTPS, e iniziamo con il creare un libreria e un file di sorgenti:
CRTLIB LIB(ZENEXMPL) TEXT('Example programs')
CRTSRCPF FILE(ZENUTILS/QWSDL) RCDLEN(112) TEXT('WSDL 2 RPG Stubs')
e mettiamo tutto in lista librerie:
ADDLIBLE LIB(LIBHTTP) ADDLIBLE LIB(WSDL2RPG) ADDLIBLE LIB(ZENEXMPL)
WSDL2RPG è un utility che crea le procedure necessarie ad assemblare la SOAP Envelope ed effettua la chiamata tramite HTTPAPI. I moduli creati vanno compilati ed assemblati in un service program che andrà collegato ai nostri programmi.
Per creare i sorgenti necessari usiamo il comando:
WSDL2RPG URL('http://localhost:10000/MTOMService/services/archiveServer?wsdl') SRCFILE(ZENEXMPL/QWSDL) SRCMBR(MTOM01) TYPE(*STUB) STRLEN(256) ATTACHMENT(*YES) PARMSTRUCT(*STMF) STRUCTSTMF('/tmp/MTOM01.log' *YES)
e selezioniamo con 1 tutti i metodi esposti dal servizio web: stiamo dicendo all'utility di creare il necessario per l'interrogazione di entrambi i metodi, con il supporto per l'invio di allegati.
Vengono creati i seguenti sorgenti nel file creato prima:
MTOM01 RPGLE Web Service: ArchiveServerPort MTOM01001 RPGLE Web Service: archiveFile() MTOM01002 RPGLE Web Service: getFile()
Da questi sorgenti vanno creati i moduli, ma prima sono necessarie delle modifiche per attivare la ricezione MTOM, dato che - come dicevo prima - è sperimentale. Apriamo il sorgente MTOM01001:
STRSEU SRCFILE(ZENEXMPL/QWSDL) SRCMBR(MTOM01001)
(ma potete anche usare RDi.)
Dobbiamo cercare l'istruzione:
g_hMsgCtx = MessageContext_new();
e modificarla così:
g_hMsgCtx = MessageContext_new(cTrue);
(tutto qui.)
La stessa cosa va fatta anche per il sorgente MTOM01002.
Ora possiamo compilare:
CRTRPGMOD MODULE(ZENEXMPL/MTOM01) SRCFILE(ZENEXMPL/QWSDL) SRCMBR(MTOM01) CRTRPGMOD MODULE(ZENEXMPL/MTOM01001) SRCFILE(ZENEXMPL/QWSDL) SRCMBR(MTOM01001) CRTRPGMOD MODULE(ZENEXMPL/MTOM01002) SRCFILE(ZENEXMPL/QWSDL) SRCMBR(MTOM01002)
e creare il service program.
CRTSRVPGM SRVPGM(ZENEXMPL/MTOM01) MODULE(ZENEXMPL/MTOM01 ZENEXMPL/MTOM01001 ZENEXMPL/MTOM01002) EXPORT(*ALL) TEXT('MTOM Service Example') BNDSRVPGM((*LIBL/WSDL2RPGRT) (*LIBL/MIME) (*LIBL/HTTPMIME) (*LIBL/BASICS1)) BNDDIR(QC2LE)
Implementiamo.
L'utility ha creato le procedure necessarie per interrogare il nostro web service, e noi abbiamo compilato il programma di servizio per utilizzarle, in particolare la procedura:
ArchiveServerPort_archiveFile
effettua la chiamata al servizio archiveFile della nostra applicazione e se andiamo a indagare la sua definizione vediamo che richiede in ingresso:
- una struttura dati i_tns_archiveFile di tipo tns_archiveFileRnmd_t : sono i parametri da passare al web service;
- una struttura dati o_msg di tipo wsdl_errText_t : contiene eventuali messaggi di errore;
in uscita invece popola una struttura dati di tipo tns_archiveFileResponse_t che contiene la risposta del web service.
NB: le strutture dati tns_archiveFileRnmd_t e tns_archiveFileResponse_t sono modellate dall'utility secondo quanto è stato dichiarato nel WSDL, rispecchiano quindi la stessa struttura dello schema XML!
NB2: l'utility rinomina le procedure e le strutture dati secondo i nomi del nostro web service e i suoi metodi, normalmente quindi le procedure descritte sopra cambiano sempre nome per ogni web service di cui facciamo lo stub, ad esempio il template per i nomi visti prima sono:
- procedura principale: <Nome_Web_Service>_<Nome_Metodo> ;
- struttura dati ingresso: tns_<Nome_Metodo>Rnmd_t ;
- struttura dati uscita: tns_<Nome_Metodo>Response_t .
Se non abbiamo idea di come utilizzare questa procedura e non vogliamo partire da zero, niente paura! WSDL2RPG ci permette di costruire in automatico un programma di esempio con il comando:
WSDL2RPG URL('http://localhost:10000/MTOMService/services/archiveServer?wsdl') SRCFILE(ZENEXMPL/QWSDL) SRCMBR(MTOM01001T) TYPE(*PGM) STUB(MTOM01001)
e selezionando il metodo archiveFile e ancora:WSDL2RPG URL('http://localhost:10000/MTOMService/services/archiveServer?wsdl') SRCFILE(ZENEXMPL/QWSDL) SRCMBR(MTOM01002T) TYPE(*PGM) STUB(MTOM01002)
e selezionando il metodo getFile.
Ora abbiamo due sorgenti di due programmi che testano le due procedure, dobbiamo solo modificare qualche riga per poter fargli fare quello che vogliamo. Iniziamo dal programma per fare l'upload: MTOM01001T.
STRSEU SRCFILE(ZENEXMPL/QWSDL) SRCMBR(MTOM01001T)
(come prima, potete usare RDi)
Prima di tutto inseriamo dei parametri di ingresso, in modo che il programma possa essere utilizzato in maniera variabile (al momento i parametri sono fissi) tramite un comando, cerchiamo:
D MTOM01001T... D PR
e
D MTOM01001T... D PI
e sotto inseriamo:
D description like( D tns_archiveRequest_t.description) D fileLoad like( D tns_archiveRequest_t.fileLoad) D fileName like( D tns_archiveRequest_t.fileName) D fileType like( D tns_archiveRequest_t.fileType) D key like( D tns_archiveRequest_t.key)
Quindi spostiamo i parametri in ingresso nella struttura dati che contiene i parametri della Request, che diventa:
parameters.request.fileName = fileName; parameters.request.fileType = 'application/pdf'; parameters.request.key = key; parameters.request.description = description;
alla fine aggiungiamo il nostro allegato:
parameters.request.fileLoad = 'cid:'+ ArchiveServerPort_archiveFile_Attachments_addFile( filePath: parameters.request.fileType);
NB: la procedura ArchiveServerPort_archiveFile_Attachments_addFile serve per aggiungere un allegato, richiede il percorso del file sull'IFS e il suo MIME-Type e ritorna l'identificativo della sezione http dove verrà inserito, come al solito il nome può cambiare e il template è:
<Nome_Web_Service>_<Nome_Metodo>_Attachments_addFile.
Ora tocca al programma per fare il download: MTOM01002T.
STRSEU SRCFILE(ZENEXMPL/QWSDL) SRCMBR(MTOM01002T)
In maniera simile a prima aggiungiamo i parametri, che è uno solo: la chiave del documento registrata in upload. Per cui cerchiamo:
D MTOM01002T... D PR
e
D MTOM01002T... D PI
e sotto inseriamo:
D key like( D tns_getFile_t.key)
E poi facciamo sempre in modo che il nostro input finisca nei parametri della Request:
parameters.key = key;
Ora possiamo compilare:
CRTRPGMOD MODULE(ZENEXMPL/MTOM01001T) SRCFILE(*LIBL/QWSDL) SRCMBR(MTOM01001T) DBGVIEW(*LIST) TRUNCNBR(*NO)
CRTPGM PGM(ZENEXMPL/MTOM01001T) MODULE(ZENEXMPL/MTOM01001T) TEXT('MTOM Service Example - Test Upload') BNDSRVPGM((ZENEXMPL/MTOM01)) BNDDIR(QC2LE) ACTGRP(*NEW)
CRTRPGMOD MODULE(ZENEXMPL/MTOM01002T) SRCFILE(*LIBL/QWSDL) SRCMBR(MTOM01002T) DBGVIEW(*LIST) TRUNCNBR(*NO)
CRTPGM PGM(ZENEXMPL/MTOM01002T) MODULE(ZENEXMPL/MTOM01002T) TEXT('MTOM Service Example - Test Download') BNDSRVPGM((ZENEXMPL/MTOM01)) BNDDIR(QC2LE) ACTGRP(*NEW)
Abbiamo i nostri due programmi di test, ma potrebbe essere utile fare due comandi per poterli utilizzare, iniziamo creando il comando per inviare:
STRSEU SRCFILE(ZENEXMPL/QWSDL) SRCMBR(SNDMTOM) TYPE(CMD) TEXT('Web Service: archiveFile() - Upload Comand')
e modifichiamo il sorgente SNDMTOM così:
CMD PROMPT('MTOM Service Upload')
PARM KWD(DESC) +
MIN(1) +
TYPE(*CHAR) +
VARY(*YES *INT2) +
LEN(128) +
CASE(*MIXED) +
PROMPT('File description' 1)
PARM KWD(PATH) +
MIN(1) +
TYPE(*CHAR) +
VARY(*YES *INT2) +
LEN(128) +
CASE(*MIXED) +
PROMPT('File path' 2)
PARM KWD(NAME) +
MIN(1) +
TYPE(*CHAR) +
VARY(*YES *INT2) +
LEN(128) +
CASE(*MIXED) +
PROMPT('File name' 3)
PARM KWD(TYPE) +
MIN(1) +
TYPE(*CHAR) +
VARY(*YES *INT2) +
LEN(128) +
CASE(*MIXED) +
PROMPT('File type' 4)
PARM KWD(KEY) +
MIN(1) +
TYPE(*CHAR) +
VARY(*YES *INT2) +
LEN(20) +
CASE(*MIXED) +
PROMPT('Key' 5)
Stessa cosa per il comando per ricevere: RCVMTOM.
STRSEU SRCFILE(ZENEXMPL/QWSDL) SRCMBR(RCVMTOM) TYPE(CMD) TEXT('Web Service: archiveFile() - Download Comand')
e quindi:
CMD PROMPT('MTOM Service Download')
PARM KWD(KEY) +
MIN(1) +
TYPE(*CHAR) +
VARY(*YES *INT2) +
LEN(20) +
CASE(*MIXED) +
PROMPT('Key' 1)
Infine non ci resta che creare anche questi oggetti:
CRTCMD CMD(ZENEXMPL/SNDMTOM) PGM(ZENEXMPL/MTOM01001T) SRCFILE(ZENEXMPL/QWSDL) SRCMBR(SNDMTOM) CRTCMD CMD(ZENEXMPL/RCVMTOM) PGM(ZENEXMPL/MTOM01002T) SRCFILE(ZENEXMPL/QWSDL) SRCMBR(RCVMTOM)
Ora possiamo testare i nostri programmi! Assicuriamoci di avere un file PDF da utilizzare per i nostri scopi salvato su IFS, per comodità io mi riferirò a un ipotetico file testfile.pdf presente in /tmp, iniziamo inviando il file:
ZENEXMPL/SNDMTOM DESC('Test file.') PATH('/tmp/testfile.pdf') NAME(renamed.pdf) TYPE('application/pdf') KEY(TEST1)
(lo salviamo sotto altro nome, giusto per provare.)
Il messaggio *** Success *** in fondo al terminale ci indica che la trasmissione è avvenuta, ma dove è stato salvato il file? Ricordate che l'applicazione stampa in output il path di archiviazione? Però questo output non è interattivo, è salvato in un file apposito nel percorso dell'istanza del server:
DSPF STMF('/www/INTAPPSVR/lwi/logs/lwistdout.txt')
dall'output notiamo che i file temporanei sono gestiti per singola istanza, per cui troviamo il file salvato qui:
DSPF STMF('/www/INTAPPSVR/lwi/temp/uploaded/renamed.pdf')
Ora quindi proviamo a recuperare il file appena archiviato:
ZENEXMPL/RCVMTOM KEY(TEST1)
Ancora, il messaggio *** Success *** ci indica che tutto è ok, questa volta però spetta alla nostra procedura salvare il file, che di default salva tutti gli allegati in /tmp/attachments:
WRKLNK OBJ('/tmp/attachments')
Considerazioni.
La funzione MTOM dell'utility è un'aggiunta interessante ed è stato divertente approcciarsi a questa metodologia e farla funzionare su IBMi, ricordo però che è ancora in fase sperimentale, e non è quindi esente da mancanze e bug che ne potrebbero limitare l'usabilità, nel caso vi invito a contattare l'autore per segnalare eventuali problemi che potrebbero essere corretti in una futura release!
Di seguito alcuni link utili:
- il sito di Raddatz ha una serie di manuali che spiegano più ampiamente l'utility e le sue procedure;
- la mailing list di Klement: è per avere aiuto per HTTPAPI, però viene data risposta anche a domande su WSDL2RPG;
- Il repository dove ho rilasciato i sorgenti di questo esempio: i sorgenti vanno importati poi a mano nella libreria ZENEXMPL, oppure ho preparato un SAVF che può essere ripristinato sulla macchina (salvato come V7R1M0);
- Configurazioni particolari per fa funzionare CXF su WebSphere;
- Manuale dello IAS.
