feign-soap-jakarta module like feign-soap, but with feign-jaxb-jakart…

…a instead of feign-jaxb (#2094)

* soap-jakarta module like soap, but with jaxb-jakarta

* require java 11

* add SOAP Jakarta and JAXB Jakarta to the feature list

---------

Co-authored-by: Marvin Froeder <[email protected]>

pom.xml

@@ -48,6 +48,7 @@
     <module>slf4j</module>
     <module>spring4</module>
     <module>soap</module>
+    <module>soap-jakarta</module>
     <module>reactive</module>
     <module>dropwizard-metrics4</module>
     <module>dropwizard-metrics5</module>

soap-jakarta/README.md

@@ -0,0 +1,57 @@
+SOAP Codec
+===================
+
+This module adds support for encoding and decoding SOAP Body objects via JAXB and SOAPMessage. It also provides SOAPFault decoding capabilities by wrapping them into the original `javax.xml.ws.soap.SOAPFaultException`, so that you'll only need to catch `SOAPFaultException` in order to handle SOAPFault.
+
+Add `SOAPEncoder` and/or `SOAPDecoder` to your `Feign.Builder` like so:
+
+```java
+public interface MyApi {
+
+    @RequestLine("POST /getObject")
+    @Headers({
+      "SOAPAction: getObject",
+      "Content-Type: text/xml"
+    })
+    MyJaxbObjectResponse getObject(MyJaxbObjectRequest request);
+
+ }
+
+ ...
+
+ JAXBContextFactory jaxbFactory = new JAXBContextFactory.Builder()
+     .withMarshallerJAXBEncoding("UTF-8")
+     .withMarshallerSchemaLocation("http://apihost http://apihost/schema.xsd")
+     .build();
+
+ api = Feign.builder()
+     .encoder(new SOAPEncoder(jaxbFactory))
+     .decoder(new SOAPDecoder(jaxbFactory))
+     .target(MyApi.class, "http://api");
+
+ ...
+
+ try {
+    api.getObject(new MyJaxbObjectRequest());
+ } catch (SOAPFaultException faultException) {
+    log.info(faultException.getFault().getFaultString());
+ }
+
+```
+
+Because a SOAP Fault can be returned as well with a 200 http code than a 4xx or 5xx HTTP error code (depending on the used API), you may also use `SOAPErrorDecoder` in your API configuration, in order to be able to catch `SOAPFaultException` in case of SOAP Fault. Add it, like below:
+
+```java
+api = Feign.builder()
+     .encoder(new SOAPEncoder(jaxbFactory))
+     .decoder(new SOAPDecoder(jaxbFactory))
+     .errorDecoder(new SOAPErrorDecoder())
+     .target(MyApi.class, "http://api");
+```
+
+In certain situations the declarations on the SOAP envelope are not inherited by JAXB when reading the documents.  This is particularly
+troublesome when it is not possible to correct the XML at the source.
+
+To account for this situation, use the `useFirstChild` option on the `SOAPDecoder` builder.  This will instruct JAX be to use `SOAPBody#getFirstChild()`
+instead of `SOAPBody#extractContentAsDocument()`.  This will allow users to supply a `package-info.java` to manage the element namespaces
+explicitly and define what should occur if the namespace declarations are missing.

soap-jakarta/pom.xml

@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright 2012-2023 The Feign Authors
+
+    Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+    in compliance with the License. You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software distributed under the License
+    is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+    or implied. See the License for the specific language governing permissions and limitations under
+    the License.
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>io.github.openfeign</groupId>
+    <artifactId>parent</artifactId>
+    <version>12.4-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>feign-soap-jakarta</artifactId>
+  <name>Feign SOAP Jakarta</name>
+  <description>Feign SOAP CoDec</description>
+
+  <properties>
+    <main.java.version>11</main.java.version>
+    <maven.compiler.source>11</maven.compiler.source>
+    <maven.compiler.target>11</maven.compiler.target>
+    <main.basedir>${project.basedir}/..</main.basedir>
+
+    <moditect.skip>true</moditect.skip>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>${project.groupId}</groupId>
+      <artifactId>feign-core</artifactId>
+    </dependency>
+
+    <dependency>
+      <groupId>${project.groupId}</groupId>
+      <artifactId>feign-jaxb-jakarta</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+
+    <dependency>
+      <groupId>${project.groupId}</groupId>
+      <artifactId>feign-core</artifactId>
+      <type>test-jar</type>
+      <scope>test</scope>
+    </dependency>
+
+    <dependency>
+      <groupId>jakarta.xml.ws</groupId>
+      <artifactId>jakarta.xml.ws-api</artifactId>
+      <version>4.0.0</version>
+    </dependency>
+    <dependency>
+      <groupId>jakarta.xml.soap</groupId>
+      <artifactId>jakarta.xml.soap-api</artifactId>
+      <version>3.0.0</version>
+    </dependency>
+    <dependency>
+      <groupId>jakarta.xml.bind</groupId>
+      <artifactId>jakarta.xml.bind-api</artifactId>
+      <version>4.0.0</version>
+    </dependency>
+    <dependency>
+      <groupId>com.sun.xml.messaging.saaj</groupId>
+      <artifactId>saaj-impl</artifactId>
+      <version>3.0.2</version>
+    </dependency>
+    <dependency>
+      <groupId>com.sun.xml.bind</groupId>
+      <artifactId>jaxb-impl</artifactId>
+      <version>4.0.3</version>
+      <scope>runtime</scope>
+    </dependency>
+  </dependencies>
+
+</project>

soap-jakarta/src/main/java/feign/soap/SOAPDecoder.java

@@ -0,0 +1,179 @@
+/*
+ * Copyright 2012-2023 The Feign Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package feign.soap;
+
+import feign.Response;
+import feign.Util;
+import feign.codec.DecodeException;
+import feign.codec.Decoder;
+import feign.jaxb.JAXBContextFactory;
+import jakarta.xml.bind.JAXBException;
+import jakarta.xml.bind.Unmarshaller;
+import jakarta.xml.soap.*;
+import jakarta.xml.ws.soap.SOAPFaultException;
+import java.io.IOException;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+
+/**
+ * Decodes SOAP responses using SOAPMessage and JAXB for the body part. <br>
+ *
+ * <p>
+ * The JAXBContextFactory should be reused across requests as it caches the created JAXB contexts.
+ *
+ * <p>
+ * A SOAP Fault can be returned with a 200 HTTP code. Hence, faults could be handled with no error
+ * on the HTTP layer. In this case, you'll certainly have to catch {@link SOAPFaultException} to get
+ * fault from your API client service. In the other case (Faults are returned with 4xx or 5xx HTTP
+ * error code), you may use {@link SOAPErrorDecoder} in your API configuration.
+ *
+ * <pre>
+ *
+ * public interface MyApi {
+ *
+ *    &#64;RequestLine("POST /getObject")
+ *    &#64;Headers({
+ *      "SOAPAction: getObject",
+ *      "Content-Type: text/xml"
+ *    })
+ *    MyJaxbObjectResponse getObject(MyJaxbObjectRequest request);
+ *
+ * }
+ *
+ * ...
+ *
+ * JAXBContextFactory jaxbFactory = new JAXBContextFactory.Builder()
+ *     .withMarshallerJAXBEncoding(&quot;UTF-8&quot;)
+ *     .withMarshallerSchemaLocation(&quot;http://apihost http://apihost/schema.xsd&quot;)
+ *     .build();
+ *
+ * api = Feign.builder()
+ *     .decoder(new SOAPDecoder(jaxbFactory))
+ *     .target(MyApi.class, &quot;http://api&quot;);
+ *
+ * ...
+ *
+ * try {
+ *    api.getObject(new MyJaxbObjectRequest());
+ * } catch (SOAPFaultException faultException) {
+ *    log.info(faultException.getFault().getFaultString());
+ * }
+ * </pre>
+ *
+ * @see SOAPErrorDecoder
+ * @see SOAPFaultException
+ */
+public class SOAPDecoder implements Decoder {
+
+  private final JAXBContextFactory jaxbContextFactory;
+  private final String soapProtocol;
+  private final boolean useFirstChild;
+
+  public SOAPDecoder(JAXBContextFactory jaxbContextFactory) {
+    this.jaxbContextFactory = jaxbContextFactory;
+    this.soapProtocol = SOAPConstants.DEFAULT_SOAP_PROTOCOL;
+    this.useFirstChild = false;
+  }
+
+  private SOAPDecoder(Builder builder) {
+    this.soapProtocol = builder.soapProtocol;
+    this.jaxbContextFactory = builder.jaxbContextFactory;
+    this.useFirstChild = builder.useFirstChild;
+  }
+
+  @Override
+  public Object decode(Response response, Type type) throws IOException {
+    if (response.status() == 404)
+      return Util.emptyValueOf(type);
+    if (response.body() == null)
+      return null;
+    while (type instanceof ParameterizedType) {
+      ParameterizedType ptype = (ParameterizedType) type;
+      type = ptype.getRawType();
+    }
+    if (!(type instanceof Class)) {
+      throw new UnsupportedOperationException(
+          "SOAP only supports decoding raw types. Found " + type);
+    }
+
+    try {
+      SOAPMessage message =
+          MessageFactory.newInstance(soapProtocol)
+              .createMessage(null, response.body().asInputStream());
+      if (message.getSOAPBody() != null) {
+        if (message.getSOAPBody().hasFault()) {
+          throw new SOAPFaultException(message.getSOAPBody().getFault());
+        }
+
+        Unmarshaller unmarshaller = jaxbContextFactory.createUnmarshaller((Class<?>) type);
+
+        if (this.useFirstChild) {
+          return unmarshaller.unmarshal(message.getSOAPBody().getFirstChild());
+        } else {
+          return unmarshaller.unmarshal(message.getSOAPBody().extractContentAsDocument());
+        }
+      }
+    } catch (SOAPException | JAXBException e) {
+      throw new DecodeException(response.status(), e.toString(), response.request(), e);
+    } finally {
+      if (response.body() != null) {
+        response.body().close();
+      }
+    }
+    return Util.emptyValueOf(type);
+  }
+
+  public static class Builder {
+    String soapProtocol = SOAPConstants.DEFAULT_SOAP_PROTOCOL;
+    JAXBContextFactory jaxbContextFactory;
+    boolean useFirstChild = false;
+
+    public Builder withJAXBContextFactory(JAXBContextFactory jaxbContextFactory) {
+      this.jaxbContextFactory = jaxbContextFactory;
+      return this;
+    }
+
+    /**
+     * The protocol used to create message factory. Default is "SOAP 1.1 Protocol".
+     *
+     * @param soapProtocol a string constant representing the MessageFactory protocol.
+     * @see SOAPConstants#SOAP_1_1_PROTOCOL
+     * @see SOAPConstants#SOAP_1_2_PROTOCOL
+     * @see SOAPConstants#DYNAMIC_SOAP_PROTOCOL
+     * @see MessageFactory#newInstance(String)
+     */
+    public Builder withSOAPProtocol(String soapProtocol) {
+      this.soapProtocol = soapProtocol;
+      return this;
+    }
+
+    /**
+     * Alters the behavior of the code to use the {@link SOAPBody#getFirstChild()} in place of
+     * {@link SOAPBody#extractContentAsDocument()}.
+     *
+     * @return the builder instance.
+     */
+    public Builder useFirstChild() {
+      this.useFirstChild = true;
+      return this;
+    }
+
+    public SOAPDecoder build() {
+      if (jaxbContextFactory == null) {
+        throw new IllegalStateException("JAXBContextFactory must be non-null");
+      }
+      return new SOAPDecoder(this);
+    }
+  }
+}