Spring Boot & Apache CXF – Von 0 auf SOAP mit dem cxf-spring-boot-starter

Sie haben bisher keinen einzigen Artikel dieser Blogserie gelesen? Gut so! Denn das Beste kommt erst jetzt. Wir verheiraten Spring Boot und Apache CXF in einem eigenen spring-boot-starter. So haben wir unsere SOAP-Endpoints noch schneller am Start und nutzen trotzdem alle bisher vorgestellten Features voll aus!

Spring Boot & Apache CXF – Tutorial

Part 1: Spring Boot & Apache CXF – SOAP ohne XML?
Part 2: Spring Boot & Apache CXF – SOAP Webservices testen
Part 3: Spring Boot & Apache CXF – XML-Validierung und Custom SOAP Faults
Part 4: Spring Boot & Apache CXF – Logging & Monitoring mit logback, Elasticsearch, Logstash & Kibana
Part 5: Spring Boot & Apache CXF – Von 0 auf SOAP mit dem cxf-spring-boot-starter

Wir haben in den vorangegangenen Blogartikeln eine Menge über die Arbeit mit Spring Boot und Apache CXF gelernt. Es bleibt eigentlich nur ein Problem: Wir fangen bei jedem unserer SOAP Endpoints von Neuem an, alle Schritte jedes einzelnen Blogartikels aufs Neue nachzuvollziehen. Bei aller Aktualität der Technologien geht uns das aber irgendwann gegen den Strich: Wir machen Dinge doppelt und dreifach. Doch glücklicherweise haben sich die Spring-Boot-Entwickler auch für diesen Fall etwas einfallen lassen: Es ist möglich, sich eigene Spring Boot Starter zu bauen, die alles Nötige für unseren speziellen Use Case mitbringen.

Der offizielle Apache CXF spring-boot-starter reicht uns nicht…

Das haben mittlerweile auch die Apache-CXF-Entwickler erkannt und bieten einen spring boot starter an (danke nochmal für den Hinweis Stéphane Nicoll 🙂 ). Schaut man sich diesen spring-boot-starter genauer an, so wird schnell klar, dass er sich natürlich ausschließlich auf Apache CXF konzentriert. Er nimmt uns dabei insgesamt die folgende Arbeit ab: Er initialisiert CXF. Das ist alles. Wie im ersten Artikel dieser Serie beschrieben, ist das letztlich folgender Code, den wir uns sparen können, wenn wir den Starter einsetzen:

1@Bean
2public ServletRegistrationBean dispatcherServlet() {
3    return new ServletRegistrationBean(new CXFServlet(), "/soap-api/*");
4}
5@Bean(name=Bus.DEFAULT_BUS_ID)
6public SpringBus springBus() {      
7    return new SpringBus();
8}

Im Kontext der CXF-Entwickler ist diese Fokussierung auch völlig ok! Aber es hilft uns in unseren Enterprise-Umfeldern wenig. Denn mit allen anderen Punkten stehen wir wieder allein da.

Also ein eigener spring-boot-starter?!!

Genau deshalb haben wir uns entschieden, einen eigenen spring-boot-starter für Apache CXF sowie notwendige Technologien „drumherum“ zu entwickeln und auf GitHub verfügbar zu machen…

Aber halt! Dürfen spring-boot-starter nicht nur durch die Spring-Entwickler bereitgestellt werden? Sind sie nicht deren exklusiver Weg, Funktionalität mit Spring Boot verfügbar zu machen? Zum Glück nicht! Neben der riesigen Anzahl von Startern, die Spring Boot von Haus aus mitbringt , kann jeder Entwickler seinen eigenen Starter bauen. Einige davon haben es sogar in die Community-Auswahl der Spring-Boot-Entwickler geschafft.

Wie man einen eigenen spring-boot-starter baut, beschreiben die Spring-Boot-Entwickler auf docs.spring.io und einer meiner Kollegen hat alle notwendigen Schritte zusammengetragen. Der Aufbau eines eigenen spring-boot-starters birgt die Möglichkeit, richtig in die Tiefen von Spring Boot abzutauchen und ein tieferes Verständnis für das Framework zu entwickeln. Gleichzeitig werden technische Frameworks nicht mehrfach entwickelt und können in allen Projekten mit den gleichen Anforderungen benutzt werden. Damit widerspricht ein spring-boot-starter auch nicht den Gedanken hinter der Microservices-Bewegung, sondern fördert diese sogar: Der Austausch von technischen Bibliotheken, am besten sogar über github.com, wird ausdrücklich empfohlen.

cxf-spring-boot-starter

Doch nun zum Eigentlichen: Ähnlich dem schon länger verfügbaren spring-boot-starter-batch-web haben wir den cxf-spring-boot-starter auf GitHub verfügbar gemacht. Er nimmt uns viele Dinge ab, die wir ohne ihn zu Fuß machen müssten. Hier ein paar davon:

• Hochziehen aller notwendigen Apache-CXF-Komponenten (natürlich mit 100% Java-Konfiguration 😉 )
• Extremes Vereinfachen der Logging-Konfiguration
• Extraktion der ein- und ausgehenden SOAP-XML-Nachrichten für einen Elastic-Stack – inkl. eigener Custom Fields & Korrelation aller Log-Events eines Requests
• Anbieten eines Builders für eigene Custom SOAP Faults, die bei XML-Schemavalidierung auf Basis eigener XSDs zurückgeliefert werden sollen
• Umfangreiche Unterstützung bei der Erstellung von Unit-, Integrations- und Systemstests sowie beim Testen von invaliden XML-Anfragen

Außerdem wird die im Detail umständliche Konfiguration des jaxws-maven-plugin vollständig gekapselt und die Generierung aller Java-Klassen aus der WSDL wird zum Kinderspiel. Hierfür kommt eine zweite Komponente zum Einsatz: das cxf-spring-boot-starter-maven-plugin . Es sucht neben der Generierung selbständig im resource-Folder nach der WSDL und sorgt dafür, dass die Klassen im Classpath landen. Zusätzlich konfiguriert es das jaxws-maven-plugin so, dass keine absoluten Pfade in die @WebServiceClient-annotierten Klassen generiert werden. So können diese uns keinen Ärger mehr machen, wenn unser CI-Server unseren Code auscheckt und die Pfade nicht auflösen kann.

Hört sich gut an! Wie fange ich an?

Damit die Vorteile des cxf-spring-boot-starter greifbar werden, schlage ich folgende Vorgehensweise vor: Wir ziehen ein Beispielprojekt mit allen Features komplett von 0 hoch und gehen dabei jedes Thema aus jedem bisherigen Artikel durch – natürlich in deutlich schnellerer Form. 😉 Wie immer gibt es in unserem Tutorial Repository ein Beispielprojekt, in dem sich alle Schritte nachvollziehen lassen .

Also los! Für die schnelle Projektanlage nutzen wir wie im ersten Artikel den Spring Initializr . Hier lassen wir unser Projekt per Generate Project erzeugen. Die generierte POM ist vom spring-boot-starter-parent abgeleitet und hängt von spring-boot-starter-test ab. Am Ende folgt noch das Build-Plugin spring-boot-maven-plugin.

Um unseren cxf-spring-boot-starter einzubinden, müssen wir nur die folgende Dependency in die POM einbinden (aktuell ist 1.0.7.RELEASE):

1<dependencies>
2    <dependency>
3        <groupId>de.codecentric</groupId>
4        <artifactId>cxf-spring-boot-starter</artifactId>
5        <version>1.0.7.RELEASE</version>
6    </dependency>
7</dependencies>

Danach binden wir noch das Build-Plugin cxf-spring-boot-starter-maven-plugin in die Build Section unserer POM ein (aktuell ist auch hier die 1.0.7.RELEASE):

1<build>
2    <plugins>
3        <plugin>
4            <groupId>de.codecentric</groupId>
5            <artifactId>cxf-spring-boot-starter-maven-plugin</artifactId>
6            <version>1.0.7.RELEASE</version>
7            <executions>
8                <execution>
9                    <goals>
10                        <goal>generate</goal>
11                    </goals>
12                </execution>
13            </executions>
14        </plugin>
15    </plugins>
16</build>

Durch einen Bug in logback 1.1.7 , der sich auf die Extraction der ein- und ausgehenden SOAP-XML-Nachrichten für einen Elastic-Stack auswirkt (da wir hierfür den logstash-logback-encoder einsetzen), müssen wir aktuell noch ein Downgrade von logback auf die 1.1.6 machen – das gilt natürlich nur, solange logback 1.1.8 noch nicht released ist und dieses Spring Boot nicht mitliefert:

1<properties>
2    <logback.version>1.1.6</logback.version>
3</properties>

Durchstarten

Nun legen wir unsere WSDL inkl. aller importierten XSDs unter src/main/resources (oder einem beliebigen Ordner darin) ab. In unserem Beispielprojekt liegen die Files wie gewohnt unter src/main/resources/service-api-definition . Wir müssen nicht einmal konfigurieren, wo wir unsere WSDL abgelegt haben 🙂 Wir können einfach die Generierung aller notwendigen Java-Klassen per mvn generate-sources veranlassen oder das Projekt einfach in unsere Lieblings-IDE importieren, die das im Hintergrund für uns übernimmt.

Für den letzten Schritt brauchen wir außerdem wieder eine das SEI implementierende Klasse WeatherServiceEndpoint , die wir ebenfalls wie gewohnt erstellen – später setzen wir hier wieder mit unserer fachlichen Implementierung auf. Danach legen wir eine @Configuration-annotierte Klasse an, in der wir unseren Endpoint hochziehen:

1@Configuration
2public class WebServiceConfiguration {
3 
4    @Autowired private SpringBus springBus;
5 
6    @Bean
7    public WeatherService weatherService() {
8        return new WeatherServiceEndpoint();
9    }
10 
11    @Bean
12    public Endpoint endpoint() {
13        EndpointImpl endpoint = new EndpointImpl(springBus, weatherService());
14        endpoint.setServiceName(weatherClient().getServiceName());
15        endpoint.setWsdlLocation(weatherClient().getWSDLDocumentLocation().toString());
16        endpoint.publish("/WeatherSoapService_1.0");
17        return endpoint;
18    }
19 
20    @Bean
21    public Weather weatherClient() {
22        return new Weather();
23    }
24}

Die Besonderheit des cxf-spring-boot-starters ist hier, dass wir Apache CXF gar nicht initialisieren müssen. Den für die Endpoint-Initialisierung benötigten org.apache.cxf.bus.spring.SpringBus können wir uns einfach autowiren lassen.

Und das war auch schon alles. 🙂 Wir können unsere SimpleBootCxfApplication per „RUN“ in unserer IDE starten oder per mvn spring-boot:run auf der Kommandozeile zum Leben erwecken. Ein kurzer Blick auf http://localhost:8080/soap-api bestätigt uns, dass Apache CXF hochgefahren ist und unser WebService registriert ist. Aufrufe per SoapUI funktionieren wunderbar.

SOAP Webservices testen

Nachdem wir den ersten Artikel damit schon abgedeckt haben, widmen wir uns dem Testen unserer SOAP-Services . Dabei lassen wir die Unit- & Integrationstests hier links liegen, denn die Auswirkungen auf diese beiden Typen durch den cxf-spring-boot-starter halten sich in Grenzen. Interessant wird es bei den Single System Integration Tests, denn hier müssen wir einen JAX-WS Client zur Verfügung haben, der unseren lokalen Server aufrufen kann – und dafür natürlich dessen URL benötigt. Die URL, auf der unsere WebServices zur Apache CXF publiziert werden, wird nun aber standardmäßig durch den cxf-spring-boot-starter festgelegt. Wir müssen also wissen, wie wir da rankommen.

Dazu nehmen wir uns den WeatherServiceXmlFileSystemTest aus dem zweiten Blogartikel. Er wird über die SimpleBootCxfSystemTestConfiguration konfiguriert – und hier setzen wir an. Wir autowiren uns die de.codecentric.cxf.configuration.CxfAutoConfiguration und greifen einfach per cxfAutoConfiguration.getBaseUrl() die benötigte URL ab. Dann sieht die Konfiguration unseres JAX-WS-Clients so aus:

1@Autowired private CxfAutoConfiguration cxfAutoConfiguration;
2 
3@Bean
4public WeatherService weatherServiceSystemTestClient() {
5    JaxWsProxyFactoryBean jaxWsProxyFactory = new JaxWsProxyFactoryBean();
6    jaxWsProxyFactory.setServiceClass(WeatherService.class);
7    jaxWsProxyFactory.setAddress("http://localhost:8090" + cxfAutoConfiguration.getBaseUrl() + SimpleBootCxfConfiguration.SERVICE_URL);
8    return (WeatherService) jaxWsProxyFactory.create();
9}

Um die Basis-URL unserer CXF-Endpoints anzupassen, reicht es übrigens, die application.properties um eine property soap.service.base.url zu erweitern und ihr einen entsprechenden Wert zu vergeben. Genauso einfach lässt sich übrigens der Titel der generierten Webseite anpassen, auf der CXF die verfügbaren Services zeigt – das geht per cxf.servicelist.title. Beides lässt sich auch in der application.properties unseres Beispielprojekts nachvollziehen.

Unser Testfall WeatherServiceXmlFileSystemTest ändert sich daneben nur leicht. Der cxf-spring-boot-starter bringt die praktische Utility-Klasse de.codecentric.cxf.common.XmlUtils, die uns die Arbeit mit dem Marshalling von XML Files in JAX-B Objekte innerhalb unserer Tests abnimmt:

1@RunWith(SpringRunner.class)
2@SpringBootTest(
3        classes=SimpleBootCxfSystemTestApplication.class,
4        webEnvironment= SpringBootTest.WebEnvironment.DEFINED_PORT,
5        properties = {"server.port=8090"}
6)
7public class WeatherServiceXmlFileSystemTest {
8 
9    @Autowired private WeatherService weatherServiceSystemTestClient;
10 
11    @Value(value="classpath:requests/GetCityForecastByZIPTest.xml")
12    private Resource getCityForecastByZIPTestXml;
13 
14    @Test
15    public void getCityForecastByZIP() throws WeatherException, IOException, BootStarterCxfException {
16        // Given
17        GetCityForecastByZIP getCityForecastByZIP = XmlUtils.readSoapMessageFromStreamAndUnmarshallBody2Object(getCityForecastByZIPTestXml.getInputStream(), GetCityForecastByZIP.class);
18 
19        // When
20        ForecastReturn forecastReturn = weatherServiceSystemTestClient.getCityForecastByZIP(getCityForecastByZIP.getForecastRequest());
21 
22        // Then
23        assertNotNull(forecastReturn);
24        assertEquals(true, forecastReturn.isSuccess());
25        ...
26    }
27}

Okay, es gibt natürlich eine weitere Änderung. Die bezieht sich allerdings auf die neuen Testfeatures von Spring Boot 1.4.x, die in der Klasse org.springframework.boot.test.context.SpringBootTest zusammengefasst wurden. Diese ersetzt alle vorher notwendigen Testannotations – wie @WebIntegrationTest, @SpringApplicationConfiguration, @ContextConfiguration usw. (siehe dazu auch den spring.io blogpost ). Außerdem verkürzt der SpringRunner die lästige Tipperei mit dem SpringJUnit4ClassRunner.

Und das war es dann auch schon zum Thema „Testen von SOAP-WebServices“.

XML-Validierung und Custom SOAP Faults

Das Fazit des dritten Blogposts lässt nicht unbedingt ein gutes Haar an den vielen Schritten, die notwendig sind, um auf XML-Validierungsfehler in einer XML-Schema-konformen Weise zu reagieren. Da diese Anforderung gerade im Enterprise-Bereich aber häufiger vorkommt (siehe BiPro), vereinfacht uns der cxf-spring-boot-starter das Leben hier erheblich.

Wir können im Grunde alle Schritte aus dem dritten Artikel getrost wieder vergessen und implementieren stattdessen das Interface de.codecentric.cxf.xmlvalidation.CustomFaultBuilder. Das ist auch schon alles.

Im Detail heißt das: Wir überschreiben zwei Methoden – createCustomFaultMessage(FaultType faultType) bietet uns dabei die Möglichkeit, die Fault-Message in unserem Soap Fault zu beeinflussen. Durch den übergebenen de.codecentric.cxf.common.FaultType wissen wir auch, ob es sich um einen XML-Schema-Validierungsfehler oder grundsätzlich inkorrektes XML handelt. Durch das Design des cxf-spring-boot-starter können wir hier sogar auf Fehler reagieren, die gar nicht durch fehlerhafte XMLs bedingt sind und dadurch wirklich immer Schema-konforme Fehlerantworten liefern.
Mithilfe der Methode createCustomFaultDetail(String originalFaultMessage, FaultType faultType) bauen wir uns unsere XML-Schema-konforme Fehlernachricht zusammen. Beides sehen wir in der Klasse WeatherFaultBuilder unseres Beispielprojekts:

1@Component
2public class WeatherFaultBuilder implements CustomFaultBuilder {
3 
4    private de.codecentric.namespace.weatherservice.exception.ObjectFactory objectFactoryDatatypes = new de.codecentric.namespace.weatherservice.exception.ObjectFactory();
5 
6    @Override
7    public String createCustomFaultMessage(FaultType faultType) {
8        if(FaultType.SCHEME_VALIDATION_ERROR.equals(faultType))
9            return CustomIds.NON_XML_COMPLIANT.getMessage();
10        else if(FaultType.SYNTACTICALLY_INCORRECT_XML_ERROR.equals(faultType))
11            return CustomIds.COMPLETE_USELESS_XML.getMessage();
12        else
13            return CustomIds.SOMETHING_ELSE_WENT_TERRIBLY_WRONG.getMessage();
14    }
15 
16    @Override
17    public WeatherException createCustomFaultDetail(String originalFaultMessage, FaultType faultType) {
18        // Build SOAP-Fault detail <datatypes:WeatherException>
19        WeatherException weatherException = objectFactoryDatatypes.createWeatherException();
20        weatherException.setBigBusinessErrorCausingMoneyLoss(true);
21        setIdBasedUponFaultContent(faultType, weatherException);
22        weatherException.setExceptionDetails(originalFaultMessage);
23        weatherException.setUuid("ExtremeRandomNumber");
24        return weatherException;
25    }
26...
27}

In der Methode createCustomFaultDetail(String originalFaultMessage, FaultType faultType) sollten wir darauf achten, die korrekte Exception zurückzuliefern. Hier kommt es bei manchen Spezifikationen zu Doppelungen, wie auch bei den BiPro-WebServices. Alles, was nun noch zu tun bleibt, ist die @Component-annotierte Klasse in unserer Spring-Konfiguration als Bean zu definieren. Und: das war es dann auch schon (wieder).

Natürlich trauen wir hier dem Autor nicht – und wollen einen Testfall sehen. Das kann ja wohl nicht so einfach gewesen sein. 🙂 Und auch für diesen Fall bringt der cxf-spring-boot-starter etwas mit: den de.codecentric.cxf.soaprawclient.SoapRawClient. Mit seiner Hilfe können wir nicht XML-Schema-konformes XML gegen unseren Endpoint schicken – damit wir überhaupt die XML-Validierungsfehler provozieren können, auf die wir ja Schema-konform antworten wollen.

Dazu nutzen wir den WeatherServiceXmlErrorSystemTest aus dem dritten Artikel – einen Single System Integration Test, der die gewünschten Validierungsfehler provoziert und prüft, ob unser Endpoint ebenfalls Schema-konform antwortet. Wir erweitern ihn nur an wenigen Stellen. Neben den obligatorischen Spring-Boot-1.4.x-Änderungen tauschen wir in unserem Testfall WeatherServiceXmlErrorSystemTest unsere selbst implementierten Konstanten gegen die im cxf-spring-boot-starter mitgelieferten in der Klasse de.codecentric.cxf.common.FaultType aus und prüfen auf den in unserem implementierten CustomFaultBuilder festgelegten Fehlertext:

1assertEquals(WeatherFaultBuilder.CUSTOM_ERROR_MSG, soapRawResponse.getFaultstringValue());

Die Konfiguration unterscheidet sich nur durch die CxfAutoConfiguration, die wir für die URL benötigen:

1@Autowired private CxfAutoConfiguration cxfAutoConfiguration;
2 
3@Bean
4public SoapRawClient soapRawClient() throws BootStarterCxfException {
5    return new SoapRawClient(buildUrl(), WeatherService.class);
6}
7 
8private String buildUrl() {
9    // return something like http://localhost:8084/soap-api/WeatherSoapService
10    return "http://localhost:8087"
11            + cxfAutoConfiguration.getBaseUrl()
12            + SimpleBootCxfConfiguration.SERVICE_URL;
13}

Führen wir unseren WeatherServiceXmlErrorSystemTest nun aus, gehen alle Lampen auf grün. Außerdem können wir per SoapUI die XML-Schema-konformen Fehlernachrichten bestaunen. In jedem Fall sind wir schnellstmöglich mit unseren eigenen Custom SOAP Faults am Start.

Logging & Monitoring mit Logback, Elasticsearch, Logstash & Kibana

Und schon sind wir beim letzten Artikel der Serie angelangt. Gerade das Thema Logging kann durchaus in Arbeit ausarten – und auch hier untersützt uns der cxf-spring-boot-starter massiv. Mit seiner Hilfe läuft alles Logging standardmäßig über slf4j und logback. Zum Loggen der SOAP-Nachrichten müssen wir nur die Property soap.messages.logging in unseren application.properties auf true setzen. Schon sehen wir die ein- und ausgehenden Nachrichten in unserem Logfile oder in der Console.

Beim Loggen in einen Elastic-Stack nimmt uns der cxf-spring-boot-starter ebenfalls die meiste Arbeit ab. Die einzigen Voraussetzungen sind die Property soap.messages.extract=true in application.properties und das Vorhandensein einer logback-spring.xml, die genauso wie im letzten Artikel beschrieben aussehen kann:

1<?xml version="1.0" encoding="UTF-8"?>
2<configuration>
3    <include resource="org/springframework/boot/logging/logback/base.xml"/>
4    <logger name="org.springframework" level="WARN"/>
5    <logger name="de.jonashackt.tutorial" level="DEBUG"/>
6    <logger name="org.apache.cxf" level="INFO"/>
7 
8    <!-- Logstash-Configuration -->
9    <appender name="logstash" class="net.logstash.logback.appender.LogstashTcpSocketAppender">
10        <destination>192.168.99.100:5000</destination>
11        <encoder class="net.logstash.logback.encoder.LogstashEncoder">
12            <customFields>{"service_name":"WeatherService 1.0"}</customFields>
13            <fieldNames>
14                <message>log_msg</message>
15            </fieldNames>
16        </encoder>
17        <keepAliveDuration>5 minutes</keepAliveDuration>
18    </appender>
19 
20  <root level="INFO">
21        <appender-ref ref="logstash" />
22  </root>
23</configuration>

Hat man einen Elastic-Stack am Laufen (dafür gibt es ebenfalls Tipps im letzten Artikel ), war es das auch schon wieder. Zusätzlich ist sogar noch mehr als nur reines Logging aktiv. Z.B. landen SOAP-Messages automatisch in den eigenen Custom Fields soap-message-inbound und soap-message-outbound, die sich viel besser auswerten lassen. Diese sind über eine Enumeration in de.codecentric.cxf.logging.ElasticsearchField definiert.

Außerdem werden alle zu einem SOAP-Request gehörenden Log-Events automatisch korreliert, und der cxf-spring-boot-starter versucht den Methodennamen des SOAP-Services zu ermitteln (was momentan allerdings auf die WSDL Specification 1.1 beschränkt ist). Diese landet automatisch im Custom Field soap-method-name. Damit hat man aus dem Stegreif praktisch alles an Bord, was man fürs Logging von SOAP-Services braucht.

Von 0 auf SOAP… Fertig!

Nun haben wir alle Voraussetzungen, noch schneller SOAP Endpoints zu entwickeln – und trotzdem vom Start weg alle notwendigen Features verfügbar zu haben, die man im Enterprise-Umfeld gebrauchen kann. Alles in vier Blogartikeln Besprochene haben wir an Bord. Liest man alle vorangegangenen Artikel, wird klar, was das heißt.

Und falls doch mal eine Funktion fehlen sollte – kein Problem: Der cxf-spring-boot-starter freut sich immer über Mitarbeit. Hier zeigt sich auch wieder die Power von Open Source: Man profitiert im eigenen Projekt und kann gleichzeitig über eigene Contributions wieder etwas zurückgeben.

Wir wünschen viel Spaß mit dem cxf-spring-boot-starter und freuen uns über Feedback und Pull Requests! 🙂