WebServices in Domino - Cosa sono ? - prima parte

Qualcuno di voi sicuramente ne avrà sentito parlare, ma molti di voi non sanno nemmeno cosa siano..
Questo articolo vuole chiarire un po' di aspetti sulle Web Services e vuole far capire come implementarle in Lotus Domino.

A) COSA SONO LE WEB--SERVICE?

Come dice la terminologia stessa, Webservices sono dei servizi WEB.
Questi "servizi" permettono di ottenere dei risultati ad una richiesta fatta sulla porta HTTP di Domino quindi ciò significa il poter interagire con Domino sulla sola porta 80.
Praticamente si avrà un "Provider" che contiene le Web-services (nel nostro caso Lotus Domino) che accetterà messaggi SOAP (La richiesta SOAP è un particolare tipo di comunicazione "XML" per interagire con WebServices) alle quali Domino risponderà sempre con una risposta SOAP.

Prima della versione 7 di Domino era necessario creare degli agenti in grado di rispondere alle chiamate SOAP.
Inoltre era necessario crearsi delle pagine WSDL per descrivere la struttura di una Web-services.

Dalla Versione 7 di Domino è stato realizzato un oggetto particolare nel designer di un database in grado di gestire queste richieste e questo tipo di comunicazioni tutto in maniera più semplificata ed integrata (il solo fatto della generazione automatica di oggetti WSDL è un gran vantaggio in fase di sviluppo)

Per comprendere meglio l'utilizzo di una Web-service vi proporrò un esempio di utilizzo.
[.....
Pensate ad un database Notes in grado di gestire il magazzino codificato di materiale informatico.
Bene ...ovviamente questo database avrà tutte le sue funzioni native  LS/formulas di carico, scarico, giacenza materiale etc...e vivrà tranquillamente di vita propria in una piattaforma Notes/Domino.

Ora pensate di realizzare una sorta di connettore in grado di poter interrogare il database remotamente da un qualsiasi client autorizzato, per capire se un certo tipo di materiale lo avete in giacenza o meno...ma no vogliate fare in modo che i Vs clienti abbiano necessariamente installato Lotus Notes sui loro client, ma una qualsiasi applicazione in grado di interfacciarci ed effettuare chiamate  RPC (Remote Procedure Call)

Con l'utilizzo delle Webservices potrete risolvere questa situazione...praticamente potrete realizzare in Domino degli Agenti  al cui interno vi sono delle funzioni LS che possono essere invocate semplicemente da una chiamata sulla porta 80 (SOAP) e che diano come risposta una stringa di risposta SOAP  al cui interno vi sia la risposta con la giacenza di quel determinato articolo (anche questa sarà una risposta SOAP)

L'agente (Web-services) avrà al suo interno una funzione con il seguente prototipo
Function VerificaGiacenza (codice_art as string) as string
che non farà altro che decodificare la richiesta SOAP in entrata , successivamente interrogare tramite una vista interna al DB con un GetdocumentbyKey (codice_art )e rispondere al client chiamante con un messaggio SOAP in uscita (la stringa di ritorno della funzione stessa)
...]

1. Immagine esempio presa da un tutorial IBM che chiarifica come avviene la comunicazione

B) COS'E' E COM'E STRUTTURATO UN WSDL?

Un WSDL è quel documento che descrive la struttura di una WEB SERVICE.
Solo questo documento permette ad un client di capire quali funzioni ci sono e quali parametri passano e restituiscono le varie funzioni implementate in una Web-service.

E' un specie di protocollo che basta leggerlo per capire con quali metodi e con quali parametri avverrà la comunicazione.
Bisogna pensarlo come ad una sorta di guida programmativa per gestire le Web-service.
Ovviamente bisogna ache saperlo interpretare e per fare ciò vi  allego un esempio di documento WSDL.

(Fino alla release 6.x, il document WSDL bisognava generarlo a mano mettendolo in una pagina di Designer e poi aprendolo con ?OpenPage da Web.
Dalla release 7.x non serve generarlo, ma basta inserire il percorso della WEBSERVICE ed utilizzare il comando ?WSDL. Il tutto è gestito automaticamente da Domino)

** ** MESSAGGI IN ENTRATA ED USCITA CON RELATIVI PARAMETRI ** <wsdl:message name="RichiestaGiacenza"> <wsdl:part name="CODICE_ART" type="xsd:string" /> </wsdl:message> <wsdl:message name="RispostaGiacenza"> <wsdl:part name="GIACENZA" type="xsd:string" /> </wsdl:message> *** *** in PORTTYPE si dichiarano tutte le operazioni (funzioni) che gestisce la Web Services ed i loro parametri d'ingresso (La funzione VerificaGiacenza dichiarata in Domino) *** <wsdl:portType name="ControllaGiacenza"> <wsdl:operation name="VerificaGiacenza" parameterOrder "CODICE_ART"> <wsdl:input message="impl:RichiestaGiacenza" name="RichiestaGiacenza" /> <wsdl:output message="impl:RispostaGiacenza" name="RispostaGiacenza" /> </wsdl:operation> </wsdl:portType> **** **** SI DEFINISCE IL TIPO DI INTERAZIONE (RPC) E PROTOCOLLO DI TRASPORTO USATO(HTTP) **** <wsdl:binding name="DominoSoapBinding" type="impl:ControllaGiacenza"> <wsdlsoap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http" />   *** *** Per ogni messaggio di input ed output si stabilisce il tipo di codifica (nel nostro caso SOAP adottando il tipo di schema) *** <wsdl:operation name="VerificaGiacenza"> <wsdlsoap:operation soapAction="" /> <wsdl:input name="RichiestaGiacenza"> <wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="urn:DefaultNamespace" use="encoded" /> </wsdl:input> <wsdl:output name="RispostaGiacenza"> <wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"      namespace="urn:DefaultNamespace" use="encoded" /> </wsdl:output> </wsdl:operation> </wsdl:binding> *** *** IL NOME DELLA WEBSERVICE e l'indirizzo di riposta/esecuzione della stessa(endpoint) *** <wsdl:service name="ControlloMagazzino"> <wsdl:port binding="impl:DominoSoapBinding" name="Domino"> <wsdlsoap:address location="http://path_domino/Webservices.nsf/VerificaGiacenza?OpenWebService" /> </wsdl:port> </wsdl:service>

C) COS'E' E COM'E STRUTTURATO UN MESSAGGIO SOAP ?

Un messaggio SOAP non è nient'altro che l'esecuzione e la risposta di una WEB-SERVICE.
WDSL è quel documento che descrive la STRUTTURA della WEBSERVICE nel suo intero, mentre SOAP è la stringa di comunicazione con cui vengono mandate le richieste e con cui arrivano le risposte dal server.
Nel nostro esempio un tipo di risposta SOAP potrebbe essere:

<?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <ns1:RispostaGiacenza soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns1="urn:DefaultNamespace"> <GIACENZA xsi:type="xsd:string">10</GIACENZA> </ns1:RispostaGiacenza> </soapenv:Body> </soapenv:Envelope>

In prarica la WEB services risponde al client con un messaggio che dice che il CAMPO GIACENZA =10.

Fine Prima parte....

( nel prossimo articolo vedremo come creare un db magazzino con la web service in domino e come testare
il suo funzionamento)

Per comprendere meglio le specifiche SOAP, WSDL, XML rimando alla lettura di questi LINK