Micronaut Jackson XML

Jackson XML support for Micronaut

Version: 4.5.0

1 Introduction

When this library is added to a Micronaut application, it creates the beans necessary to allow for the serialization and deserialization of XML. Both the client and server are supported in a similar manner to the standard support of JSON. Jackson is used to do the conversion of the XML to objects.

Because XML has no array boundaries, the entire request body must be buffered into memory before deserialization can occur. The standard request body size limits apply here as well.

2 Dependency

To use Micronaut Jackson XML add the following dependency:

implementation("io.micronaut.xml:micronaut-jackson-xml")

<dependency>
    <groupId>io.micronaut.xml</groupId>
    <artifactId>micronaut-jackson-xml</artifactId>
</dependency>

See the Jackson XML documentation for more information.

3 Example

To send an XML document such as:

<book>
    <name>Huckleberry Finn</name>
</book>

You could define a POJO such as the following:

package io.micronaut.xml.jackson.docs;

import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlRootElement;
import io.micronaut.core.annotation.Introspected;

@Introspected
@JacksonXmlRootElement(localName = "book")
public record Book(String name) {
}

package io.micronaut.xml.jackson.docs

import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlRootElement
import io.micronaut.core.annotation.Introspected
import io.micronaut.core.annotation.NonNull

@Introspected
@JacksonXmlRootElement(localName = "book")
class Book {
    @NonNull
    String name
}

package io.micronaut.xml.jackson.docs

import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlRootElement
import io.micronaut.core.annotation.Introspected

@Introspected
@JacksonXmlRootElement(localName = "book")
data class Book(val name: String)

To return an XML document such as:

<book isbn="f594e59e-6c2d-41b3-ba77-a3aabafceae4">
    <name>Huckleberry Finn</name>
</book>

You could define a POJO such as the following:

package io.micronaut.xml.jackson.docs;

import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlProperty;
import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlRootElement;
import io.micronaut.core.annotation.Introspected;
import io.micronaut.core.annotation.NonNull;

@JacksonXmlRootElement(localName = "book")
@Introspected
public class BookSaved {

    @NonNull
    private final String name;

    @NonNull
    @JacksonXmlProperty(isAttribute = true)
    private final String isbn;

    public BookSaved(String name, String isbn) {
        this.name = name;
        this.isbn = isbn;
    }

    @NonNull
    public String getName() {
        return name;
    }

    @NonNull
    public String getIsbn() {
        return isbn;
    }
}

package io.micronaut.xml.jackson.docs

import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlProperty
import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlRootElement
import io.micronaut.core.annotation.Introspected
import io.micronaut.core.annotation.NonNull

@JacksonXmlRootElement(localName = "book")
@Introspected
class BookSaved {
    String name

    @NonNull
    @JacksonXmlProperty(isAttribute = true)
    String isbn
}

package io.micronaut.xml.jackson.docs;

import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlProperty
import com.fasterxml.jackson.dataformat.xml.annotation.JacksonXmlRootElement
import io.micronaut.core.annotation.Introspected

@JacksonXmlRootElement(localName = "book")
@Introspected
data class BookSaved(val name: String, @field:JacksonXmlProperty(isAttribute = true) val isbn: String)

To receive and send XML from a Micronaut Controller, you can specify the Accept HTTP header and the response Content-Type with the @Produces and @Consumes annotations.

package io.micronaut.xml.jackson.docs;

import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Body;
import io.micronaut.http.annotation.Consumes;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Post;
import io.micronaut.http.annotation.Produces;
import java.util.UUID;

@Controller
public class BookController {

    @Consumes(MediaType.APPLICATION_XML)
    @Produces(MediaType.APPLICATION_XML)
    @Post("/book")
    public BookSaved save(@Body Book book) {
        return new BookSaved(book.name(), UUID.randomUUID().toString());
    }
}

package io.micronaut.xml.jackson.docs;

import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Body;
import io.micronaut.http.annotation.Consumes;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Post;
import io.micronaut.http.annotation.Produces;

@Controller
class BookController {

    @Consumes(MediaType.APPLICATION_XML)
    @Produces(MediaType.APPLICATION_XML)
    @Post("/book")
    BookSaved save(@Body Book book) {
        new BookSaved(name: book.getName(), isbn: UUID.randomUUID().toString())
    }
}

package io.micronaut.xml.jackson.docs

import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Body
import io.micronaut.http.annotation.Consumes
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Post
import io.micronaut.http.annotation.Produces
import java.util.*

@Controller
class BookController {

    @Consumes(MediaType.APPLICATION_XML)
    @Produces(MediaType.APPLICATION_XML)
    @Post("/book")
    fun save(@Body book: Book) = BookSaved(book.name, UUID.randomUUID().toString())
}

Moreover, you can send and receive XML with the Micronaut HTTP Client.

package io.micronaut.xml.jackson.docs;

import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Body;
import io.micronaut.http.annotation.Consumes;
import io.micronaut.http.annotation.Post;
import io.micronaut.http.annotation.Produces;
import io.micronaut.http.client.annotation.Client;

@Client("/")
public interface BookClient {
    @Consumes(MediaType.APPLICATION_XML)
    @Produces(MediaType.APPLICATION_XML)
    @Post("/book")
    BookSaved save(@Body Book book);
}

package io.micronaut.xml.jackson.docs

import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Body
import io.micronaut.http.annotation.Consumes
import io.micronaut.http.annotation.Post
import io.micronaut.http.annotation.Produces
import io.micronaut.http.client.annotation.Client

@Client("/")
interface BookClient {
    @Consumes(MediaType.APPLICATION_XML)
    @Produces(MediaType.APPLICATION_XML)
    @Post("/book")
    BookSaved save(@Body Book book)
}

package io.micronaut.xml.jackson.docs

import io.micronaut.http.MediaType
import io.micronaut.http.annotation.Body
import io.micronaut.http.annotation.Consumes
import io.micronaut.http.annotation.Post
import io.micronaut.http.annotation.Produces
import io.micronaut.http.client.annotation.Client

@Client("/")
@Consumes(MediaType.APPLICATION_XML)
@Produces(MediaType.APPLICATION_XML)
interface BookClient {
    @Consumes(MediaType.APPLICATION_XML)
    @Produces(MediaType.APPLICATION_XML)
    @Post("/book")
    fun save(@Body book: Book): BookSaved
}

4 Release History

For this project, you can find a list of releases (with release notes) here:

https://github.com/micronaut-projects/micronaut-jackson-xml/releases

5 Repository

You can find the source code of this project in this repository:

https://github.com/micronaut-projects/micronaut-jackson-xml

6 Breaking Changes

Micronaut Jackson XML BOM modules' coordinates have changed from io.micronaut.xml:micronaut-jackson-bom to io.micronaut.xml:micronaut-jackson-xml-bom.