Home

Home: Jackson XML databind Wiki

This is the home page for "jackson-xml-databind" project. The main deliverable of the project is a jar that contains extension to Jackson JSON library, to extend it so that it can bind XML to POJOs (and vice versa), instead of using JSON.

Basic usage

Intended usage is by instantiating 'com.fasterxml.jackson.xml.XmlMapper', and using it just like standard Jackson 'ObjectMapper' -- the difference being that instead of JSON, external data format is XML. That is:

import com.fasterxml.jackson.xml.XmlMapper;

// with Jackson 2.10 and later
ObjectMapper mapper = XmlMapper.builder()
    // possible configuration changes
    .build();

// or, with Jackson versions before 2.10 (also exists for later versions)
ObjectMapper mapper = new XmlMapper();

For most usage that is all there is!

One alternative is that if you need to change some configuration, you may need to first configure module, then construct mapper:

JacksonXmlModule module = new JacksonXmlModule();
// to default to using "unwrapped" Lists:
module.setDefaultUseWrapper(false);
XmlMapper xmlMapper = XmlMapper.builder(module)
    .build();

Note that underlying JsonParser and JsonGenerator instances are specific subtypes as well (FromXmlParser, ToXmlGenerator), but usually you don't have to worry about this.

Usage: pretty-printing

Although basic pretty-printing using like this works fine with XML:

String doc = mapper.writerWithDefaultPrettyPrinter().writeValue(value);

you may want to use specifically configured pretty-printer. XML module requires specific PrettyPrinter subtype (XmlPrettyPrinter); used of standard JSON-based DefaultPrettyPrinter does not work. So when writing XML, you need to pretty print the XML using the DefaultXmlPrettyPrinter.

DefaultXmlPrettyPrinter xmlPrettyPrinter = new DefaultXmlPrettyPrinter();
// you can then configure the settings on the xmlPrettyPrinter instance
xmlMapper.setDefaultPrettyPrinter(xmlPrettyPrinter);

Licensing

Project is licensed under Apache License 2.0 (http://www.apache.org/licenses/LICENSE-2.0.txt) like all official Jackson components.

FasterXML also explicitly allows users to alternatively license component under Lesser GPL (LGPL) 2.1 up to and including version 2.2. If so, they may want to repackage artifacts to reflect their choice of license to use.

Documentation

Javadocs

See javadoc.io docs and select the appropriate API version in top banner.

Snapshots

Snapshot builds can be found from Sonatype Maven Snapshot repository:

<snapshotRepository>
   <id>sonatype-nexus-snapshots</id>
   <name>Sonatype Nexus Snapshots</name>
   <url>https://oss.sonatype.org/content/repositories/snapshots</url>
</snapshotRepository>