Juffrou XML – Three Minute Tutorial

Three Minute Tutorial

Getting started

Getting to work with juffrou-xml is very easy. This is how you get the XML representation of an object:

First create a couple of java beans and fill up some of their properties

	Address address = new Address();
	address.setStreet("Bean street, No 1");
	address.setCity("Lisboa");

	Person person = new Person();
	person.setFirstName("Carlos");
	person.setLastName("Martins");
	person.setBirthDay(new SimpleDateFormat("yyyy-MM-dd").parse("1967-10-01"));
	person.setHome(address);

Then instantiate Juffrou-xml and marshal the java bean

	JuffrouXml juffrouXml = new JuffrouXml();
	String xmlString = juffrouXml.toXml(person);

The output will be the following XML:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<net.sf.juffrou.xml.test.dom.Person>
  <firstName>Carlos</firstName>
  <lastName>Martins</lastName>
  <birthDay>10/1/67 12:00 AM</birthDay>
  <home>
    <street>Bean street, No 1</street>
    <city>Lisboa</city>
  </home>
</net.sf.juffrou.xml.test.dom.Person>

To unmarshal an object back from XML is also straight forward:

	Person person = (Person) juffrouXml.fromXml(xmlString);

Adjusting the output

Registering the person bean will allow you to also define its xml element name

	JuffrouXml juffrouXml = new JuffrouXml();
	juffrouXml.registerRootElement(Person.class, "Person");
	
	String xmlString = juffrouXml.toXml(person);

The output will now be:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Person>
  <firstName>Carlos</firstName>
  <lastName>Martins</lastName>
  <birthDay>10/1/67 12:00 AM</birthDay>
  <home>
    <street>Bean street, No 1</street>
    <city>Lisboa</city>
  </home>
</Person>

To have the birth day date displayed in simple date format, create a custom serializer:

public class SimpleDateSerializer implements Serializer {

	private final SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd");
	
	@Override
	public void serialize(JuffrouWriter writer, BeanWrapper valueOwner, String valuePropertyName) {
		writer.write(formatter.format((Date)valueOwner.getValue(valuePropertyName)));
	}

	@Override
	public void deserialize(JuffrouReader reader, BeanWrapper valueOwner, String valuePropertyName) {
		String value = reader.getText();
		try {
			valueOwner.setValue(valuePropertyName, formatter.parse(value));
		} catch (ParseException e) {
		}
	}
}

and just register the corresponding bean property:

	JuffrouXml juffrouXml = new JuffrouXml();
	juffrouXml.registerRootElement(Person.class, "Person");
	juffrouXml.registerSerializer("simpledate", new SimpleDateSerializer());
	juffrouXml.registerElement(Person.class, "birthDay", "birthDay", "simpledate");
	
	String xmlString = juffrouXml.toXml(person);

The output will now be:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Person>
  <firstName>Carlos</firstName>
  <lastName>Martins</lastName>
  <birthDay>1967-10-01</birthDay>
  <home>
    <street>Bean street, No 1</street>
    <city>Lisboa</city>
  </home>
</Person>

Simplified marshalling

Simplified marshalling is the possibility of marshalling nested beans into a "flat" XML structure like this: imagine that you don't want the whole home address marshalled for this person. You only want his home city and you want it displayed as it were a simple property of person.

Easy! All you have to do is this:

	JuffrouXml juffrouXml = new JuffrouXml();
	juffrouXml.registerRootElement(Person.class, "Person");
	juffrouXml.registerElement(Person.class, "home.city", "homeTown", null);
	String xmlString = juffrouXml.toXml(person);

The output will now be:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Person>
  <firstName>Carlos</firstName>
  <lastName>Martins</lastName>
  <birthDay>1967-10-01</birthDay>
  <homeTown>Lisboa</homeTown>
</Person>

Of course this XML will also be unmarshalled back to a person object. That person object will have a home with city Lisboa.

Using a mapping file to configure Juffrou-XML

Juffrou-XML can also be configured using mapping files.

To demonstrate lets do the equivalent configuration of the prior examples. Create a file calledjuffrou-xml-mapping.xml with the following contents:

<?xml version="1.0" encoding="UTF-8"?>
<mapping>

	<serializer id="simpledate" class="net.sf.juffrou.xml.test.dom.SimpleDateSerializer" />
	
	<root-element xml="Person" type="net.sf.juffrou.xml.test.dom.Person">
		<element property="firstName" />
		<element property="lastName" />
		<element property="birthDay">
			<serializer ref="simpledate" />
		</element>
		<element property="home.city" xml="homeTown" />
	</root-element>
	
	<root-element xml="Person" type="net.sf.juffrou.xml.test.dom.Address" />
	
</mapping>

By not specifying any of the Address' properties to marshal, all will be marshalled

To instantiate Juffrou-xml now we use another constructor:

	JuffrouXml juffrouXml = new JuffrouXml("classpath:juffrou-xml-mapping.xml");
	String xmlString = juffrouXml.toXml(person);