Servicii Web de tip SOAP n JavaEE6

Web Service ca aplicatie Web

Un serviciu Web (Web Service) este o aplicatie Web de tip client-server, n care un server
furnizor de servicii (numit si "Service Endpoint") este accesibil unor aplicatii client (care nu sunt
de tip browser) pe baza adresei URL a serviciului. Serviciul Web si clientii si pot rula pe
platforme diferite si pot fi scrise n limbaje diferite,deoarece se comunic prin protocoale
standard HTTP, XML, SOAP, JSON, s.a. De aceea principalul merit al serviciilor Web este acela
c asigur interoperabilitatea unor aplicatii software implementate pe platforme diferite si cu
instrumente (framework-uri) diferite. In acelasi timp aplicatiile sunt slab cuplate (loosely
coupled), n sensul c mesajele schimbate sunt standard (self-contained) si oricare dintre
aplicatii nu presupune existenta la cellalt capt a altor facilitti dect cele continute n
standarde.
Furnizorul de servicii expune un API pe Internet, adic o serie de metode ce pot fi apelate de
clienti. Aplicatia client trebuie s cunoasc adresa URL a furnizorului de servicii si metodele prin
care are acces la serviciul oferit (nume, parametri, rezultat). Interfata API este limitat la cteva
operatii n cazul serviciilor de tip REST si nelimitat ca numr si ca diversitate a operatiilor n
cazul serviciilor de tip SOAP.
Diferenta dintre o aplicatie Web clasic si un serviciu Web const n principal n formatul
documentelor primite de client si a modului cum sunt ele folosite : ntr-o aplicatie Web clientul
primeste documente HTML transformate de un browser n pagini afisate, iar clientul unui
serviciu Web primeste un document XML (sau JSON) folosit de aplicatia client, dar care nu se
afiseaz direct pe ecran (dect n anumite programe de verificare a serviciilor Web).
Pentru comparatie vom folosi exemplul unui client care foloseste un browser pentru a intra
pe un site ca s afle rata de schimb ntre dou valute , dar o aplicatie de comert electronic va
apela un serviciu Web cu rate de schimb pentru a calcula si comunica clientilor suma de plata n
valuta local.
Din punct de vedere al tehnologiilor folosite exist dou tipuri de servicii Web:
- Servicii de tip REST ( RESTful Web Services), n care cererile de la client se exprim prin
comenzi HTTP (GET, PUT, POST,DELETE), iar rspunsurile sunt primite ca documente XML
sau JSON;
- Servicii de tip SOAP (Simple Object Access Protocol), n care cererile si rspunsurile au forma
unor mesaje SOAP (documente XML cu un anumit format) transmise tot peste HTTP. In astfel
de servicii furnizorul expune si o descriere a interfetei API sub forma unui document WSDL
(Web Service Description Language), care este tot XML si poate fi prelucrat de client. Un client
trebuie s cunoasc metodele oferite de ctre Service Endpoint, pe care le poate afla din
descrierea WSDL.
Serviciile de tip SOAP ofer mai mult flexibilitate, o mai bun calitate a serviciilor si
interoperabilitate dect serviciile REST si sunt recomandate pentru un API mai mare oferit
clientilor. Serviciile de tip SOAP pot fi combinate pentru realizarea de operatii complexe, ceea
ce a condus la o arhitectur orientat pe servicii (SOA=Service Oriented Architecture).
In JEE cele dou tipuri de servicii sunt numite JAS-RS (REST) si JAX-WS (SOAP), iar
JavaEE Tutorial contine o comparatie ntre avantajele si limitele fiecrei solutii si recomandri
privind alegerea uneia sau alteia.
Majoritatea serviciilor Web reale sunt de tip SOAP, dar exist si cteva servicii de tip REST
notabile : Amazon S3 (Simple Storage Service) pentru memorarea si regsirea de obiecte,
reteaua Twitter si alte site-uri de blog, n care se descarc fisiere XML n format RSS sau Atom
cu liste de legturi ctre alte resurse.
Ca exemple de servicii SOAP larg utilizate sunt servicii pentru rate de schimb ntre diferite
valute, servicii bancare pentru verificare si operare n conturi (de ctre aplicatii Web de comert
electronic, de exemplu), servicii de memorare si regsire date, s.a.
Exist mai multe instrumente software pentru dezvoltarea de servicii Web pe platforma Java,
dintre care mai cunoscute sunt:

CXF (fost XFire) (Apache)

Metro (Sun) pentru servicii SOAP
Axis (Apache)
Jersey (Sun) pentru servicii REST
SoapUI este cel mai cunoscut instrument pentru simularea unui client de servicii Web (prin
afisarea cererilor client si rspunsurilor primite), pentru testarea si dezvoltarea de servicii SOAP
si REST.
Site-ul Xmethod.com contine o lista de servicii Web (de tip SOAP) publice si gratuite, cu
adresele descrierilor WSDL, care pot fi folosite n SoapUI pentru exersarea metodelor oferite.
Servicii Web de tip SOAP
Probleme de implementare a serviciilor Web de tip SOAP
Un serviciu Web de tip SOAP este versiunea modern a unui apel de proceduri la distant
(numite RPC=Remote Procedure Call sau RMI=Remote Method Invocation), cu diferenta c
datele schimbate ntre client si server sunt documente XML n locul fisierelor binare care
respectau si ele anumite conventii (protocolul RMI-IIOP sau CORBA sau alt protocol).
Ca si n orice apel de proceduri la distant, o functie (metod) dintr-un calculator (care se
execut ntr-o masin virtual Java) apeleaz o functie (o metod) aflat ntr-un alt calculator
(n alt masin virtual Java) folosind urmtoarele operatii:
- Un soft din masina client transform apelul si parametrii si ntr-un sir de octeti, deci face o
serializare a acelui apel (care poate necesita si serializarea parametrilor de un tip clas);
- Un alt soft din masina client (numit si proxy sau stub) transmite sirul de octeti rezultat din
serializare ctre masina server, folosind protocolul standard HTTP;
- Un soft din masina server (numit si ties) receptioneaz apelul serializat;
- Un alt soft din masina server transform sirul de octeti ntr-un apel efectiv de metod
Rezultatul apelului este si el serializat si trece prin aceleasi faze ca si apelul metodei.
Serviciile Web de tip SOAP folosesc pentru serializare fisiere text bazate pe XML.

In plus, exist si problema modului n care un client afl ce metode sunt disponibile n
serviciul oferit si detaliile de apelare pentru aceste metode. Solutia (partial) a acestei probleme
este un descriptor al serviciului Web aflat pe server si care poate fi citit de client. In cazul
serviciilor SOAP acesta este tot un document XML numit WSDL (Web Service Description
Language) si care poate fi obtinut de clienti de la o adres public URL.
S-a propus existenta unor registre publice care s centralizeze toate adresele URL de
servicii web disponibile (unde se afl wsdl-ul serviciului) si chiar s-a standardizat modul de
acces si de publicare n aceste registre UDDI (Universal Description, Discovery and Integration)
dar momentan nu exist astfel de registre.
Standardul WS-I Basic Profile 1.1 (Web Services- Interoperability) specific cerintele impuse
implementrilor de servicii Web pentru a asigura interoperabilitatea lor. Printre aceste cerinte
este si formatul fisierelor WSDL care descriu serviciile.
JAX-WS 2.0 este cea mai recent ncercare de unificare (de standardizare) a implementrii
serviciilor Web bazate pe SOAP si este incorporat n produse ca Metro (Sun), Axis2 (Apache),
CXF (Apache) s.a. JAX-WS standardizeaz adnotri Java utilizate n scrierea codului pentru
serviciu si pentru clienti, precum si artefacte portabile. Prin artefacte se nteleg fisierele Java si
XML necesare pentru implementarea unui serviciu Web si care sunt asamblate ntr-o arhiv
instalat (deployed) pe server.
Serviciile JAX-WS pot fi de dou feluri:

- Orientate pe mesaje (message-oriented);

- Orientate RPC (cu apeluri de proceduri)
Numrul si continutul concret al artefactelor cerute de un serviciu Web depind de fiecare
implementare, iar unele pot fi generate folosind anumite utilitare sau un framework cum este
SOAP-UI. De asemenea sunt diferente ntre formatul arhivelor in care sunt mpachetate aceste
artefacte pentru a fi instalate pe un server Web (de obicei un server de servleti).
Crearea unui serviciu Web poate porni de la un WSDL existent (top-down) sau de la un
program surs Java (bottom-up) din care se creeaz WSDL.
JAX-WS prevede cteva utilitare pentru dezvltarea de servicii Web:
- apt (Adnotations Processing Tool) : genereaz artefacte portabile din adnotri;
- wsgen care genereaza WSDL si alte artefacte din clasa care implementeaz SEI;
- wsimport care foloseste WSDL pentru generarea de cod Java si alte artefacte necesare att
furnizorului ct si clientilor de servicii JAX-WS.
Implementarea care porneste de la WSDL se numeste si contract-first pentru c acest
WSDL este pivit ca un contract ntre furnizorul serviciului si clientii serviciului.
Furnizorul de servicii (Service Endpoint) expune o interfat cu serviciile oferite clientilor, sub
forma unei interfete Java (SEI=Service Endpoint Interface) si a unor clase care implementeaz
aceast interfat. In plus, este creat de obicei si un fisier WSDL care descrie operatiile oferite de
SEI, fisier folosit de clienti pentru a genera cereri la serviciile oferite. Fisierul WSDL este o
modalitate de transmitere a interfetei SEI ctre aplicatii client.
Mai nou, aceste componente se numesc JAX-WS run-time si fac parte din artefactele care
trebuie generate in procesul de implementare al unui serviciu Web si al unui client pentru acest
serviciu:
Client WS run-time SOAP Message WS run-time Service
O versiune mai complet pentru secventa de la client la furnizorul de servicii arat astfel:
Client Handler Transport Sender SOAP Transport Listener Handler Service
Interceptorii (numiti si Handlers) prelucreaz de obicei partea de antet din mesajele SOAP si
pot asigura diverse functii, cum ar fi securitatea transmiterii mesajelor.
Implementarea protocolului SOAP la server si la client presupune trecerea ntre clase Java si
documente XML, n ambele sensuri. In acest scop se folosesc mai multe solutii, dintre care
parsere de documente XML de tip STAX, DOM s.a. si, mai recent, JAXB (Java API for XML
Binding), folosit de JAX-WS.
JAXB transform documente XML n obiecte Java si invers folosind schema ce descrie
documentul XML.
Utilitarul xjc este un compilator de schem XML care produce fabrici de obiecte Java
(Object Factories), iar utilitarul schemagen genereaz schema XML din clase Java adnotate.
Componenta run-time JAXB produce documente XML din obiecte JAXB (operatie numit
marshalling) si genereaz obiecte JAXB din documente XML (operatia de unmarshalling).
Protocolul SOAP
Protocolul SOAP este astzi unanim folosit n aplicatii de tip servicii Web si nlocuieste
protocoale mai vechi de comunicare ntre obiecte aflate pe masini diferite ca IIOP(RMI),
CORBA, DCOM, JAX-RPC s.a.
Intre clientul unui serviciu Web si furnizorul serviciilor se schimb mesaje SOAP, indiferent de
modul cum au fost implementate cele dou prti.
Un mesaj SOAP este un document XML cu o anumit structur. Mesajele SOAP au o parte
care nu poate lipsi (SOAP Part) si o parte atasat, optional (Attachements).
Partea fix contine o anvelop (SOAP Envelope), anvelop care contine o parte optional de
antet (SOAP Header) si o parte obligatorie de corp mesaj (SOAP Body) :

SOAP message
SOAP part
SOAP envelope
SOAP header (optional)
Header
Header
SOAP body
XMLContent
SOAP Fault

Fiecare din prtile atasate contine o parte de antete MIME si o parte de continut (XML sau
non-XML):
Attachement Part
MIME Headers
Content
Fisierele atasate pot fi imagini sau alte tipuri de fisiere transmise mpreun cu cereri ctre
servicii Web (in SOAP 1.2).
Exist un API Java, numit SAAJ (SOAP with Attachements API for Java), care permite
crearea (producerea) si folosirea (consumarea) de mesaje SOAP. Este un API de nivel cobort,
care este folosit de JAX-WS API, dar poate fi folosit si direct (exist exemple de utilizare n
JEE5 Tutorial).
WSDL ca limbaj pentru descrierea de servicii Web
WSDL foloseste urmtoarele elemente (taguri) pentru descrierea unui serviciu Web:
<types> Tipuri de date folosite de serviciul Web
<message> Mesaje folosite de serviciul Web
<portType> Operatii realizate de serviciul Web
<binding> Protocoale de comunicatii folosite de serviciul Web

Orice document WSDL are structura urmtoare:

<definitions>
<types>
definition of types........
</types>
<message>
definition of a message....
</message>
<portType>
definition of a port.......
</portType>
<binding>
definition of a binding....
</binding>
</definitions>

Fragment dintr-un document WSDL simplificat:

<message name="getTermRequest">
<part name="term" type="xs:string"/>
</message>
<message name="getTermResponse">
<part name="value" type="xs:string"/>
</message>

<portType name="glossaryTerms">
<operation name="getTerm">
<input message="getTermRequest"/>
<output message="getTermResponse"/>
</operation>
</portType>

Marcajele <operation> corespund numelor de metode oferite de serviciul Web.

Marcajul <binding> defineste formatul mesajelor si protocolul folosit. Marcajul <soap:binding>
are dou atribute: stil si transport; stilul poate fi rpc sau document, iar transportul este de
obicei HTTP. Exemplu:
<binding type="glossaryTerms" name="b1">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
<operation>
<soap:operation soapAction="http://example.com/getTerm"/>
<input><soap:body use="literal"/></input>
<output><soap:body use="literal"/></output>
</operation>
</binding>

Un exemplu complet de WSDL pentru un serviciu cu o singur metod (sayHello):

<definitions name="HelloService"
targetNamespace="http://www.examples.com/wsdl/HelloService.wsdl"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="http://www.examples.com/wsdl/HelloService.wsdl"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<message name="SayHelloRequest">
<part name="firstName" type="xsd:string"/>
</message>
<message name="SayHelloResponse">
<part name="greeting" type="xsd:string"/>
</message>
<portType name="Hello_PortType">
<operation name="sayHello">
<input message="tns:SayHelloRequest"/>
<output message="tns:SayHelloResponse"/>
</operation>
</portType>
<binding name="Hello_Binding" type="tns:Hello_PortType">
<soap:binding style="rpc"
transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="sayHello">
<soap:operation soapAction="sayHello"/>
<input>
<soap:body
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="urn:examples:helloservice"
use="encoded"/>
</input>
<output>
<soap:body
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="urn:examples:helloservice"
use="encoded"/>

</output>
</operation>
</binding>
<service name="Hello_Service">
<documentation>WSDL File for HelloService</documentation>
<port binding="tns:Hello_Binding" name="Hello_Port">
<soap:address
location="http://www.examples.com/SayHello/">
</port>
</service>
</definitions>

Observatii:
- Elementul <types> lipseste deoarece se folosesc tipuri predefinite n schema XML (xsd:string)
- Mesajele schimbate sunt:
sayHelloRequest, cu parametrul firstName (de tip xsd:string)
sayHelloResponse, cu rezultatul greeting (de tip xsd:string)
- Numele metodelor expuse: sayHello (<portType> .. <operation>)
- Protocol SOAP peste HTTP (<binding>)
- Asocierea numelui cu adresa URI a serviciului (<service> ..<port> .. <soap:address>)
Documentele WSDL pot fi generate automat si sunt prelucrate de ctre JAXB astfel nct
programatorul unui furnizor sau unui client de serviciu JAX-WS nu lucreaz direct cu WSDL.
Programarea unui furnizor de servicii Web cu JAX-WS pornind de la Java
Se poate porni de la o component Java verificat local, la care se adaug adnotrile
necesare pentru a o transforma ntr-un serviciu web (@WebService). Se poate defini sau nu o
interfat pentru Service Endpoint si se poate genera sau nu fisier WSDL.
Adnotrile JAX-WS furnizeaz toate informatiile necesare pentru configurarea furnizorului de
servicii si pentru client, dar se recomand si crearea fisierului WSDL.
JAX-WS prevede dou posibilitti de definire a unui service endpoint, prin dou adnotri
diferite @WebService si @WebServiceProvider pentru clasa Java care defineste serviciul. Un
serviciu adnotat cu @WebService foloseste modelul RPC, iar un serviciu WebServiceProvider
foloseste modelul orientat pe mesaje (pe documente).
Metodele unei clase serviciu pot fi adnotate cu @WebMethod si pot arunca exceptii
java.rmi.RemoteException.
Exemplu de clas care implementeaz un furnizor de servicii JAX-WS (Service Endpoint)
cu o singur metod sayHello:
package helloservice.endpoint;
import javax.jws.WebService;
import javax.jws.webMethod;
@WebService
public class Hello {
private String message=newString("Hello, ");
public void Hello() { }
@WebMethod
public String sayHello (String name){
return message+name+ ".";
}
}
Programarea unui client pentru serviciul anterior necesit urmtoarele operatii:
- Utilizarea clasei generate helloservice.endpoint.HelloService, pentru care adnotarea
@WebServiceRef injecteaz un obiect si pune adresa lui n variabila service:
@WebServiceRef(wsdlLocation="META-INF/wsdl/localhost_8080/helloservice/HelloService.wsdl")
privatestaticHelloServiceservice;

- Obtinerea unei clase Proxy a serviciului (un port) prin metoda getHelloPort, clas care
implementeaz interfata SEI a serviciului:
helloservice.endpoint.Helloport=service.getHelloPort();

- Apelul metodelor din interfata SEI prin obiectul proxy:

String result=port.seyHello (world);

package appclient;
import helloservice.endpoint.HelloService;
import javax.xml.ws.WebServiceRef;
public class HelloAppClient {
@WebServiceRef(wsdlLocation=
"META-INF/wsdl/localhost_8080/helloservice/HelloService.wsdl")
private static HelloService service;
public static void main(String[] args) {
System.out.println(sayHello(args[0]));
}
private static String sayHello (arg){
helloservice.endpoint.Helloport=service.getHelloPort();
return port.sayHello(arg);
}
}
Exemplu de client Web al unui serviciu Web, sub forma unui servlet:
@WebServlet(name="HelloServlet",urlPatterns={"/HelloServlet"})
public class HelloServlet extendsHttpServlet {
@WebServiceRef(wsdlLocation= "WEB-INF/wsdl/localhost_8080/helloservice/HelloService.wsdl")
private HelloService service;
protected void processRequest (HttpServletRequestrequest, HttpServletResponseresponse)
throwsServletException,IOException{
response.setContentType("text/html;charset=UTF-8");
PrintWriterout=response.getWriter();
try {
out.println("<html>"); out.println("<body>");
out.println("<h1>ServletHelloServletat " + request.getContextPath()+ "</h1>");
out.println("<p>" +sayHello("world")+ "</p>");
out.println("</body>"); out.println("</html>");
} finally { out.close(); }
}
//doGet and doPost methods,which call processRequest,and getServletInfo method
private String sayHello(String arg) {
helloservice.endpoint.Helloport=service.getHelloPort();
return port.sayHello(arg);
}
}

WS* ca etap superioar de dezvoltare a serviciilor Web

WS* completeaz specificatiile pentru servicii Web SOAP cu urmtoarele specificatii:
- WS Addressing
- WS Policy
- WS Security
- WS Optimization
- WS Reliable Messaging

Firma Sun a lucrat mpreun cu firma Microsoft pentru implementarea acestor specificatii cu
pstrarea interoperabilittii dintre serviciile Web realizate cu Metro si respectiv cu .NET3.5
(WCF= Windows Communication Foundation), ntr-un proiect numit WSIT (Web Service
Interoperability Technology). Compatibilitate nseamn c un client Metro poate accesa si poate
consuma servicii oferite de un furnizor WCF si un client WCF poate folosi servicii WCF.

BIBLIOGRAFIE:
Sun : JEE6 Tutorial
Apache : JAX-WS Guide (Axis2 Doc)
Sun : Documentatie Metro
SOApUI UserGuide