Maria Paola BonfadiniIndice articolo
In questo articolo vi descriverò come integrare un progetto di Web Service Client Java con Sme.UP ERP.
Ho usato un client SOAP creato un un precedente articolo, ma gli stessi concetti valgono per qualunque tipologia di webservice o api-client java.
Prerequisito fondamentale per poter comprendere al meglio questo argomento è aver letto il mio articolo precedente nel quale descrivo come creare un client soap in java. Quindi, se non l’avete già fatto, andate a questo link http://blog.smeup.com/creare-un-client-soap-in-java/.
In diversi articoli di questo blog si è parlato dello Sme.UP Provider e del suo fondamentale ruolo di interlocutore con Sme.UP ERP. Attraverso lo sviluppo di Plugin è possibile estendere le funzionalità dello Sme.UP Provider. Una possibile estensione è, appunto, far sì che il Provider comunichi con un Web Service, assumendo a tutti gli effetti il ruolo di Web Service Client.
La scelta di separare il cuore dello Sme.UP Provider dai Plugins ha portato considerevoli vantaggi tra cui facilitare lo sviluppo di nuove integrazioni senza dover modificare ed appesantire l’intero progetto dello Sme.UP Provider e facilitare agli sviluppatori i test che diventano possibili provando solo la parte di integrazione.
Maven
Prima di entrare nel merito dell’articolo vorrei introdurre brevemente, per chi non lo conoscesse, Maven.
Maven è un software usato principalmente per la gestione di progetti Java.
Il suo utilizzo comporta notevoli vantaggi tra i quali la standardizzazione della struttura di un progetto e del processo di compilazione, insieme alla gestione e download automatico delle librerie necessarie al progetto con risoluzione delle eventuali dipendenze. Per il nostro scopo apprezzeremo Maven soprattutto per quest’ultima caratteristica.
Il progetto viene descritto tramite il pom.xml (POM=Project Object Model), un file di configurazione che contiene informazioni generali del progetto, dipendenze, processo di compilazione e fasi secondarie come la generazione di documentazione.
Come abbiamo detto la gestione e download automatico delle librerie necessarie al progetto è uno dei punti di forza di Maven. Una volta individuata la libreria che ci interessa da includere nel progetto, Maven di default si collegherà al repository remoto e scaricherà lui tutti i pacchetti di cui necessita, comprese le dipendenze degli stessi.
Per inserire questa dipendenza è sufficiente aggiungere nel file pom.xml un tag <dependencies> e dentro questo mettiamo quanto segue:
<dependency> <groupId>groupIdLib</groupId> <artifactId>artifactIdLib</artifactId> <version>x.x.x</version> </dependency>
Spesso nel sito della libreria che vi interessa troverete la stringa <dependency> che vi occorre.
Configurazione progetto java
Entriamo finalmente nel merito dell’articolo, cioè integrare un progetto Web Service Client con il costruttore A38.
Il costruttore A38 ha lo scopo di mettere a disposizione una configurazione, e la relativa interfaccia per l’utilizzo, che permette di definire e dichiarare connettori verso servizi esposti da Web Services esterni.
La configurazione si basa sugli script con prefisso LOA38_ contenuti nel file SCP_SET che ereditano la struttura di Sezione e Sub-sezione dagli script usati per i costruttori V2-LOCOS.
Ora dobbiamo prendere il nostro progetto Web Service Client ed inserire come dipendenza la libreria di integrazione che permetterà di colloquiare con il costruttore A38 tramite una classe che implementi l’interfaccia SPIWsCConnectorInterface.
Prendete il vostro progetto Web Service Client. Se utilizzate Eclipse, installate il plugin di integrazione con Maven e convertite il progetto che avete creato a progetto Maven. Per fare questo dovete posizionarvi sul progetto fare tasto destro Configure – Convert to Maven Project. Verrà creato il pom.xml al quale dovete aggiungere la seguente dipendenza:
<groupId>com.smeup</groupId> <artifactId>wscspi</artifactId> <version>0.0.1-SNAPSHOT</version>
Se invece utilizzate NetBeans le ultime versioni hanno già integrato Maven. Dovrete quindi creare un nuovo progetto Maven, inserire i sorgenti e modificare il pom.xml come sopra.
Quindi create una classe che implementi l’interfaccia SPIWsCConnectorInterface.
I metodi da implementare risulteranno i seguenti:
init – metodo richiamato all’avvio del plugin in cui vengono istanziati dei valori uilizzati lungo tutto il ciclo di vita del plugin;
unplug – metodo per distruggere gli oggetti creati dalla classe. Questo metodo ha acquisito significato recentemente da quando lo Sme.UP Provider può rimanere dormiente, cioè inattivo rispetto all’AS400. Grazie a questa modalità non bisogna riavviare lo Sme.UP Provider tutte le volte che si riavvia l’AS400, ma il Provider quando si accorge che l’AS400 non risponde, rimane latente e richiama l’unplug di ogni suo Plugin per evitare problemi di allocazione della memoria;
invoke – Entry Point dove sono definite le funzioni e i metodi del web service client;
ping – metodo utilizzato per verificare che la classe sia attiva;
getSez – restituisce l’oggetto SezInterface, passato come primo parametro all’init.
Per poter effettuare dei test comodi lanciando semplicemente il plugin è utile che la classe abbia un main che ricalchi l’utilizzo del Web Service Client, per cui istanzi il connettore, richiami il metodo init e quindi il metodo invoke.
Per distribuire il progetto è sufficiente creare un jar e “pubblicarlo” nella cartella di installazione dello Sme.UP Provider sotto \libs\plugins
Debug del progetto
Se invece si vuole fare il debug del provider comprensivo del plugin bisogna scaricare dall’SVN il progetto del provider:
https://gilberto.smea.it/loocup/svn/loocup/branches/sviluppo
Nel Build Path del progetto SmeupDevSVN aggiungere ai Projects il progetto del Plugin.
Creare uno specifico file .launch con le corrette configurazioni nei seguenti tag:
<stringAttribute key="org.eclipse.jdt.launching.JRE_CONTAINER" value="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/jre1.8.0_77"/>
Va specificata la VM installata sulla macchina, ricordandosi che lo Sme.UP Provider necessita di una VM a 32 bit.
<stringAttribute key="org.eclipse.jdt.launching.PROGRAM_ARGUMENTS" value="<as400> <utente> <password> <ambiente> --server:<CODASERVER> --http:<PORTAHTTP>"/>
Vanno specificate le credenziali di accesso a Sme.UP ERP.
Script LOA38_XX
In Looc.UP è possibile navigare in questi script, tramite il tasto F4, inserendo i seguenti parametri:
Per esempio ES.S00.B00 questo script apparterrà al gruppo ES = Prototipo Web Services di esempio, avrà la sezione S00 e la sottosezione B00.
Nella sezione viene definita la CNFSEZ che è l’insieme dei parametri (nome/valore) che verranno passati all’init. Nella sottosezione vengono definite la SUBVAR e la MSGVAR. La SUBVAR è l’insieme dei parametri che verranno passati all’invoke, mentre la MSGVAR conterrà la struttura dati da passare all’evento asincrono che colloquia con Sme.UP ERP. Ci dovrà essere quindi corrispondenza tra la CNFSEZ e i parametri passati nell’init, tra la SUBVAR e i parametri passati nell’invoke e tra la MSGVAR e i parametri passati per istanziare la classe SPIWsCConnectorResponse.
Nella sottoscheda Network del costruttore, nella sezione “Simulazione chiamata Sub” è possibile testare le chiamate passando i parametri con la sintassi nome(valore).
Un esempio di script
Di seguito un esempio di script di LOA38, con gli elementi fondamentali ed, [IN GRASSETTO FRA PARENTESI QUADRE I COMMENTI ALLA SPECIFICA ]
* ============================================================== * MODIFICHE Ril. T Au Descrizione * gg/mm/aa nn.mm i xx Breve descrizione * xx/xx/17 V5.R1 FF - Speek *=============================================================== -- queue ::A38.SUPPRV DtaQ="PROTST" Active="1" [QUESTA E' LA SPECIFICA CHE ASSEGNA LO SCRIPT AL PROVIDER CHE DOVRA' ATTIVARE IL PLUGIN] -- Sezione ::SEZ Cod="S00" Txt="Speek" [QUI VIENE BATTEZZATA LA SEZIONE, INDICANDO ANCHE UNA BREVE DESCRIZIONE] ::A38.CLSSEZ Class="com.smeup.wscspi.speekwsplugin.SPeekWSPlugin" Log="Yes" [QUI VIENE INDICATO IL PLUGIN JAVA, INSTALLATO NEL PROVIDER SUINDICATO, CHE VERRA' USATO PER GESTIRE LA RICHIESTA K11] ::A38.CNFSEZ Name="Endpoint" Value="https://api-staging.modefinancegate.com/api/v1/it/companies/" [QUI EVENTUALI PARAMETRI DI INIZIALIZZAZIONE DEL PLUGIN, NEL FORMATO NOME-VALORE. POSSONO ESSERCI DIVERSE RIGHE DI QUESTO TIPO, A SECONDA DEL PLUGIN. COSTITUISCONO LA STRUTTURA DATI PASSATA AL PLUGIN NEL METODO INIT] -- Sub B00 ::SUB Cod="B00" Txt="semaphore - restituisci il semaforo" [QUI VIENE BATTEZZATA LA SUBSEZIONE, INDICANDO ANCHE UNA BREVE DESCRIZIONE] ::A38.SUBMET Value="semaphore" Txt="Nome che identifica la funzione" [QUI VIENE ASSOCIATO IL NOME DEL METODO RICONOSCIUTO DAL PLUGIN, INDICANDO ANCHE UNA BREVE DESCRIZIONE] ::A38.SUBVAR Name="CF" Txt="codice fiscale" [ ] ::A38.SUBVAR Name="AuthMethod" Txt="basic / non-prempitive / universal" [ ] ::A38.SUBVAR Name="User" Txt="Utente" [LE SUBVAR IDENTIFICANO I POSSIBILI PARAMETRI DI INVOKE DEL PLUGIN, SONO CONTROLLATI DA K11 IN FASE DI RICHIESTA] ::A38.SUBVAR Name="Pwd" Txt="Password" [ ] ::A38.SUBVAR Name="Path" Txt="Cartella destinazione" [ ] ::A38.SUBVAR Name="FileName" Txt="nome del file" [ ]
Una volta creato o modificato lo script per far sì che il provider senta la modifica, quest’ultimo va riavviato.
Riflessioni finali
Ad un certo punto dell’implementazione vi troverete a domandarvi quale ruolo deve ricoprire il Plugin, cioè quanta intelligenza affidare al Plugin e quanta a Sme.UP ERP. Le strade che si aprono sono molteplici e le scelte naturalmente dipendono da molti fattori, tra cui il tipo di progetto e la complessità delle classi fornite dal Web Service Client.
Se si preferisce che il processo applicativo rimanga affidato a Sme.UP ERP il Plugin avrà il solo compito di trasferimento dei dati senza entrare nel merito delle sue logiche. In questo caso il SOAPHandler, di cui vi parlavo nel mio precedente articolo, ricopre un ruolo fondamentale perché permette di manipolare il messaggio SOAP sia in uscita sia in entrata. Quindi Sme.UP ERP potrebbe direttamente scrivere il body del messaggio e il Plugin, attraverso il SOAPHandler, lo potrà iniettare nel messaggio SOAP completo prima di inviarlo al Web Service.