Web Service SOAP e WSDL. Tito Flagella tito@link.it Lorenzo Nardi nardi80@gmail.com

Transcript

1 Web Service SOAP e WSDL Tito Flagella tito@link.it Lorenzo Nardi nardi80@gmail.com

2 SOAP Originariamente: Simple Object Access Protocol E poi evoluto in un Framework per lo scambio di messaggi in XML 2

3 SOAP (2) Le caratteristiche principali del framework sono: L estendibilità L indipendenza dal protocollo di rete L indipendenza dal modello di programmazione 3

4 La struttura del messaggio SOAP Un messaggio SOAP consiste di: Envelope, identifica il contenuto del messaggio e include: Header, opzionali, contengono informazioni relative al messaggio (meta) Body, contiene i documenti XML di richiesta o di risposta 4

5 Struttura di un messaggio SOAP <?xml version= 1.0?> <soap:envelope xmlns:soap= envelope/ > <soap:header> (opzionale) </soap:header> <soap:body> (payload obbligatorio) </soap:body> </soap:envelope> 5

6 SOAP: Header e Body Supponiamo di inviare i dati di un'ordine. I dati veri e propri (dettagli degli articoli, indirizzo di spedizione,...) saranno inseriti nel body. I metadati (security, routing,...) saranno inseriti nell'header Oltre alla merce scelta, inviamo i dati per il pagamento. Cifriamo questo dato in modo che l'unico in grado di leggerlo sia la Banca. 6

7 Gli Header SOAP (1) Il rivenditore legge le informazioni di suo interesse, poi si occuperà di effettuare il routing del messaggio alla banca per le operazioni di pagamento Dobbiamo indicare che l'header di sicurezza è per la banca e che DEVE essere processato, altrimenti i dati cifrati sono illeggibili 7

8 Gli Header SOAP (2) A questo scopo gli header hanno due attributi: mustunderstand, che può assumere i valori: 1, indica che il ricevente deve sapere gestire l Header, altrimenti deve restituire un messaggio di Fault 0, o attributo non presente, indica che il ricevente può ignorare l Header e continuare nella gestione del messaggio. l actor che specifica l URI dell endpoint che deve gestirlo. 8

9 Versioni SOAP SOAP 1.1 Definito nello schema: SOAP 1.2 Definito nello schema: 9

10 SOAP Protocol Binding SOAP è indipendente dal protocollo di trasporto utilizzato; Per favorire l interoperabilità è necessario standardizzare come i messaggi SOAP siano veicolati in un certo protocollo 10

11 SOAP http binding 11

12 WSDL Web Services Description Language Definizione neutra di un Web Service rispetto a linguaggio e piattaforma Descrive completamente il servizio Web: Tipi di dati usati nei messaggi Formato dei Messaggi Descrizione delle Operazioni in termini di sequenza di messaggi Binding tra le operazioni e il trasporto Indirizzo fisico dei servizi da utilizzare Definito dallo schema XML: Riferimento: 12

13 Struttura di un file WDSL L elemento top level XML è definitions La descrizione del web service è articolata in una parte astratta e una parte concreta: <definitions name="ordiniservice" targetnamespace=" xmlns=" > <!-- abstract definitions --> <types>... <message>... <porttype>... <!-- concrete definitions --> <binding>... <service>... </definition> 13

14 Struttura di un file WDSL (2) La parte astratta include: Types: descrivono il formato dei dati usati (Schema) Message: definizione dei dati trasmessi in un messaggio Operation: ogni operazione può avere un messaggio di input e/o uno di output porttype: l insieme di operazioni del Servizio (interfaccia) La parte concreta include: Binding: informazioni concrete sul protocollo da utilizzare per uno specifico porttype Port: specifica l indirizzo fisico per il binding del servizio Service: usato per aggregare un insieme di Port correlate 14

15 Caso d uso: Sottomissione di un ordine Il servizio esposto dal rivenditore riceve un ordine e risponde con un esito 15

16 WSDL Types Usano gli schemi XML per definire i tipi e gli elementi usati nel documento WSDL. Abbiamo già descritto i tipi che ci servono. Non ci resta che importarli. <wsdl:definitions... xmlns:sotype=" > <wsdl:import namespace=" location="ordini.xsd">... </wsdl:definitions> 16

17 ordini.xsd <xs:schema xmlns:xs=" targetnamespace=" xmlns:sotype=" <xs:complextype name="ordinetype"> <xs:sequence maxoccurs="unbounded"> <xs:element name="articolo" type="sotype:articolotype"/> </xs:sequence> </xs:complextype> <xs:complextype name="articolotype"> <xs:sequence> <xs:element name="codice" type="sotype:codicetype"/> <xs:element name="quantita" type="xs:positiveinteger"/> </xs:sequence> </xs:complextype> <xs:simpletype name="codicetype"> <xs:restriction base="xs:string"> <xs:pattern value="[a-z][a-z][0-9]{4}"/> </xs:restriction> </xs:simpletype>... </xs:schema> 17

18 WSDL Types Per i tipi mancanti possiamo definire lo Schema dentro il tag types <wsdl:types> <xsd:schema targetnamespace=" xmlns:sotype=" <xsd:element name="notifica" type="xsd:string"/> <xsd:element name="esito" type="sotype:esitotype"/> <xsd:element name="ordine" type="sotype:ordinetype"/> </xsd:schema> </wsdl:types> 18

19 WSDL Message Gli elementi message definiscono il formato dei messaggi elementari di input o di output di una operation <wsdl:definitions xmlns:ele=" <wsdl:message name="submitordinerequest"> <wsdl:part name="parameter" element="ele:ordini"/> </wsdl:message> <wsdl:message name="submitordineresponse"> <wsdl:part name="parameter" element="ele:esito"/> </wsdl:message> <wsdl:message name="notificamessage"> <wsdl:part name="parameter" element="ele:notifica"/> </wsdl:message> </wsdl:definitions> 19

20 WSDL Operation Una operation corrisponde ad uno scambio di messaggi Una stessa interazione tra due nodi può essere mappata su operation diverse. Esempio Logica Sincrona: <definitions... <operation name= submitordine"> <input message="submitordinerequest "/> <output message= submitordineresponse"/> </operation>... </definitions> Esempio Logica Asincrona: <definitions... <operation name= submitordine"> <input message="submitordinerequest "/> </operation> <operation name= esitoordine"> <output message="submitordineresponse "/> </operation>... </definitions> 20

21 WSDL Operation Le operazioni posso essere quindi: One-way, un unico messaggio di input Request-response, un messaggio di input seguito da un messaggio correlato di output Solicit-response, un messaggio di output seguito da un messaggio di input Notification, un unico messaggio di output 21

22 WSDL PortType porttype, individua l insieme di operazioni accessibili: <wsdl:porttype name="ordineinterface"> <wsdl:operation name="submitordine">... </wsdl:operation> <wsdl:operation name="notifica">... </wsdl:operation> </wsdl:porttype> In WSDL 1.2 "porttype" è sostituito da "interface" 22

23 WSDL Binding Binding: indica come i messaggi di una operation saranno effettivamente trasmessi via rete Il Binding si riferisce ad uno specifico porttype, tramite l'elemento type Nel caso di SOAP, conterrà un elemento soap:binding Ulteriori informazioni sulle modalità di trasmissione sono specificate tramite l elemento operation <wsdl:binding name="ordineinterfacebinding" type="ordineinterface"> <soap:binding style=".." transport=".."/> <wsdl:operation name=".."> <wsdl:input>... </wsdl:input> <wsdl:output>... </wsdl:output> </wsdl:operation> </wsdl:binding> 23

24 SOAP Binding L'elemento SOAP binding permette di specificare: style: può essere rpc o document trasport: il tipo di protocollo usato per il trasporto Esempio di binding SOAP, su http e stile document <wsdl:binding name="ordineinterfacebinding" type="ordineinterface"> <soap:binding style="document" transport=" <wsdl:operation name="submitordine">... </wsdl:operation>... </wsdl:binding> 24

25 SOAP Binding Style RCP: indica che il body del messaggio SOAP contiene un elemento (wrapper) con il nome dell'operation invocata; questo elemento include poi il messaggio di input associato all'operation; la risposta è strutturata allo stesso modo, e contiene il messaggio di output di questa operation (metafora della chiamata di procedura). Document: in questo stile non c è un elemento wrapper che codifica l invio dei dati. Invece le parti del messaggio appaiono nel <soap:body> come documento xml esattamente come specificato nel file WSDL. 25

26 WSDL binding: operation L'elemento soap:operation permette di specificare: L'header http soapaction La codifica dei messaggi di input e output <wsdl:binding name="ordineinterfacebinding" type= ordineinterface">... <wsdl:operation name="submitordine"> <soap:operation soapaction="..."/> <wsdl:input> <soap:body use="literal"/> </wsdl:input> <wsdl:output> <soap:body use="literal"/> </wsdl:output> </wsdl:operation>... </wsdl:binding> 26

27 L elemento SOAP Body I elemento soap:body può assumere valore literal o encoded Encoded, il contenuto del messaggio è serializzato in xml usando le codifiche di serializzazione per oggetti, strutture, array, etc. previste nelle specifiche SOAP Literal, il contenuto del messaggio è serializzato in XML usando le stesse specifiche XML del file WSDL e degli schemi XML utilizzati 27

28 4 possibili schemi di codifica soap:binding/soap:body: Rpc/encoded (Deprecato) Rpc/literal Document/encoded (mai usato) Document/Literal 28

29 Esempio codifica RPC/literal <soap:envelope xmlns:soap="..."> <soap:body> <addordine xmlns=" <ordine> <articolo> <codice>ab0001</codice> <quantita>1</quantita> </articolo> <articolo> <codice>ab0002</codice> <quantita>2</quantita> </articolo> </ordine> </addordine> </soap:body> </soap:envelope> 29

30 Esempio codifica document/literal <soap:envelope xmlns:soap="..."> <soap:body> <ordine xmlns=" <articolo> <codice>ab0001</codice> <quantita>1</quantita> </articolo> <articolo> <codice>ab0002</codice> <quantita>2</quantita> </articolo> </ordine> </soap:body> </soap:envelope> 30

31 Wrapped Document/Literal Analogo al Document/Literal, ma richiede un root element per ogni messaggio Si tratta di una convenzione nella definizione del WSDL Analogo a RPC/Literal se si usa un root element con lo stesso nome dell'elemento operation del WSDL 31

32 SOAP Port Element Port: specifica l indirizzo fisico per il binding del servizio L elemento Port è un framework generico per specificare i dettagli relativi allo specifico protocollo <wsdl:port name="ordineinterfaceendpoint" binding="ordineinterfacebinding"> <soap:address location=" </wsdl:port> 32

33 SOAP Service element Service: usato per aggregare un insieme di Port correlate <wsdl:service name="ordiniservice"> <wsdl:port... >...</wsdl:port> <wsdl:port... >...</wsdl:port> </wsdl:service> 33

34 Applicazioni Web Services Approcci possibili: Programmazione Orientata agli Oggetti Bottom/Up: partire dal linguaggio di programmazione (a partire dall implementazione viene generato il WSDL del Servizio) Top/Down: partire dal WSDL (esistente o progettato ad-hoc) Programmazione Orientata al Messaggio XML Si lavora su oggetti SOAPMessage tramite parsing xml Ideale per implementare servizi generici indipendenti dal formato dei messaggi (es: firewall xml) 34

35 Java API for XML Web Service JAX-WS è una API per la creazione di Web Service (javax.jws.*). Java API for XML Web Services Per la manipolazione e la spedizione di SOAPMessage viene utilizzata SAAJ (Soap with Attachment API for Java) Legacy Web Services: Java API for XML-Based RPC (JAX-RPC) 35

36 Operation Level Service Programmazione Orientata agli Oggetti/Bottom-up Si parte da una interface in Java per la progettazione del servizio Si usano le annotazioni sull'interfaccia java per specificare le informazioni aggiuntive altrimenti contenute nel WSDL Il programmatore tratta il contenuto del messaggio come oggetti java Si effettua il deploy del servizio come un normale archivio WAR, eventualmente arricchito con file di configurazione dello specifico WS-Framework utilizzato Nota: nelle esercitazioni useremo CXF 36

37 Annotare l implementazione del servizio package lai.ws; public class Ordine { public void notifica(java.lang.string evento);... } package public class Ordine { public void notifica(java.lang.string parameter){... } } <soap:envelope xmlns:soap=" <soap:body> <ns1:notifica xmlns:ns1=" <arg0>pagato</arg0> </ns1:notifica> </Body> </Envelope> 37

38 Dettagliare il servizio package public class Ordine { public void notifica(@webparam(name="evento") java.lang.string parameter){... } } <soap:envelope xmlns:soap=" <soap:body> <ns1:notifica xmlns:ns1=" <evento>pagato</evento> </ns1:notifica> </Body> </Envelope> 38

39 Esempio completo package lai.ws; import = = SOAPBinding.ParameterStyle.BARE) public class Ordine = "Notifica") public void = "evento", targetnamespace = " java.lang.string parameter); } In Java non è possibile specificare tutti gli aspetti del WSDL, ad esempio le stringhe con restrizioni come il codice fiscale Per informazioni sulle annotazioni: 39

40 Operation Level Service (2) Programmazione Orientata agli Oggetti/Top-down Si parte dalla descrizione WSDL del servizio Si usano tool per la generazione automatica delle classi java complete delle annotazioni Jax-ws per rispettare il WSDL concordato. Wsdl2java -service -impl negozio.wsdl -service: genera lo skeleton del servizio -client: genera lo stub del servizio -impl: genera il codice di partenza per l implementazione Per maggiori informazioni sulle opzioni disponibili: 40

41 Message Level Service Programmazione Orientata al Messaggio XML Si usano le annotazioni attorno ad un unico metodo (invoke) che agisce su messaggi SOAP (SOAPMessage) Il programmatore tratta il contenuto del messaggio come un dato xml: riconosce l'operazione, valida il messaggio rispetto ai tipi public class Ordini implements Provider<SOAPMessage>{ public SOAPMessage invoke(soapmessage request) { SOAPMessage response = null;... return response; } } 41

42 Message Level Service (2) Agisce sull'oggetto SOAPMessage usando la API SAAJ: SOAPPart sp = message.getsoappart(); SOAPEnvelope se = sp.getenvelope(); SOAPBody sb = se.getbody(); SOAPHeader sh = se.getheader() SAAJ e basato sul DOM: org.w3c.dom.document dom = sb.extractcontentasdocument(); NodeList node = dom.getelementsbytagname("ordine"); 42

43 Client Anche il Client può fruire di due modalità di approccio ai Web Service Lavorando su oggetti Java puo' utilizzare il tool wsdl2java per ottenere gli stub attraverso i quali invocare il servizio. Lavorando sul messaggio XML puo' costruire il messaggio SOAP a partire dall'xml del body utilizzando SAAJ, spedendolo tramite l'oggetto Connection SOAPConnectionFactory scf = SOAPConnectionFactory.newInstance(); SOAPConnection con = scf.createconnection(); java.net.url endpoint = new URL(" SOAPMessage response = con.call(message, endpoint); 43