Quick Start

To quickly start using XiMpLe with default behaviour, you simply need to instantiate an instance of the Ximple class, and call the writeXml(Object, Writer) method with the Object you wish to serialize. 

   Writer out = new StringWriter();
   Foo foo = new Foo();
   // do stuff with foo
   
   Ximple ximple = new Ximple();
   ximple.writeXml(foo, out);

To deserialize an XML document, you call the readXml(Reader) method. 

   // deserialize output from above
   Reader in = new StringReader(out.toString());
   
   Ximple ximple = new Ximple();
   Foo foo = (Foo)ximple.readXml(in);

Default Behaviour

The default behaviour of XiMpLe is to serialize all public getter methods (excluding the getClass() method of the base java.lang.Object class).

As an example, given the following class to serialize: 

public class Person {
   private String firstname;
   private String lastname;
   private int status;
   
   public String getFirstname() { ... }
   public void setFirstname(String fn) { ... }

   public String getLastname() { ... }
   public void setLastname(String ln) { ... }
}
The XML output will be: 
<Person>
 <firstname>William</firstname>
 <lastname>Rockpierre</lastname>
</Person>

Note that the private status member variable is not serialized because there is no corresponding getter method for that variable.

The example above assumes that the Person class is in the default package (package with no name). If the Person class was declared in a package, then the root element name of the XML output would be the fully- qualified class name of the Object being serialized.

So if the Person class is declared to be in the package com.foobar 

package com.foobar;

public class Person {
   ...
}
then the resulting XML would be: 
<com.foobar.Person>
 <firstname>William</firstname>
 <lastname>Rockpierre</lastname>
</com.foobar.Person>

To change this behaviour, see the Usage section below to configure this option.

For deserialization, the default behaviour is to call the corresponding setter method of the current XML element being parsed. If no corresponding setter method is found, the element is skipped.

For example, if the current element being parsed is: 

 <firstname>William</firstname>

XiMpLe will call the setFirstname(String) passing "William" as the parameter.

Usage

Be default, XiMpLe uses the Object's fully-qualified class name as the root tag name of the XML. If you prefer to use an alternate tagname for the root tag, then you must map the tag name to the Class of the Object to be serialized. To do this, make a call to the addMapping(String, Class) method. This will associate a tag name to a Class during serialization/deserialization. 

   ximple.addMapping("contact", Person.class);
So the XML output will become: 
<contact>
 <firstname>William</firstname>
 <lastname>Rockpierre</lastname>
</contact>

Conversely, during deserialization, when the <contact> root element is parsed, it will instantiate an instance of the Person class.

You can also customize the behaviour of XiMpLe to include and/or exclude methods during serialization/deserialization. This provides you with greater control as to which methods are called, in addition to the getter/setter methods, that you wish to serialize/deserialize.

The Ximple class has two methods to explicitly include or exclude methods from serialization/deserialization: addMethodToInclude(Class, String) and addMethodToExclude(Class, String), respectively. For both methods, the first parameter specifies the Class where the method is declared and the second parameter specifies the method name to include/exclude. The method name is the full name as declared in the class. If a property you wish to exclude during serialization/deserialization has a getter and a setter method, then you must make two calls to addMethodToExclude(Class, String), one for each method.

Using the Person class defined above, if you did not want to serialize the lastname, then you would initialize the Ximple object as follows: 

   Ximple ximple = new Ximple();
   ximple.addMethodExclude(Person.class, "getLastname");
   
   Person person = new Person();
   person.setFirstname("William");
   person.setLastname("Rockpierre");
   
   ximple.writeXml(person, new FileWriter("person.xml"));
The expected person.xml file would contain: 
<Person>
 <firstname>William</firstname>
</Person>