Oprettelse af en SOAP-webservice med Spring

1. Oversigt

I denne vejledning ser vi, hvordan man opretter en SOAP-baseret webservice med Spring Boot Starter Web Services.

2. SOAP Web Services

En webservice er kort sagt en platform-uafhængig service fra maskine til maskine, der muliggør kommunikation over et netværk.

SOAP er en beskedprotokol. Beskeder (anmodninger og svar) er XML-dokumenter via HTTP. XML-kontrakten er defineret af WSDL (Sprog til webtjenestebeskrivelse). Det giver et sæt regler til at definere meddelelser, bindinger, operationer og placering af tjenesten.

XML, der bruges i SOAP, kan blive ekstremt kompleks. Af denne grund er det bedst at bruge SOAP med en ramme som JAX-WS eller Spring, som vi vil se i denne vejledning.

3. Kontrakt-første udviklingsstil

Der er to mulige tilgange, når du opretter en webservice: Contract-Last og Contract-First. Når vi bruger en kontrakt-sidste tilgang, starter vi med Java-koden, og vi genererer webservicekontrakten (WSDL) fra klasserne. Når du bruger kontrakt-først, Vi starter med WSDL-kontrakten, hvorfra vi genererer Java-klasser.

Spring-WS understøtter kun den første kontraktudviklingsstil.

4. Opsætning af Spring Boot Project

Vi opretter et Spring Boot-projekt, hvor vi definerer vores SOAP WS-server.

4.1. Maven afhængigheder

Lad os starte med at tilføje spring-boot-starter-parent til vores projekt:

 org.springframework.boot spring-boot-starter-parent 2.2.6.RELEASE 

Lad os derefter tilføje spring-boot-starter-web-services og wsdl4j afhængigheder:

 org.springframework.boot spring-boot-starter-web-services wsdl4j wsdl4j 

4.2. XSD-filen

Kontrakt-første tilgang kræver, at vi først opretter domænet (metoder og parametre) til vores service. Vi skal bruge en XML-skemafil (XSD), som Spring-WS automatisk eksporterer som en WSDL:

I denne fil ser vi formatet på getCountryRequest anmodning om webservice. Vi definerer det til at acceptere en parameter af typen snor.

Dernæst definerer vi formatet på svaret, som indeholder et objekt af typen Land.

Endelig ser vi betalingsmiddel objekt, der bruges inden for Land objekt.

4.3. Generer Java-klasser for domæne

Vi skal nu generere Java-klasser fra XSD-filen, der er defineret i det foregående afsnit. Det jaxb2-maven-plugin gør dette automatisk i løbet af byggetiden. Pluginet bruger XJC-værktøjet som motor til kodegenerering. XJC kompilerer XSD-skemafilen i fuldt kommenterede Java-klasser.

Lad os tilføje og konfigurere pluginet i vores pom.xml:

 org.codehaus.mojo jaxb2-maven-plugin 1.6 xjc xjc $ {project.basedir} / src / main / resources / $ {project.basedir} / src / main / java false 

Her bemærker vi to vigtige konfigurationer:

  • $ {project.basedir} / src / main / ressourcer - Placeringen af ​​XSD-filen
  • $ {project.basedir} / src / main / java - Hvor vi vil have, at vores Java-kode skal genereres

For at generere Java-klasser kunne vi bare bruge xjc-værktøjet fra vores Java-installation. Selvom ting i vores Maven-projekt er endnu mere enkle, som klasserne genereres automatisk under den sædvanlige Maven-build:

mvn kompilere

4.4. Tilføj SOAP Web Service Endpoint

SOAP-webservicens slutpunktsklasse håndterer alle indgående anmodninger om tjenesten. Den starter behandlingen og sender svaret tilbage.

Før vi definerer dette, opretter vi en Land arkiv for at levere data til webservicen.

@Komponent offentlig klasse CountryRepository {privat statisk endelig Kort lande = nyt HashMap (); @PostConstruct public void initData () {// initialiser landekort} public Country findCountry (String name) {return countries.get (name); }} 

Lad os derefter konfigurere slutpunktet:

@Endpoint offentlig klasse CountryEndpoint {privat statisk endelig streng NAMESPACE_URI = "//www.baeldung.com/springsoap/gen"; private CountryRepository countryRepository; @Autowired public CountryEndpoint (CountryRepository countryRepository) {this.countryRepository = countryRepository; } @PayloadRoot (namespace = NAMESPACE_URI, localPart = "getCountryRequest") @ResponsePayload offentlig GetCountryResponse getCountry (@RequestPayload GetCountryRequest anmodning) {GetCountryResponse svar = ny GetCountryResponse (); respons.setCountry (countryRepository.findCountry (anmodning.getnavn ())); tilbagevenden svar }} 

Her er et par detaljer at bemærke:

  • @Endpoint - registrerer klassen med Spring WS som et Web Service Endpoint
  • @PayloadRootdefinerer behandlermetoden i henhold til navneområde og localPart egenskaber
  • @ResponsePayload - angiver, at denne metode returnerer en værdi, der skal kortlægges, til svarets nyttelast
  • @RequestPayload - angiver, at denne metode accepterer en parameter, der skal kortlægges fra den indgående anmodning

4.5. SOAP Web Service Configuration Beans

Lad os nu oprette en klasse til konfiguration af Spring-meddelelsesforsendelses servlet til at modtage anmodningen:

@EnableWs @Configuration offentlig klasse WebServiceConfig udvider WsConfigurerAdapter {// bean definitioner}

@EnableWs aktiverer SOAP Web Service-funktioner i denne Spring Boot-applikation. Det WebServiceConfig klasse udvider WsConfigurerAdapter basisklasse, som konfigurerer den annoteringsdrevne Spring-WS programmeringsmodel.

Lad os oprette en MessageDispatcherServlet som bruges til håndtering af SOAP-anmodninger:

@Bean public ServletRegistrationBean messageDispatcherServlet (ApplicationContext applicationContext) {MessageDispatcherServlet servlet = ny MessageDispatcherServlet (); servlet.setApplicationContext (applicationContext); servlet.setTransformWsdlLocations (true); returner ny ServletRegistrationBean (servlet, "/ ws / *"); } 

Vi indstiller den injicerede ApplicationContext genstand for servlet så Spring-WS kan finde andre Spring bønner.

Vi aktiverer også WSDL-placeringsservlet-transformation. Dette transformerer placeringsattributten for sæbe: adresse i WSDL, så den afspejler URL'en til den indgående anmodning.

Lad os endelig oprette en StandardWsdl11Definition objekt. Dette udsætter en standard WSDL 1.1 ved hjælp af et XsdSchema. WSDL-navnet vil være det samme som bønnenavnet.

@Bean (navn = "lande") offentlig StandardWsdl11Definition defaultWsdl11Definition (XsdSchema landeSchema) {DefaultWsdl11Definition wsdl11Definition = ny DefaultWsdl11Definition (); wsdl11Definition.setPortTypeName ("CountriesPort"); wsdl11Definition.setLocationUri ("/ ws"); wsdl11Definition.setTargetNamespace ("// www.baeldung.com/springsoap/gen"); wsdl11Definition.setSchema (landeSchema); returnere wsdl11Definition; } @Bean offentlige XsdSchema-landeSchema () {returner nyt SimpleXsdSchema (nyt ClassPathResource ("lands.xsd")); } 

5. Test af SOAP-projektet

Når projektkonfigurationen er afsluttet, er vi klar til at teste den.

5.1. Byg og kør projektet

Det ville være muligt at oprette en WAR-fil og distribuere den til en ekstern applikationsserver. Vi bruger i stedet Spring Boot, som er en hurtigere og lettere måde at få applikationen i gang.

Først tilføjer vi følgende klasse for at gøre applikationen eksekverbar:

@SpringBootApplication public class Application {public static void main (String [] args) {SpringApplication.run (Application.class, args); }} 

Bemærk, at vi ikke bruger nogen XML-filer (som web.xml) til at oprette denne applikation. Det hele er rent Java.

Nu er vi klar til at opbygge og køre applikationen:

mvn spring-boot: løb

For at kontrollere, om applikationen kører korrekt, kan vi åbne WSDL gennem URL: //localhost:8080/ws/countries.wsdl

5.2. Test en SOAP-anmodning

For at teste en anmodning opretter vi følgende fil og navngiver den anmodning.xml:

    Spanien 

For at sende anmodningen til vores testserver kunne vi bruge eksterne værktøjer som SoapUI eller Google Chrome-udvidelsen Wizdler. En anden måde er at køre følgende kommando i vores shell:

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

Det resulterende svar er muligvis ikke let at læse uden indrykning eller linjeskift.

For at se det formateret kan vi kopiere det til vores IDE eller et andet værktøj. Hvis vi har installeret xmllib2, kan vi føre output fra vores curl-kommando til xmllint:

krølle [kommandolinjevalg] | xmllint --format -

Svaret skal indeholde oplysninger om Spanien:

     Spanien 46704314 Madrid EUR 

6. Konklusion

I denne artikel lærte vi, hvordan man opretter en SOAP-webservice ved hjælp af Spring Boot. Vi lærte også, hvordan man genererer Java-kode fra en XSD-fil, og vi så, hvordan vi konfigurerer de Spring-bønner, der er nødvendige for at behandle SOAP-anmodningerne.

Den komplette kildekode er tilgængelig på GitHub.