XeriL
XML Serialization Library
Documentation

Introduction

The main idea that motivated this work was to be able to represent a java object in an XML formatted file. Basically, Java serialization allows you to turn any object into a ".ser" file, which can then be stored, or sent through the network... The problem with this approach is that the serialized object is not human readable and thus cannot be edited by hand or even read. We would like to produce something that is human readable and editable. This can then be used for configuration files for example.

The format of the file

We want the format of the file to be as straightforward as possible. Thus there is going to be a specific DTD for each kind of object (each class). Let's take an example:

public class MyTest
{
  private int myIntField;
  private double myDoubleField;
  private java.util.Date myDateField;
}

will be represented by

<MyTest>
  <myIntField>13</myIntField>
  <myDoubleField>34.98</myDoubleField>
  <myDateField>07/20/2000</myDateField>
</MyTest>

with the following DTD:

<!ELEMENT null EMPTY >
<!ELEMENT myDateField (#PCDATA)>
<!ELEMENT myDoubleField (#PCDATA)>
<!ELEMENT MyTest (myIntField, myDoubleField, myDateField)>
<!ELEMENT myIntField (#PCDATA)>

NB: I will explain how to actually represent a "Date" object by a simple string (this is called customization).

How to use it

The package contains 2 main classes:

ObjectToXml that turns an object into an XML output using the static method ObjectToXml.objectToXml(Object o, PrintWriter out)
XmlToObject that turns an XML input into an object using the static method XmlToObject.xmlToObject(InputStream in, Class cl)

There is a third class that can be used as a tool to generate the correct DTD: ClassToDtd. You invoke it like this: '

java org.xeril.xml.ClassToDtd
    xxxxx

' where xxxx is the name of the class (including the package information). Please note that you can 'tweak' the DTD by hand afterwards (for example, adding '?' if a parameter is optional).

Customization

You can customize the way the XML file will look like: you need to create a new simple class for this customization (it is inspired by the Bean/BeanInfo pattern). You have to create a class that complies to the 2 following requirements:

the class must implement the XmlInfo interface.
the name of the class is derived from the name of the class you want to customize by appending XmlInfo (ex: if you want to customize test.MyTest then you have to name the class test.MyTestXmlInfo). An extension to this, in order not to pollute the global namespace with this kind of class, is to define an XmlInfo class which is nested within the original class (thus the name of that new class would be test.MyTest$XmlInfo)

The best solution is probably to inherit from the SimpleXmlInfo class which implements the XmlInfo interface and provides some convenient methods.

`XmlInfo`

The XmlInfo interface holds two methods.

getXmlName(): returns the xml tag name of this class (if you don't provide it then the class name will be taken instead).
getXmlMapDescriptors(): returns an array of XmlMapDescriptor objects. Each one of this object allows you to specify what you want to do with a field (you don't have to provide one for each field... because if not defined then default value will be taken, for example the name of the tag will be the name of the field).

`XmlMapDescriptor`

A XmlMapDescriptor allows you to customize one field:

you can hide a field (won't be shown into the XML output)
you can give it a different name (if for example you are used to name your private attribute _xxx, it doesn't look nice to have an XML tag called <_xxxx>).
you can also modify the way it is displayed when you associate a XmlMapper to it.

`XmlMapper`

XmlMapper is another interface that maps an object to a string representation and vice-versa. This is extremely powerfull and can be extended at will. This package provides 2 'standard' mapper classes and it is easy to write your own:

XmlMapperDate for converting a java.util.Date object into a nice String representation.
XmlMapperClass for converting a java.lang.Class object into just the class name.

Example

Here is an example that tries to cover all the aspects of the package:

The class Ex1 defines 2 simple types, an array of double, another object and a Date. It contains the nested XmlInfo class that customizes its xml behavior.
The class Ex2 defines a hidden field, a simple type and an array of Class objects. It contains the nested XmlInfo class that customizes its xml behavior.
The Test program simply reads an xml file that represents an Ex1 object and redisplays it as its output after calling the change method on it.
Here is an example of xml file: ex.xml

Constraints, restrictions and future developments

The code uses introspections to find out fields and types. It calls the method java.lang.reflect.Field.setAccessible(true) which will throw a security exception if you don't have the right property file.
It is right now not possible to have objects that point to each other recursively (maybe done in a future release). For doing this we need to be able to give a name or reference to each individual object.
Only simple arrays are supported (arrays of arrays are not).

Dependencies and requirements

This library is supposed to work with JDK1.2 and it is known not to work under JDK1.1 since it uses the java.lang.reflect.Field.setAccessible(true) method call, introduced with JDK1.2.
The library uses the packages javax.xml.parsers, org.w3c.dom and org.xml.sax. They can be found in JAXP (the Java API for XML Parsing) provided by SUN. Those packages are actually part of JDK1.4, so it is no longer necessary to download them separately.

License and Copyright

Download

You can download a tarball (.tar.gz) which contains the library (a jar file) and the source. Click here to download (22Kb).

Source

The source of this project can be extracted from CVS on sourceforge.net at cvs.xeril.sourceforge.net:/cvsroot/xeril and the directory name is XeriL

Yan Pujante

Last modified: Sat Nov 10 19:07:07 PST 2001

XeriLXML Serialization LibraryDocumentation