xml2class - Example

Let's do a simple linked list (usable for Stacks, Lists, and so on). We'll need a Document Type Definition, a Java object (ListItem), a XML file (this one may also be produced by saving the list) and some code for your own classes.

[top] Document Type Definition

Here we define, how the XML file is going to be structured. Actually this file isn't necessary for the proper working of xml2class, but if it exists, it will facilitate your work: you'll easier see, what must be put where, and it will allow XML validation and the implementation in other software basing on XML.

    <!-- File: linklist.dtd - DTD for a simple linked list -->

    <!ELEMENT ListItem (value, nextItem?)>

a ListItem class with two methods: setValue() and setNextItem().
every ListItem must contain one value and one or null nextItems.

    <!ELEMENT value (#PCDATA)>

setValue() accepts one String as argument.

    <!ELEMENT nextItem (ListItem)>

setNextItem() accepts one ListItem as argument.

[top] Java class code

In order to keep this example simple, I've omitted the constructor and the get methods. For practical use, at least the get methods would be necessary. If you add also a constructor, be aware that the parser is currently looking for an empty constructor in order to create the ListItems (no parameters / attributes have been specified).

/* File: ListItem.java */

import xml2class.X2cTools;

public class ListItem
{
    /** This item's value. */
    private String _value = new String();
    /** Reference to the next item in the list. */
    private ListItem _nextItem = null;

The following two methods correspond to the value and the nextItem elements in the XML / DTD files. Elements beginning with a lowercase letter will be translated to set methods for their content.

    /** Set this item's value. */
    public void setValue(String value)
    {
        _value = value;
    }
    
    /** Set the next item in the list. */
    public void setNextItem(ListItem nextItem)
    {
        _nextItem = nextItem;
    }

In order to save the list back to disk, provide a toXMLString() method, which returns the XML representation of the object. I.e. any value set by the parser should be added. Like this you can save the list easily back to disk by using XMLFile.save([RootElement], "[directory/filename.xml]").

    /**
     * @return The XML representation of this object.
     */
    public String toXMLString()
    {
        StringBuffer xmlString = new StringBuffer("<ListItem>\n\t<value>");
        xmlString.append(X2cTools.toEntityString(_value)).append("</value>\n");
        if (_nextItem != null)
            xmlString.append("<nextItem>\n").append(_nextItem.toXMLString()).append("</nextItem>\n");
        xmlString.append("</ListItem>\n");
        return xmlString.toString();
    }
}

[top] XML file example

If you save your list, it might look somehow like this:

    <?xml version="1.0"?>
    <!DOCTYPE ListItem SYSTEM "linklist.dtd">

These two lines are not necessary for xml2class, but if you want to validate your XML files, they are required (here you've got the reference to the DTD).

    <ListItem>

Here begins the first item,

        <value>[the first item's value]</value>
        <nextItem>
            <ListItem>

here begins the second item,

                <value>[the second item's value]</value>
                <nextItem>

and here go all the other items... (the last <nextItem> tag will be omitted, when there are no more items to follow)

                </nextItem>
            </ListItem>
        </nextItem>
    </ListItem>

[top] Your code

All that lacks now, is the list controller (through which you can add objects to the list and get them back) and the methods for reading and writing...

You've got two options here: or you use the given, but rather unflexible ones:

    ListItem top = (ListItem)XMLFile.parse("[directory/filename.xml]", "[package.name]");

and

    XMLFile.save(top, "[directory/filename.xml]");

or if you want to use the DTD

    XMLFile.save(top, "[directory/filename.xml]", "ListItem SYSTEM \"linklist.dtd\"");

Remember: [directory] is relative to your home directory (you may consider it to be a class path). And the package name(s) indicates where the needed class files are located.

...or you adapt them by writing them yourself in your own code. Here you may use any Reader as input source, you may indicate a PrintWriter as verbose destination, and you may also parse other levels than just the first (at the condition that you use different objects at the different levels). Have a look at XMLFile and at the xml2class API for the precise instructions. You'll surely figure out how it's supposed to work... anything should be quite obvious or rather self-explanatory...

That's it, now you should have a simple linked list, able to save itself into an XML file and to restore itself at another time.

In case it didn't work (it really should), you may get help from...

Simon Bünzli, zeniko@gmx.ch

Back to the introduction