Serveis web SOAP amb Spring Web Services

Veurem els conceptes referents a la definició de serveis web SOAP amb Spring-WS desenvolupant un servei web SOAP amb Spring-WS que permeti consultar les dades d’una empresa per CIF.

Spring-WS ens obliga a utilitzar una estratègia Contract First per crear serveis web SOAP, això vol dir que primer descriurem els paràmetres i tipus de retorn del servei amb XSD, després utilitzarem aquest XSD per generar el document WSDL que serà el contracte públic del servei i, finalment, generarem les classes Java que implementaran el servei d’acord amb aquest contracte.

El projecte ja té el pom.xml preparat per poder desenvolupar el servei web amb Spring-WS; concretament, s’hi ha afegit aquestes dues dependències:

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-ws</artifactId>
</dependency>
<dependency>
	<groupId>wsdl4j</groupId>
	<artifactId>wsdl4j</artifactId>
</dependency>

Farem el desplegament del servei web creant una aplicació executable. Per fer el desplegament creant una aplicació executable que s’executarà al contenidor de servlets que Spring porta incorporat cal crear una classe Java anotada amb @SpringBootApplication amb un mètode main que cridi el mètode run de SpringApplication. Per fer-ho ja us hem creat la classe Application al paquet cat.xtec.ioc.service.impl amb el següent codi:

package cat.xtec.ioc.service.impl;
 
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
 
@SpringBootApplication
public class Application {
 
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

El fet d’anotar la classe amb @SpringBootApplication afegeix tota la configuració necessària per tal que l’aplicació pugui funcionar de forma autònoma.

El servei web SOAP que volem crear és molt senzill, tan sols ens ha de permetre consultar la informació d’una empresa d’un repositori d’empreses.

Com que crearem el servei web seguint una estratègia Contract First, el primer que ens cal fer és crear el document XSD que definirà el model de domini. El model de domini es defineix amb un fitxer d’esquema XML que després Spring-WS s’encarregarà d’exportar a WSDL.

La part principal del nostre model del domini serà l’entitat Company, que representarà les dades d’una empresa i la modelarem amb un document XSD. Per fer-ho creeu un fitxer anomenat company.xsd al directori /src/main/resources/ amb el següent contingut:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://cat.xtec.ioc/domain/company"
           targetNamespace="http://cat.xtec.ioc/domain/company" elementFormDefault="qualified">
 
    <xs:complexType name="company">
        <xs:sequence>
            <xs:element name="cif" type="xs:string"/>
            <xs:element name="name" type="xs:string"/>
            <xs:element name="employees" type="xs:int"/>
            <xs:element name="email" type="xs:string"/>
            <xs:element name="web" type="xs:string"/>
        </xs:sequence>
    </xs:complexType>
 
</xs:schema>

Fixeu-vos que es defineix un tipus XML complex per construir el model del domini; en aquest cas, un objecte company que conté el CIF, el nom, el nombre de treballadors, el correu i la pàgina web de l’empresa.

Un cop definida la nostra entitat del domini ens cal concretar els tipus de les peticions i les respostes del servei web que permetrà consultar la informació de l’empresa per CIF. Per fer-ho creeu un fitxer anomenat companyoperations.xsd al directori /src/main/resources/ amb el següent contingut:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://cat.xtec.ioc/domain/company/services"
           targetNamespace="http://cat.xtec.ioc/domain/company/services" xmlns:company="http://cat.xtec.ioc/domain/company" elementFormDefault="qualified">
    <xs:import namespace="http://cat.xtec.ioc/domain/company" schemaLocation="company.xsd"/>
    <xs:element name="getCompanyRequest">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="cif" type="xs:string"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
 
    <xs:element name="getCompanyResponse">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="company" type="company:company"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>    
 
</xs:schema>

Fixeu-vos que:

• S’importa la definició del tipus complex company que ha de tornar la resposta.
• Es defineix la petició com un tipus XML complex que conté la cadena on passarem el CIF de l’empresa de la qual volem consultar les dades.
• Es defineix la resposta també com un tipus XML complex que conté la informació de l’empresa consultada.

Per tal d’utilitzar els tipus que hem definit als fitxers XSD ens cal generar les classes Java per a aquests tipus. Spring-WS serà capaç de generar la classe Java Company que representa el model de domini i les classes Java que modelaran la petició (GetCompanyRequest) i la resposta (GetCompanyResponse) del servei web.

Aquesta és una part fonamental als serveis web SOAP: la conversió dels missatges SOAP d’XML cap a Java i a l’inrevés. Aquesta tasca no seria senzilla si l’haguéssiu de fer a mà, però Spring ho fa fàcil utilitzant el bastiment (framework, en anglès) JAXB, i ho farem en temps de construcció del projecte.

Això es pot fer de diverses formes; una manera senzilla és que ho faci el plugin de Maven jaxb-maven-plugin en temps de construcció del projecte. Afegiu les següents línies al fitxer pom.xml:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>jaxb2-maven-plugin</artifactId>
    <version>1.6</version>
    <executions>
        <execution>
            <id>xjc</id>
            <goals>
                <goal>xjc</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <schemaDirectory>${project.basedir}/src/main/resources/</schemaDirectory>
        <outputDirectory>${project.basedir}/src/main/java</outputDirectory>
        <clearOutputDir>false</clearOutputDir>
    </configuration>
</plugin>

Si recarregueu el pom.xml fent clic amb el botó dret damunt el nom del projecte i prement l’opció Reload POM del menú contextual i després feu Clean and Build, també al menú contextual de NetBeans, veureu com a la fase de generació el plugin xjc ha generat, a partir dels documents XSD de definició de servei, la classe Java que modela el domini i les classes Java que modelen la petició i la resposta del servei web (vegeu la figura).

--- jaxb2-maven-plugin:1.6:xjc (xjc) @ springsoapemptioc ---
Generating source...
Analizando un esquema...
Compilando un esquema...
ioc\xtec\cat\domain\company\services\GetCompanyRequest.java
ioc\xtec\cat\domain\company\services\GetCompanyResponse.java
ioc\xtec\cat\domain\company\services\ObjectFactory.java
ioc\xtec\cat\domain\company\services\package-info.java
ioc\xtec\cat\domain\company\Company.java
ioc\xtec\cat\domain\company\ObjectFactory.java
ioc\xtec\cat\domain\company\package-info.java

Ara toca crear el repositori d’on el servei ha de consultar la informació de les empreses. En el nostre cas, per simplicitat, farem servir un repositori in memory que tindrà una llista precarregada d’empreses i un mètode findCompany que permet consultar una de les empreses per CIF. Òbviament, en un projecte real la definició del servei serà molt més complexa!

Per fer-ho creeu una classe Java anomenada InMemoryCompanyRepository al paquet cat.xtec.ioc.domain.repository.impl amb el següent codi:

package cat.xtec.ioc.domain.repository.impl;
 
import ioc.xtec.cat.domain.company.Company;
import java.util.ArrayList;
import java.util.List;
import javax.annotation.PostConstruct;
import org.springframework.stereotype.Repository;
import org.springframework.util.Assert;
 
@Repository
public class InMemoryCompanyRepository {
 
    private static final List<Company> companies = new ArrayList<Company>();
 
    @PostConstruct
    public void initData() {
        Company oracle = new Company();
        oracle.setCif("XXXXXXXX");
        oracle.setName("Oracle");
        oracle.setEmployees(5000);
        oracle.setEmail("oracle@oracle.com");
        oracle.setWeb("http://www.oracle.com");
 
        companies.add(oracle);
 
        Company ms = new Company();
        ms.setCif("YYYYYYYY");
        ms.setName("Microsoft");
        ms.setEmployees(10000);
        ms.setEmail("microsoft@microsoft.com");
        ms.setWeb("http://www.microsoft.com");
 
        companies.add(ms);
 
        Company redhat = new Company();
        redhat.setCif("ZZZZZZZZ");
        redhat.setName("Red Hat");
        redhat.setEmployees(2000);
        redhat.setEmail("redhat@redhat.com");
        redhat.setWeb("http://www.redhat.com");
        companies.add(redhat);
    }
 
    public Company findCompany(String cif) {
        Assert.notNull(cif);
        Company result = null;
        for (Company company : companies) {
            if (cif.equals(company.getCif())) {
                result = company;
            }
        }
 
        return result;
    }
}

Amb tot això ja estem preparats per crear l’endpoint del servei web SOAP que tornarà la informació de les empreses. Noteu que, per sota, hi ha un servlet que s’encarrega de recollir les peticions SOAP que vagin al servei i les envia a l’endpoint per tal de processar-les.

Creeu una classe Java anomenada CompanyEndpoint al paquet cat.xtec.ioc.service.impl amb el següent codi:

package cat.xtec.ioc.service.impl;
 
import cat.xtec.ioc.domain.repository.impl.InMemoryCompanyRepository;
import ioc.xtec.cat.domain.company.services.GetCompanyRequest;
import ioc.xtec.cat.domain.company.services.GetCompanyResponse;
 
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.ws.server.endpoint.annotation.Endpoint;
import org.springframework.ws.server.endpoint.annotation.PayloadRoot;
import org.springframework.ws.server.endpoint.annotation.RequestPayload;
import org.springframework.ws.server.endpoint.annotation.ResponsePayload;
 
@Endpoint
public class CompanyEndpoint {
 
    private static final String NAMESPACE_URI = "http://cat.xtec.ioc/domain/company/services";
 
    private InMemoryCompanyRepository companyRepository;
 
    @Autowired
    public CompanyEndpoint(InMemoryCompanyRepository companyRepository) {
        this.companyRepository = companyRepository;
    }
 
    @PayloadRoot(namespace = NAMESPACE_URI, localPart = "getCompanyRequest")
    @ResponsePayload
    public GetCompanyResponse getCompany(@RequestPayload GetCompanyRequest request) {
        GetCompanyResponse response = new GetCompanyResponse();
        response.setCompany(companyRepository.findCompany(request.getCif()));
 
        return response;
    }
}

Fixeu-vos que:

• Hem injectat el repositori d’empreses al constructor del servei amb Spring.
• Hem anotat la classe amb @Endpoint per indicar a Spring que aquesta classe correspon a un endpoint d’un servei web SOAP i tindrà mètodes que serviran peticions SOAP. @Endpoint és una versió especialitzada de l’anotació @Component.
• TARGET_NAMESPACE representa l’espai de noms que heu definit anteriorment al document XSD. Es fa servir per mapar les peticions a mètodes específics de l’endpoint.
• Hem anotat el mètode getCompany amb l’anotació @PayloadRoot on es defineix l’espai de noms i el mètode que servirà les peticions de cerca d’empreses per CIF.
• El missatge SOAP que consulti una empresa per CIF haurà de fer referència al PayloadRoot especificat.
• Hem anotat el mètode amb @ResponsePayload per indicar que el mètode tornarà un objecte de tipus GetCompanyResponse amb la informació de l’empresa. Spring s’encarregarà de convertir aquest objecte a XML.
• El paràmetre del mètode l’hem anotat amb @RequestPayload per indicar que el missatge d’entrada serà de tipus GetCompanyRequest. Spring s’encarregarà de convertir el missatge XML d’entrada a un objecte d’aquest tipus.
• Tant el tipus de retorn com el paràmetre corresponen a classes generades automàticament en el procés de construcció a partir de la definició del fitxer d’esquema XML companyoperations.xsd.

Un cop creat l’endpoint del servei web SOAP tan sols ens queda configurar Spring per carregar tota la configuració. Això ho podeu fer de diverses maneres, ja sigui amb fitxers de configuració o amb anotacions a classes Java de configuració. A l’exemple utilitzarem aquesta darrera tècnica.

Creeu una classe Java anomenada WebServiceConfig al paquet cat.xtec.ioc.service.impl amb el següent codi:

package cat.xtec.ioc.service.impl;
 
import org.springframework.boot.web.servlet.ServletRegistrationBean;
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;
import org.springframework.ws.config.annotation.EnableWs;
import org.springframework.ws.config.annotation.WsConfigurerAdapter;
import org.springframework.ws.transport.http.MessageDispatcherServlet;
import org.springframework.ws.wsdl.wsdl11.DefaultWsdl11Definition;
import org.springframework.xml.xsd.SimpleXsdSchema;
import org.springframework.xml.xsd.XsdSchema;
 
@EnableWs
@Configuration
@ComponentScan("cat.xtec.ioc.service.imp, cat.xtec.ioc.domain.repository.impl")
public class WebServiceConfig extends WsConfigurerAdapter {
 
    @Bean
    public ServletRegistrationBean messageDispatcherServlet(ApplicationContext applicationContext) {
        MessageDispatcherServlet servlet = new MessageDispatcherServlet();
        servlet.setApplicationContext(applicationContext);
        servlet.setTransformWsdlLocations(true);
        return new ServletRegistrationBean(servlet, "/soapws/*");
    }
 
    @Bean(name = "companyoperations")
    public DefaultWsdl11Definition defaultWsdl11Definition(XsdSchema companiesSchema) {
        DefaultWsdl11Definition wsdl11Definition = new DefaultWsdl11Definition();
        wsdl11Definition.setPortTypeName("CompaniesPort");
        wsdl11Definition.setLocationUri("/soapws");
        wsdl11Definition.setTargetNamespace("http://cat.xtec.ioc/domain/company/services");
        wsdl11Definition.setSchema(companiesSchema);
        return wsdl11Definition;
    }
 
    @Bean
    public XsdSchema companiesSchema() {
        return new SimpleXsdSchema(new ClassPathResource("companyoperations.xsd"));
    }
 
    @Bean(name = "company")
    public XsdSchema companySchema() {
        return new SimpleXsdSchema(new ClassPathResource("company.xsd"));
    }
}

Fixeu-vos que:

• Spring fa servir un servlet especial de tipus MessageDispatcherServlet per servir peticions SOAP, i cal que el registreu al ApplicationContext de l’aplicació.
• El mètode defaultWsdl11Definition s’encarrega de configurar el document WSDL de definició del servei web a partir del document XSD especificat.
• L’ús de DefaultWsdl11Definition permet la generació automàtica del document WSDL.
• El mètode defaultWsdl11Definition també defineix l’URI i l’espai de noms que caldrà que utilitzeu per cridar el servei web i que estarà disponible en el document WSDL de definició del servei.

Aquesta és tota la feina que ens cal fer per implementar el servei web de consulta de dades d’empreses; ara tan sols ens manca fer el desplegament i provar-lo.

Un cop creat el servei web cal que el desplegueu per tal de fer-lo accessible als clients.

El desplegament del servei web es pot fer de diverses maneres, entre les quals:

• Desplegant l’aplicació Java EE que el conté mitjançant els mecanismes normals de desplegament de qualsevol aplicació Java EE.
• Creant una aplicació executable que s’executarà amb un contenidor de servlets Tomcat que Spring porta incorporat.

Farem el desplegament del servei web creant una aplicació executable. Per fer el desplegament creant una aplicació executable que s’executarà al contenidor de servlets que Spring porta incorporat tan sols ens cal una classe Java anotada amb @SpringBootApplication amb un mètode main que cridi el mètode run de SpringApplication. Al projecte inicial ja teniu una classe Application al paquet cat.xtec.ioc.service.impl que permet que l’aplicació pugui funcionar de forma autònoma.

Poseu-vos damunt la classe Application, feu clic amb el botó dret del ratolí i seleccioneu l’opció Run (també podeu executar el goal de Maven spring-boot:run). Veureu que apareix una finestra a NetBeans amb l’execució de l’aplicació amb Spring (vegeu la figura).

Podeu provar que el desplegament ha anat bé consultant el document WSDL generat a l’enllaç localhost:8080/soapws/companyoperations.wsdl amb qualsevol navegador, i heu de veure el document WSDL de definició del servei generat:

<wsdl:definitions targetNamespace="http://cat.xtec.ioc/domain/company/services">
    <wsdl:types></wsdl:types>
    <wsdl:message name="getCompanyRequest"></wsdl:message>
    <wsdl:message name="getCompanyResponse"></wsdl:message>
    <wsdl:portType name="CompaniesPort"></wsdl:portType>
    <wsdl:binding name="CompaniesPortSoap11" type="tns:CompaniesPort"></wsdl:binding>
    <wsdl:service name="CompaniesPortService"></wsdl:service>
</wsdl:definitions>

Si tot ha anat bé ja teniu el servei web desplegat i a punt per provar-lo. Però com ho fem? Quin format han de tenir els missatges?

Quan es desplega el servei web SOAP es genera un fitxer WSDL de definició del servei web. El fitxer WSDL està forma per elements XML que descriuen completament el servei web i com s’ha de consumir.

El fitxer WSDL té una secció abstracta per definir els ports, els missatges i els tipus de dades de les operacions, i una part concreta que defineix la instància on hi ha aquestes operacions. Aquesta estructura permet reutilitzar la part abstracta del document.

A la part abstracta hi tenim els següents elements:

• types
• message
• portType

Els tipus de dades, tant d’entrada com de sortida, de les operacions es defineixen amb XSD a l’etiqueta <types>:

<wsdl:types>
    <xs:schema elementFormDefault="qualified" targetNamespace="http://cat.xtec.ioc/domain/company/services">
        <xs:import namespace="http://cat.xtec.ioc/domain/company" schemaLocation="company.xsd"/>
        <xs:element name="getCompanyRequest">
            <xs:complexType>
                <xs:sequence>
                    <xs:element name="cif" type="xs:string"/>
                </xs:sequence>
            </xs:complexType>
        </xs:element>
        <xs:element name="getCompanyResponse">
            <xs:complexType>
                <xs:sequence>
                    <xs:element name="company" type="company:company"/>
                </xs:sequence>
            </xs:complexType>
        </xs:element>
    </xs:schema>
</wsdl:types>

Per exemple, si us hi fixeu, defineix que les peticions a l’operació getCompanyRequest reben un paràmetre de tipus string i a les respostes es torna un tipus de dades complex anomenat company que està format per un int i quatre string (cif, name, employees, email i web).

La definició del tipus complex company s’importa d’un fitxer XSD separat que té la definició del model del domini.

<xs:schema elementFormDefault="qualified" targetNamespace="http://cat.xtec.ioc/domain/company">
    <xs:complexType name="company">
        <xs:sequence>
            <xs:element name="cif" type="xs:string"/>
            <xs:element name="name" type="xs:string"/>
            <xs:element name="employees" type="xs:int"/>
            <xs:element name="email" type="xs:string"/>
            <xs:element name="web" type="xs:string"/>
        </xs:sequence>
    </xs:complexType>
</xs:schema>

Després de la definició dels tipus de dades trobem els elements <message> amb la definició dels missatges que es poden intercanviar les operacions del servei web, amb una entrada per a la petició i una altra per a la resposta:

<wsdl:message name="getCompanyRequest">
    <wsdl:part element="tns:getCompanyRequest" name="getCompanyRequest">
    </wsdl:part>
</wsdl:message>
<wsdl:message name="getCompanyResponse">
    <wsdl:part element="tns:getCompanyResponse" name="getCompanyResponse">
    </wsdl:part>
</wsdl:message>

I després, els elements <portType> ens defineixen les operacions que es poden fer al servei web amb els seus paràmetres i el tipus de retorn:

<wsdl:portType name="CompaniesPort">
    <wsdl:operation name="getCompany">
        <wsdl:input message="tns:getCompanyRequest" name="getCompanyRequest">
        </wsdl:input>
        <wsdl:output message="tns:getCompanyResponse" name="getCompanyResponse">
        </wsdl:output>
    </wsdl:operation>
</wsdl:portType>

Veiem, per exemple, que l’operació getCompanyRequest rep com a paràmetre d’entrada un tns:getCompanyRequest i que retorna un tns:getCompanyResponse. Aquests tipus de dades han estat definides completament en el document XSD que hem creat per definir el servei.

A la part concreta hi tenim els següents elements:

• binding
• service

L’element <binding> defineix el protocol i el format en què es poden fer les operacions; en el nostre cas, les operacions es faran per HTTP i amb un estil de Document.

<wsdl:binding name="CompaniesPortSoap11" type="tns:CompaniesPort">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="getCompany">
        <soap:operation soapAction=""/>
        <wsdl:input name="getCompanyRequest">
            <soap:body use="literal"/>
        </wsdl:input>
        <wsdl:output name="getCompanyResponse">
            <soap:body use="literal"/>
        </wsdl:output>
    </wsdl:operation>
</wsdl:binding>

L’element <service>, per la seva part, defineix el lloc físic on hi ha el servei web (adreça URL).

<wsdl:service name="CompaniesPortService">
    <wsdl:port binding="tns:CompaniesPortSoap11" name="CompaniesPortSoap11">
        <soap:address location="http://localhost:8080/soapws"/>
    </wsdl:port>
</wsdl:service>

En el nostre cas, el servei web es a l’URL localhost:8080/soapws.

Amb tot això ja sabem el format dels missatges SOAP que cal enviar per accedir al servei web i on cal enviar-los; creeu un fitxer anomenat request.xml, que representarà el missatge SOAP de petició, amb el següent contingut:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
				  xmlns:gs="http://cat.xtec.ioc/domain/company/services">
   <soapenv:Header/>
   <soapenv:Body>
      <gs:getCompanyRequest>
         <gs:cif>XXXXXXXX</gs:cif>
      </gs:getCompanyRequest>
   </soapenv:Body>
</soapenv:Envelope>

I ja tan sols ens queda fer una petició al servei web per provar-ho. La nostra proposta és que feu servir cURL, que és una eina molt útil per fer peticions HTTP de diferents tipus i que és multiplataforma. Si feu servir Linux possiblement ja la tingueu instal·lada al sistema, i en cas que utilitzeu Windows la podeu descarregar del següent enllaç: curl.haxx.se/download.html.

La sintaxi de cURL per fer peticions és molt senzilla; per exemple, per consultar les dades de l’empresa que té per CIF XXXXXXXX feu un command prompt:

curl --header "content-type: text/xml" -d @request.xml http://localhost:8080/soapws/

Indiquem que la petició s’envia al fitxer request.xml amb el tipus MIME text/xml. Aquest fitxer és el que acabeu de crear amb el missatge SOAP de petició, i l’URL és l’URL on escolta el servei web.

Si executeu la comanda anterior i tot ha anat correctament, veureu la resposta del servei web amb les dades de l’empresa que té per CIF XXXXXXXX:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns3:getCompanyResponse xmlns:ns2="http://cat.xtec.ioc/domain/company" xmlns:ns3="http://cat.xtec.ioc/domain/company/services">
            <ns3:company>
                <ns2:cif>XXXXXXXX</ns2:cif>
                <ns2:name>Oracle</ns2:name>
                <ns2:employees>5000</ns2:employees>
                <ns2:email>oracle@oracle.com</ns2:email>
                <ns2:web>http://www.oracle.com</ns2:web>
            </ns3:company>
        </ns3:getCompanyResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

I això és tot! Hem vist els passos que us cal fer per desenvolupar, desplegar i provar un servei web SOAP amb Spring-WS seguint una estratègia Contract First.

Crearem una aplicació Java que consumeixi el servei web de consulta de dades d’empreses i ho farem desenvolupant un client Java stand-alone que accedirà al servei web amb Spring-WS.

Els passos generals per fer un client amb Spring-WS són els següents:

1. Generar els artefactes necessaris per poder consumir el servei web a partir de la definició del servei en format WSDL.
2. Codificar la classe que farà la crida al servei web heretant de la classe WebServiceGatewaySupport que proporciona Spring-WS.
3. Compilar i executar el client.

El client que farem consultarà les dades de les empreses d’un servei web SOAP desenvolupat amb Spring-WS. Descarregueu el codi del servei web que consultarem en el següent

Quan tingueu el projecte importat a NetBeans cal que desplegueu el servei web que conté; per exemple, creant una aplicació executable que s’executarà amb un contenidor de servlets Tomcat que Spring porta incorporat. Ho podeu fer de diverses maneres, una és fent clic amb el botó dret damunt de la classe Application del paquet cat.xtec.ioc.client i seleccionant Run File (vegeu la figura).

També ho podeu fer executant el goal de Maven spring-boot:run. Amb qualsevol de les dues opcions veureu que apareix una finestra a NetBeans amb l’execució de l’aplicació amb Spring (vegeu la figura).

Podeu provar que el desplegament ha anat bé consultant el document WSDL generat a l’enllaç localhost:8080/soapws/companyoperations.wsdl amb qualsevol navegador, i heu de veure el document WSDL de definició del servei.

Després de desplegar el servei web que volem consultar ens cal crear el client Java que el consultarà amb Spring-WS.

El primer que cal fer és generar els artefactes necessaris per poder consumir el servei web des d’aquest client a partir de la seva definició en format WSDL. Això es pot fer de diverses formes, i una manera senzilla és que ho faci un plugin de Maven en temps de construcció del projecte.

Afegiu les següents línies al fitxer pom.xml i feu un Reload POM del projecte:

<plugin>
    <groupId>org.jvnet.jaxb2.maven2</groupId>
    <artifactId>maven-jaxb2-plugin</artifactId>
    <version>0.13.1</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <schemaLanguage>WSDL</schemaLanguage>
        <generatePackage>cat.xtec.ioc.domain.companies.wsdl</generatePackage>
        <schemas>
            <schema>
                <url>http://localhost:8080/soapws/companyoperations.wsdl</url>
            </schema>
        </schemas>
    </configuration>
</plugin>

Aquest plugin generarà automàticament les classes necessàries per consultar el servei web de consulta de dades d’empreses en temps de compilació i les deixarà al paquet cat.xtec.ioc.domain.companies.wsdl. Fixeu-vos també que estem especificant en la configuració del plugin la localització del document WSDL amb la definició del servei.

Si feu clic amb el botó dret damunt el projecte “Springsoapempclientioc” i feu Clean and Build veureu que el plugin genera, entre d’altres, les següents classes a partir del document WSDL de definició de servei:

• Company.java
• GetCompanyRequest.java
• GetCompanyResponse.java

Un cop generats els artefactes necessaris cal que creeu la classe Java que farà la crida al servei web. Creeu-la, per exemple, al paquet cat.xtec.ioc.client i anomeneu-la CompaniesClient:

package cat.xtec.ioc.client;
 
import cat.xtec.ioc.domain.companies.wsdl.GetCompanyRequest;
import cat.xtec.ioc.domain.companies.wsdl.GetCompanyResponse;
import org.springframework.ws.client.core.support.WebServiceGatewaySupport;
import org.springframework.ws.soap.client.core.SoapActionCallback;
 
public class CompaniesClient extends WebServiceGatewaySupport {
 
    public GetCompanyResponse getCompanyInformation(String cif) {
        GetCompanyRequest request = new GetCompanyRequest();
        request.setCif(cif);
        GetCompanyResponse response = (GetCompanyResponse) getWebServiceTemplate()
                .marshalSendAndReceive(request,
                        new SoapActionCallback("http://localhost:8080/soapws/getCompanyResponse"));
 
        return response;
    }
 
}

Aquesta classe hereta d’una classe que proporciona Spring anomenada WebServiceGatewaySupport i utilitza les classes generades per fer una crida al servei web mitjançant un template que proporciona la seva classe base.

També ens cal crear una classe de configuració per indicar a Spring que faci servir JAXB per fer les transformacions de missatge SOAP a objecte Java, i a la inversa. Creeu aquesta classe Java també al paquet cat.xtec.ioc.client i anomeneu-la ClientAppConfig:

package cat.xtec.ioc.client;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.oxm.jaxb.Jaxb2Marshaller;
 
@Configuration
public class ClientAppConfig {
 
    @Bean
    public Jaxb2Marshaller marshaller() {
        Jaxb2Marshaller marshaller = new Jaxb2Marshaller();
        marshaller.setContextPath("cat.xtec.ioc.domain.companies.wsdl");
        return marshaller;
    }
 
    @Bean
    public CompaniesClient companiesClient(Jaxb2Marshaller marshaller) {
        CompaniesClient client = new CompaniesClient();
        client.setDefaultUri("http://localhost:8080/soapws/companies.wsdl");
        client.setMarshaller(marshaller);
        client.setUnmarshaller(marshaller);
        return client;
    }
}

Finalment, creeu una classe Java, també al paquet cat.xtec.ioc.client, i l’anomeneu RunCompaniesClient, amb el següent codi:

package cat.xtec.ioc.client;
 
import cat.xtec.ioc.domain.companies.wsdl.GetCompanyResponse;
import org.springframework.context.annotation.AnnotationConfigApplicationContext;
 
public class RunCompaniesClient {
 
    public static void main(String[] args) {
        AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext();
        ctx.register(ClientAppConfig.class);
        ctx.refresh();
        CompaniesClient companiesClient = ctx.getBean(CompaniesClient.class);
        System.out.println("For Company XXXXXXXX");
        GetCompanyResponse response = companiesClient.getCompanyInformation("XXXXXXXX");
        System.out.println("CIF: " + response.getCompany().getCif());
        System.out.println("Name: " + response.getCompany().getName());
        System.out.println("Num. employees: " + response.getCompany().getEmployees());
        System.out.println("Email: " + response.getCompany().getEmail());
        System.out.println("Web: " + response.getCompany().getWeb());
    }
}

Aquesta classe té un mètode main que s’encarrega de crear un objecte de tipus CompaniesClient amb la configuració especificada a ClientAppConfig, fer una petició al servei web de consulta de dades d’empreses per recuperar les dades de l’empresa que té el CIF XXXXXXXX amb aquesta classe i mostrar els resultats per a la sortida estàndard.

Ara ja podem executar el client; per fer-ho, poseu-vos damunt de la classe RunCompaniesClient i feu Run File a NetBeans (vegeu la figura).

I obtindreu per consola les dades de l’empresa que té el CIF XXXXXXXX:

CIF: XXXXXXXX
Name: Oracle
Num. employees: 5000
Email: oracle@oracle.com
Web: http://www.oracle.com

Heu vist les bases per al desenvolupament dels serveis web SOAP amb Spring-WS i les heu treballat de forma pràctica mitjançant exemples.

Concretament, heu après:

• Les nocions bàsiques dels serveis web SOAP amb Spring-WS.
• La diferència entre Contract First i Code First.
• Les diferències bàsiques entre JAX-WS i Spring-WS.
• Desenvolupar, desplegar i provar un servei web SOAP amb Spring-WS.
• Desenvolupar i provar un client Java que consulti un servei web SOAP mitjançant Spring-WS.