XML Support

Akka HTTP’s marshalling and unmarshalling infrastructure makes it rather easy to seamlessly support specific wire representations of your data objects, like JSON, XML or even binary encodings.

Akka HTTP does not currently provide a Java API for XML support. If you need to produce and consume XML, you can write a custom marshaller using Jackson, which is also the library used for providing JSON support.

sourceimport java.io.IOException;
import java.util.List;
import java.util.Arrays;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.dataformat.xml.XmlMapper;
import akka.http.javadsl.model.*;
import akka.http.javadsl.marshalling.Marshaller;
import akka.http.javadsl.unmarshalling.Unmarshaller;

public class JacksonXmlSupport {
  private static final ObjectMapper DEFAULT_XML_MAPPER =
    new XmlMapper().enable(SerializationFeature.WRAP_ROOT_VALUE);
  private static final List<MediaType> XML_MEDIA_TYPES = Arrays.asList(MediaTypes.APPLICATION_XML, MediaTypes.TEXT_XML);

  public static <T> Marshaller<T, RequestEntity> marshaller() {
    return Marshaller.wrapEntity(
      u -> toXML(DEFAULT_XML_MAPPER, u),
      Marshaller.stringToEntity(),
      MediaTypes.APPLICATION_XML
    );
  }

  public static <T> Unmarshaller<HttpEntity, T> unmarshaller(Class<T> expectedType) {
    return Unmarshaller.forMediaTypes(XML_MEDIA_TYPES, Unmarshaller.entityToString())
                       .thenApply(xml -> fromXML(DEFAULT_XML_MAPPER, xml, expectedType));
  }

  private static <T> String toXML(ObjectMapper mapper, T object) {
    try {
      return mapper.writeValueAsString(object);
    } catch (IOException e) {
      throw new IllegalArgumentException("Cannot marshal to XML: " + object, e);
    }
  }

  private static <T> T fromXML(ObjectMapper mapper, String xml, Class<T> expectedType) {
    try {
      return mapper.readerFor(expectedType).readValue(xml);
    } catch (IOException e) {
      throw new IllegalArgumentException("Cannot unmarshal XML as " + expectedType.getSimpleName(), e);
    }
  }
}

The custom XML (un)marshalling code shown above requires that you depend on the jackson-dataformat-xml library.

The Akka dependencies are available from Akka’s library repository. To access them there, you need to configure the URL for this repository.

sbt
resolvers += "Akka library repository".at("https://repo.akka.io/maven")
Gradle
repositories {
    mavenCentral()
    maven {
        url "https://repo.akka.io/maven"
    }
}
Maven
<project>
  ...
  <repositories>
    <repository>
      <id>akka-repository</id>
      <name>Akka library repository</name>
      <url>https://repo.akka.io/maven</url>
    </repository>
  </repositories>
</project>

Additionally, add the dependency as below.

sbt
libraryDependencies += "com.fasterxml.jackson.dataformat" % "jackson-dataformat-xml" % "2.15.4"
Gradle
dependencies {
  implementation "com.fasterxml.jackson.dataformat:jackson-dataformat-xml:2.15.4"
}
Maven
<dependencies>
  <dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-xml</artifactId>
    <version>2.15.4</version>
  </dependency>
</dependencies>

For XML Akka HTTP currently provides support for Scala XML right out of the box through it’s akka-http-xml module.

Scala XML Support

The ScalaXmlSupport trait provides a FromEntityUnmarshaller[NodeSeq] and ToEntityMarshaller[NodeSeq] that you can use directly or build upon.

In order to enable support for (un)marshalling from and to XML with Scala XML NodeSeq you must add the following dependency:

sbt
val AkkaHttpVersion = "10.6.3"
libraryDependencies += "com.typesafe.akka" %% "akka-http-xml" % AkkaHttpVersion
Gradle
def versions = [
  ScalaBinary: "2.13"
]
dependencies {
  implementation platform("com.typesafe.akka:akka-http-bom_${versions.ScalaBinary}:10.6.3")

  implementation "com.typesafe.akka:akka-http-xml_${versions.ScalaBinary}"
}
Maven
<properties>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.typesafe.akka</groupId>
      <artifactId>akka-http-bom_${scala.binary.version}</artifactId>
      <version>10.6.3</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
<dependencies>
  <dependency>
    <groupId>com.typesafe.akka</groupId>
    <artifactId>akka-http-xml_${scala.binary.version}</artifactId>
  </dependency>
</dependencies>

Once you have done this (un)marshalling between XML and NodeSeq instances should work nicely and transparently, by either using import akka.http.scaladsl.marshallers.xml.ScalaXmlSupport._ or mixing in the akka.http.scaladsl.marshallers.xml.ScalaXmlSupport trait.

Found an error in this documentation? The source code for this page can be found here. Please feel free to edit and contribute a pull request.