My favorites | Sign in
Project Home Wiki Issues Source

quick, start
Updated Dec 3, 2009 by

Quick Start

Basic mappings

Xmappr is a small and fast library that maps arbitrary XML to your classes. It was designed to handle complex XML coming from external sources, where you do not have control over how it’s generated nor when it’s structure (schema) changes. Xmappr’s biggest strength is that it let’s you map just a part of XML document that is of interest to you.

Let’s give it a spin with this first example. You want to map this XML:

<root a="2.2">
    some text

to this class:

public static class Root {

    public float a;

    public Integer node;

    public String text;

All you have to do is add @RootElement, @Element, @Attribute or @Text annotations to your classes and configuration is done.

Mapping is than done in just three lines of code:

Xmappr xm = new Xmappr(Root.class);
Root root = (Root) xm.fromXML(reader);

Mapping via XML configuration

If you don't want to use annotations you can achieve the same effect with an external XML configuration file. For the above example the XML config would be:

<root-element name="root" class="">
  <attribute field="a"/>
  <element field="node"/>
  <text field="text"/>

In case of XML configuration, invoking Xmappr is just a bit different - pass a Reader to Xmappr where XML configuration can be read:

Reader xmlConfigReader = new FileReader("/path/to/XmlConfigFile");
Xmappr xm = new Xmappr(xmlConfigReader);
Root root = (Root) xm.fromXML(reader);

Mappings with a name

If XML element names differ from your field names, then just add element name to the Xmappr annotations:

public static class NewRoot {

    public float attribute;

    public Integer someOtherNodeName;

    public String theTextOfTheNode;

or with XML configuration:

<root-element name="root" class="">
  <attribute field="attribute" name="a"/>
  <element field="someOtherNodeName" name="node"/>
  <text field="theTextOfTheNode"/>

Text elements don’t have names, of course.

Comment by, Jan 4, 2010

It's really cool!!

Comment by, Jan 21, 2010

As already mailed: AWESOME WORK! keep it up :)

Comment by, Feb 24, 2010

It's really working!good job

Comment by, Apr 19, 2010

Hi guys, I try to map the following XML <?xml version="1.0" encoding="UTF-8"?> <validations xmlns=""

xmlns:xsi="" xsi:schemaLocation=" vld.xsd">
<validation forElements=".req"/> <validation forElements=".mail"/> <validation forElements="#cmbTitle"/>

to the class:

package ro.isdc.validator.parser;

import java.util.List;

import org.xmappr.Element; import org.xmappr.RootElement?; import org.xmappr.converters.CollectionConverter?;

@RootElement? public class Validations {

@Element(converter=CollectionConverter?.class) List<Validation> validations;

public List<Validation> getValidations() {
return validations;
public void setValidations(List<Validation> validations) {
this.validations = validations;


but the List<Validation> validations results null. What did I wrong? Thx a lot

Comment by project member, Apr 19, 2010

Several things: 1. Field "validations" is package private so Xmappr does not have access to it. Ether it must be public or you have to put @Element to its setter/getter.

2. You are trying to map <validation> elements to field named "validations". Since the name is not the same (note the "s" at the end) you must use named mapping: @Element("validation")

3. Root element <validations> belongs to the "" namespace. You probably need to define (you didn't post this piece of code) default namespace. It's aasiest to add a namespace configuration-wide: xmappr.addNamespace("")

4. You don't need to define CollectionConverter?? for collections as this is the default. Just use @Element without converter=...

One can do a lot of troubleshooting by printing out the mappings: xmappr.getXmlConfiguration(MappedClassName??.class)

If this still does not work contact me via mailing list.

Comment by, Feb 25, 2014

every java XML demarshaler wants you to define landing-pad variables to receive values...I just want an object for the whole file! I'm trying to sue this for validation purposes. I don't need variables to receive values.

Well, on to the next demarshaler I guess

Sign in to add a comment
Powered by Google Project Hosting