Esteban Mayoralen viernes, 11 de agosto de 2023

Como crear servicios SOAP 🧼🫧 con Spring Boot 🍃 + Apache CXF

Como crear servicios SOAP con Spring Boot + Apache CXF

Uno de los estándares mas extendidos para la creación de servicios antes de REST, fue SOAP, que la diferencia a simple vista que vemos es que en lugar de usar JSON como elemento de intercambio de la información usa XML.

La principal ventaja de los servicios SOAP en el pasado fue que definía no solo una forma de transmitir la información, sino también reglas en lo que tiene que ver a la estructura de los mensajes, y estableciendo cosas como WSDL (Web Services Description Language) como estándar, lo que permite un "contrato formal" para todos aquellos consumidores que usen tu servicio.

A día de hoy REST tiene OpenAPI / Swagger como estándar de definición que seria el equivalente en SOAP a WSDL, así que personalmente diría que en la actualidad no tiene ningún sentido crear servicios SOAP respecto a uno REST principalmente porque JSON es mucho las ligero que XML, pero si que considero que es importante conocerlo ya que durante mi carrera para implementar requisitos me he visto en la necesidad de realizar integraciones con servicios SOAP, es por ello que el articulo el objetivo principal es abrir camino, para un segundo articulo en el que hablo de como consumir servicios SOAP.

Comencemos.

Para empezar, voy a usar la maravillosa pagina de Spring Initialzr que nos permite seleccionar de manera rápida y sencilla los diferentes "starters" que vamos a necesitar, en este caso vamos a necesitar únicamente:

Spring Web

Yo en mi caso también voy a añadir las Spring DevTools, pero no es necesaria.

Spring Initializr

Adicionalmente también añadiré la siguiente dependencia en el pom.xml

<dependency>  
   <groupId>org.apache.cxf</groupId>  
   <artifactId>cxf-spring-boot-starter-jaxws</artifactId>  
   <version>4.0.2</version>  
</dependency>

os recomiendo poner la versión en <properties> dentro del pom.xml y usar ${cxf.version}

Creando nuestra primera operación.

A diferencia de los servicios REST en los servicios SOAP tenemos un único endpoint que puede tener varias "operaciones", cada una de estas operaciones representa un endpoint si lo comparamos con los servicios REST (esto a algunos os recordara a GraphQL)

Para crear mi primera operación he creado una clase y le he agregado un simple método:

package dev.mpesteban.soapservice;  

import jakarta.jws.WebMethod;  
import jakarta.jws.WebService;  


@WebService  
public class MySoapService {  

    @WebMethod  
    public String sayHello(String name) {  
        return "Hello, " + name + "!";  
    }  
}

Lo siguiente es crear las Beans necesarias para que funcione correctamente con Spring Boot, para ello he creado una clase con la anotación @Configuration con lo siguiente:

package dev.mpesteban.soapservice;  

import jakarta.xml.ws.Endpoint;  
import org.apache.cxf.Bus;  
import org.apache.cxf.bus.spring.SpringBus;  
import org.apache.cxf.jaxws.EndpointImpl;  
import org.apache.cxf.transport.servlet.CXFServlet;  
import org.springframework.boot.web.servlet.ServletRegistrationBean;  
import org.springframework.context.annotation.Bean;  
import org.springframework.context.annotation.Configuration;  

@Configuration  
public class WebServiceConfig {  
    @Bean  
    public ServletRegistrationBean<CXFServlet> cxfServlet() {  
        return new ServletRegistrationBean<>(new CXFServlet(), "/ws/*");  
    }  

    @Bean(name = Bus.DEFAULT_BUS_ID)  
    public SpringBus springBus() {  
        return new SpringBus();  
    }  

    @Bean  
    public Endpoint endpoint() {  
        EndpointImpl endpoint = new EndpointImpl(springBus(), new MySoapService());  
        endpoint.publish("/Hello");  
        return endpoint;  
    }  

}

Y listo con todo esto tendríamos ya listo un servicio muy básico para ser usado.

¡Vamos a probarlo!

Para probar que nuestra operación ha sido creada y funciona correctamente, arrancamos como haríamos normalmente con cualquier proyecto de Spring Boot.

Lo primero que podremos detectar como buena señal de que esta funcionando correctamente son algunos mensajes en el log, indicando que el servicio ha sido registrado:

2023-08-08T11:33:35.763+02:00  INFO 34656 --- [  restartedMain] o.a.c.w.s.f.ReflectionServiceFactoryBean : Creating Service {http://soapservice.mpesteban.dev/}MySoapServiceService from class dev.mpesteban.soapservice.MySoapService
2023-08-08T11:33:36.124+02:00  INFO 34656 --- [  restartedMain] org.apache.cxf.endpoint.ServerImpl       : Setting the server's publish address to be /Hello

Esto es buena señal pero si nos dirigimos a http://localhost:8080/ws/Hello?wsdl deberiamos poder visualizar correctamente la definicion WSDL.

<wsdl:definitions xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://soapservice.mpesteban.dev/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:ns1="http://schemas.xmlsoap.org/soap/http" name="MySoapServiceService"
    targetNamespace="http://soapservice.mpesteban.dev/">
    <wsdl:types>
        <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:tns="http://soapservice.mpesteban.dev/" elementFormDefault="unqualified"
            targetNamespace="http://soapservice.mpesteban.dev/" version="1.0">
            <xs:element name="sayHello" type="tns:sayHello" />
            <xs:element name="sayHelloResponse" type="tns:sayHelloResponse" />
            <xs:complexType name="sayHello">
                <xs:sequence>
                    <xs:element minOccurs="0" name="arg0" type="xs:string" />
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="sayHelloResponse">
                <xs:sequence>
                    <xs:element minOccurs="0" name="return" type="xs:string" />
                </xs:sequence>
            </xs:complexType>
        </xs:schema>
    </wsdl:types>
    <wsdl:message name="sayHelloResponse">
        <wsdl:part element="tns:sayHelloResponse" name="parameters"> </wsdl:part>
    </wsdl:message>
    <wsdl:message name="sayHello">
        <wsdl:part element="tns:sayHello" name="parameters"> </wsdl:part>
    </wsdl:message>
    <wsdl:portType name="MySoapService">
        <wsdl:operation name="sayHello">
            <wsdl:input message="tns:sayHello" name="sayHello"> </wsdl:input>
            <wsdl:output message="tns:sayHelloResponse" name="sayHelloResponse"> </wsdl:output>
        </wsdl:operation>
    </wsdl:portType>
    <wsdl:binding name="MySoapServiceServiceSoapBinding" type="tns:MySoapService">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
        <wsdl:operation name="sayHello">
            <soap:operation soapAction="" style="document" />
            <wsdl:input name="sayHello">
                <soap:body use="literal" />
            </wsdl:input>
            <wsdl:output name="sayHelloResponse">
                <soap:body use="literal" />
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:service name="MySoapServiceService">
        <wsdl:port binding="tns:MySoapServiceServiceSoapBinding" name="MySoapServicePort">
            <soap:address location="http://localhost:8080/ws/Hello" />
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

Si este es el caso es que entonces todo va como la seda, para terminar de comprobar que todo funciona correctamente he descargado SOAP UI, una herramienta que para mi es imprescindible cuando trabajo con servicios SOAP, describirlo rápidamente es "El Postman de servicios SOAP", aunque Postman a la fecha de escribir este articulo, ya te permite importar WSDL, Postman concreto me ha dado algún que otro problema en alguna ocasión no generándome el contenido de la request de ejemplo de forma correcta, es por eso que sigo prefiriendo SOAP UI.

Para lanzar llamadas contra nuestro servicio con SOAP UI:

Desde File > New SOAP Project introducimos

Project Name: El que tu quieras.
Initial WSDL: La URL de nuestro WSDL http://localhost:8080/ws/Hello?wsdl

Esto creara un nuevo proyecto SOAP que nos permitirá hacer llamadas a nuestras operaciones,

SOAP UI Operation 1

Lanzamos la petición:

SOAP UI Request

Y podemos ver que nos responde correctamente.

Creando estructuras mas complejas

El ejemplo anterior era sencillo pero ¿Y si queremos recibir un objeto con varios atributos etc. como podemos hacerlo?

Bien aquí entran las etiquetas de JAXB veamos un ejemplo:

Para este ejemplo voy a crear una clase Car y un nuevo método en mi servicio que devuelva una lista de los Car que coincidan con la marca que le he pasado por parámetros en la petición.

package dev.mpesteban.soapservice;  


import jakarta.xml.bind.annotation.XmlRootElement;  

@XmlRootElement  
public class Car {  

    private String brand;  

    private String model;  
    private Integer horsepower;  


    public Car(String brand, String model, Integer horsepower) {  
        this.brand = brand;  
        this.model = model;  
        this.horsepower = horsepower;  
    }

    public Car() {}

    public String getBrand() {  
        return brand;  
    }  

    public void setBrand(String brand) {  
        this.brand = brand;  
    }  

    public String getModel() {  
        return model;  
    }  

    public void setModel(String model) {  
        this.model = model;  
    }  

    public Integer getHorsepower() {  
        return horsepower;  
    }  

    public void setHorsepower(Integer horsepower) {  
        this.horsepower = horsepower;  
    }  

}

La clase Car tenga un constructor por defecto, es algo requerido por JAXB, y que si no lo tenemos la aplicación no arrancara.

Nuestra nueva operación dentro de la clase MySoapService quedaría así:

@WebMethod  
public List<Car> getCarsByBrand(String brandName) {  

    final List<Car> cars = List.of(  
            new Car("Ford", "Mustang", 300),  
            new Car("Kia", "Ceed", 140),  
            new Car("Honda", "Civic", 300),  
            new Car("Honda", "Jazz", 90)  
    );  

    return cars.stream().filter((e) -> e.getBrand().equalsIgnoreCase(brandName)).collect(Collectors.toList());  

}

Probamos la peticion y todo como la seda.

SOAP UI Operation 2

Simplificando la creacion de endpoints

Como habréis observado al inicio, cada vez que queremos crear un nuevo "Endpoint", implica crear una nueva Bean, indicando las clases que contienen operaciones asociados a ese endpoint, esto hace que pueda haber algún punto en el que la clase de configuraciónion crezca mucho, en una tarea repetitiva como lo es la creación de endpoints.

Para solucionar esto, vamos a crear nuestra propia anotación, que nos permita al arrancar la aplicación, obtener todas las clases que contienen esta anotación, instanciarlas y asociarlas a un Endpoint.

package dev.mpesteban.soapservice;  


import java.lang.annotation.Retention;  
import java.lang.annotation.RetentionPolicy;  


@Retention(RetentionPolicy.RUNTIME)  
public @interface WebServiceEndpoint {  
    String value();  
}

Con nuestra anotación personalizada creada, vamos a hacer toda la logica relacionada con obtener las clases y crear las beans, para ello voy a modificar la clase WebServiceConfig y hacer que implemente la interfaz BeanFactoryPostProcessor proporcionandonos el metodo postProcessBeanFactory.

El método postProcessBeanFactory se llama durante la fase de inicialización del contexto de Spring, después de que se hayan cargado todas las definiciones de beans pero antes de que se creen las instancias reales de los beans. Esto te brinda la oportunidad de influir en cómo se configurarán y se instanciarán los beans antes de que se utilicen en la aplicación, en nuestro caso concreto nos va a permitir definir las beans que necesitamos de forma dinámica.

@Override  
public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException {  
    try {  
        generateServiceBeans(beanFactory);  
    } catch (ClassNotFoundException e) {  
        throw new RuntimeException(e);  
    }  
}

El metodo generateServiceBeans tiene lo principal que vamos a usar.

public void generateServiceBeans(  
        final ConfigurableListableBeanFactory  beanFactory  
) throws ClassNotFoundException {  

    List<Class<?>> clazzList = findAllWebServiceEndpointClasses(this.getClass().getPackageName());  

    log.info("Detected " + clazzList.size() + " SOAP WebServices interfaces");  

    Bus bus = beanFactory.getBean(Bus.class);  

    for (Class<?> clazz : clazzList) {  
        WebServiceEndpoint wsEndpoint = clazz.getAnnotation(WebServiceEndpoint.class);  
        beanFactory.registerSingleton("endpoint" + clazz.getSimpleName(), generateEndpointBean(bus, clazz, wsEndpoint));  
    }  

}

Como podemos observar tenemos un método findAllWebServiceEndpointClasses que es el que va a tener la lógica para buscar las clases con nuestra anotación personalizada, recibe el nombre del paquete que para este ejemplo he utilizado la clase actual para obtenerlo:

private List<Class<?>> findAllWebServiceEndpointClasses(String packageName) throws ClassNotFoundException {  
    final List<Class<?>> result = new LinkedList<>();  
    final ClassPathScanningCandidateComponentProvider provider = new ClassPathScanningCandidateComponentProvider(  
            false);  
    provider.addIncludeFilter(new AnnotationTypeFilter(WebServiceEndpoint.class));  
    for (BeanDefinition beanDefinition : provider  
            .findCandidateComponents(packageName)) {  
            result.add(Class.forName(beanDefinition.getBeanClassName()));  
    }  

    return result;  
}

Esto nos devuelve una lista con todas las clases que tienen esta anotacion, para que funcione correctamente deberemos aplicar la anotacion @WebServiceEndpoint a la clase MySoapService quedando de la siguiente manera:

package dev.mpesteban.soapservice;  

import jakarta.jws.WebMethod;  
import jakarta.jws.WebService;  

import java.util.List;  
import java.util.stream.Collectors;  



@WebServiceEndpoint("/Hello")  
@WebService  
public class MySoapService {  

    @WebMethod  
    public String sayHello(String name) {  
        return "Hello, " + name + "!";  
    }  

    @WebMethod  
    public List<Car> getCarsByBrand(String brandName) {  

        final List<Car> cars = List.of(  
                new Car("Ford", "Mustang", 300),  
                new Car("Kia", "Ceed", 140),  
                new Car("Honda", "Civic", 300),  
                new Car("Honda", "Jazz", 90)  
        );  

        return cars.stream().filter((e) -> e.getBrand().equalsIgnoreCase(brandName)).collect(Collectors.toList());  

    }  
}

Volviendo al metodo generateServiceBeans podemos ver que lo siguiente que hace es recorrer la lista obtenida y por cada elemento llama a el metodo generateEndpointBean. y registra una bean usando beanFactory que le hemos ido pasando por parametros.

    for (Class<?> clazz : clazzList) {  
        WebServiceEndpoint wsEndpoint = clazz.getAnnotation(WebServiceEndpoint.class);  
        beanFactory.registerSingleton("endpoint" + clazz.getSimpleName(), generateEndpointBean(bus, clazz, wsEndpoint));  
    }

private <T> T generateEndpointBean(  
        final Bus bus,  
        Class<T> clazz,  
        final WebServiceEndpoint endpointConfig  
) {  
    JaxWsServerFactoryBean endpointBean = new JaxWsServerFactoryBean();  
    endpointBean.setAddress(endpointConfig.value());  
    endpointBean.setBus(bus);  
    endpointBean.setServiceClass(clazz);  
    return (T) endpointBean.create();  
}

Usando la clase JaxWsServerFactoryBean creamos nos permite crear una instancia de esa clase lista para ser usada como Bean.

Esto nos permite de manera rápida que simplemente cada vez que una clase tenga nuestra anotación automáticamente se considere que es un nuevo endpoint y nos evita repetir código constantemente.

Con todo esto tendríamos una solida base para un proyecto.

¿Por qué Apache CXF y no usar Spring WS?

Esto es una pregunta que los mas avanzados y que ya entiendan del tema se pueden hacer la respuesta es sencilla:

El principal motivo es que el objetivo de esta guia era que cuanto antes empezar a programar, el problema de Spring WS es que te obliga a que comiences definiendo tu esquema XSD (hacer el contrato de tu API primero), y en cambio Apache CXF te permite generar a partir de tu código toda la definición necesaria.