Spincast - Plugins - Spincast Jackson XML

Overview

This plugin provides XML functionalities using Jackson. It contains an implementation of the XmlManager interface : SpincastXmlManager.

Make sure you read the Jackson documentation for more information.

Installation

If you use the spincast-default artifact and the standard Bootstrapper, this plugin is already installed by default so you have nothing to do!

If you start from scratch, using the spincast-core artifact, you can use the plugin by :

1. Adding this Maven artifact to your project:

<dependency>
    <groupId>org.spincast</groupId>
    <artifactId>spincast-plugins-jackson-xml</artifactId>
    <version>2.2.0</version>
</dependency>

2. Installing the provided SpincastJacksonXmlPluginModule module to your Guice context.

Plugin class

The class implementing the SpincastPlugin interface is SpincastJacksonXmlPlugin.

Suggested add-on

Name : xml()
Component : XmlManager
Usage : to give your Route Handlers access to XML functionalitites.

Example :

public void myRouteHandler(DefaultRequestContext context) {

    // Converts a user object to XML
    String xml = context.xml().toXml(userObj);
    
    //...
}

This add-on is already installed by default on the Request Context type.

Javadoc

Main configurations

You can bind a SpincastXmlManagerConfig implementation to tweak the default configurations used by the components this plugin provides. By default, the SpincastXmlManagerConfigDefault class is used as the implementation.

(De)serialization configurations

Jackson allows some configuration when serializing and deserializing an object.

Most of those configurations are defined using annotations. You can annotate the objects directly, or you can use mix-ins.

Annotating the objects :

If you don't minds annotating your objects with Jackson specific annotations, this is maybe the simplest thing to do. For example, let's say you have a User class that has two fields, name and title, and you don't want to keep the title field when you serialize an instance of this class:

public class User implements User {

    private String name;
    private String title;

    @Override
    public String getName() {
        return this.name;
    }

    @Override
    public void setName(String name) {
        this.name = name;
    }

    @Override
    public String getTitle() {
        return this.title;
    }

    @Override
    public void setTitle(String title) {
        this.title = title;
    }
}

To ignore the title field to be included during the serialization, you can simply annotate the getTitle() method with @JsonIgnore (yes, you use the same annotations than the ones for Json mix-ins):

public class User implements User {

    private String name;
    private String title;

    @Override
    public String getName() {
        return this.name;
    }

    @Override
    public void setName(String name) {
        this.name = name;
    }

    @Override
    @JsonIgnore
    public String getTitle() {
        return this.title;
    }

    @Override
    public void setTitle(String title) {
        this.title = title;
    }
}

If you serialize an instance of this class using the XML Manager, only the name property would be kept:

User user = new User();
user.setName("Stromgol");
user.setTitle("alien");

String xml = getXmlManager().toXml(user);
assertNotNull(xml);
assertEquals("<User><name>Stromgol</name></User>", xml);

Using mix-ins:

Many developers (us included) don't like to pollute their model classes with too many annotations. Lucky us, Jackson provides a way to configure objects from the outside, without annotating the objects directly, by using what is called mix-ins annotations.

Let's start with the same User class, without any Jackson annotations:

public class User implements User {

    private String name;
    private String title;

    @Override
    public String getName() {
        return this.name;
    }

    @Override
    public void setName(String name) {
        this.name = name;
    }

    @Override
    public String getTitle() {
        return this.title;
    }

    @Override
    public void setTitle(String title) {
        this.title = title;
    }
}

To use XML mix-ins in a Spincast application, you first need to create the mix-in abstract class. Interfaces work too, but only to annotate methods, not fields.

An example mix-in for our User objects:

public abstract class UserMixin implements User {

    // Ignore this property!
    @Override
    @JsonIgnore
    public abstract String getTitle();
}

As you can see, a mix-in extends the class/interface to configure, and adds the Jackson annotations on the overriding fields or methods declarations.

Once the mix-in is defined, you have to register it, in your custom Guice module:

public class AppModule extends SpincastDefaultGuiceModule {

    public AppModule(String[] mainArgs) {
        super(mainArgs);
    }

    @Override
    protected void configure() {
        super.configure();

        bindXmlMixins();
        
        //...
    }

    protected void bindXmlMixins() {

        Multibinder<XmlMixinInfo> xmlMixinsBinder = Multibinder.newSetBinder(binder(), XmlMixinInfo.class);
        xmlMixinsBinder.addBinding().toInstance(new XmlMixinInfo(User.class, UserMixin.class));
    }
}

Explanation :

18 : A multibinder is used to collect the various mix-ins to register. The advantage of a multibinder is that it allows to register mix-ins from any Guice module. For example, some plugins may want to register their mix-ins, and you may want to register your custom ones.
19 : We register our mix-in, by binding a XmlMixinInfo instance, which specifies the class to configure, and the class of the mix-in used to configure it.

With this in place, Spincast will automatically configure Jackson so it uses your mix-ins, and you would have the exact same result than annotating the User class directly:

User user = new User();
user.setName("Stromgol");
user.setTitle("alien");

String xml = getXmlManager().toXml(user);
assertNotNull(xml);
assertEquals("<User><name>Stromgol</name></User>", xml);

Spincast Jackson XML plugin