xml2class - Introduction

In this document, you'll find a brief package description, some quick start information and the basic rules for xml2class usage.

[top] Description

xml2class provides you with a simple XML parser, which instantiates data structures written in Java out of a XML description (and supports storing them back as XML code). It is thought as an aid for programmers, as it won't do all the work for you.

With the aid of xml2class you may describe most data structures (such as linked lists, binary trees, tables, menus, and so on) in easy to modify XML. Following the XML descriptions, it won't be difficult to write the corresponding Java classes. Then the XML2ClassParser will read in and instantiate the entire structure in a way that you may save it back to disk easily (in XML).

[top] Quick start

Implement the data structure in XML. Think of one XML element as one Java class. E.g. for...

    <RootElementName att1="Constructor Parameter 1" att2="Constr. Param. 2">
        <method>
        	any parameters (any Objects)
        </method>
        <AnotherElement att3="Constr. param."/>
        <methodName/>
        ...
    </RootElementName>

...write the following Java class:

    public class ElementName {
        public ElementName(String anyValue1, String anyValue2) { ... }
        public void setMethod([ParameterObjectsClassType] value) { ... }
        public void addAnotherElement(AnotherElement element) { ... }
        public void methodName()
        ...
    }

Note how the tags correspond to classes, methods and parameters. Implement now the data structure like this. Have a look at the explicit rules for more precise information to be considered.

Now you can load it into your program with the following line:

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

And save it back by using

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

supposing your objects provide a toXMLString() method.

For more concrete information, have a look at the example.

[top] Basic rules

Tags & methods

Class names always start with an uppercase character.
Method names always start with a lowercase character (--> set[MethodName]( ) or [methodName]( ), depending on whether you closed the tag directly: <methodName/>).
If no method name is indicated, it will be produced through the class name: add[ClassName]( ).
Any set[...]( ) and add[...]( ) method may have only one parameter, so that there will be several method calls for several objects / elements.
This parameter must be of the (super)type of the objects to be set.
The parameter may also be an Interface which the object implements.
Alternatively the set[...]( ) and add[...]( ) methods may be overloaded. xml2class will then automatically select the right method.
[methodName]( ) calls won't have any parameters.
If you don't like a "set" put in front of the method name, name the tag <_[methodName]>. This will result in a [methodName]( ) call, but with the same parameters as the corresponding set[...]( ) method.

Objects & classes

For the constructur, various string variables may be set.
These have to be put however already in the right order (as XML2ClassParser ignores the attribute's names).
Java language objects may also be used - e.g. <Double value='x'/> ("java.lang" doesn't have to be added to the classpath).
In general, if a file isn't in one of the indicated packages (you told the parser, when you created it or when you called XMLFile.parse( )), the entire package name should be written (or the relative one from where one of the classpaths has been set to).
The classpath list provided to XMLFile should use whitespace (e.g. spaces) as separators

XML & entities

Well-formed and valid XML will be of advantage, but is not necessarily required.
In attribute values and string data, use entities instead of the following characters:

Character	&	<	>	"	'
Entity	&	<	>	"	'

Furthermore you may produce entities for any (unicode) character by its value: &#[value]; or &#x[hexvalue];.
You may produce these entities also by XMLFile.toEntityString(String s) (necessary for saving data back to a XML file).

xml2class parsing

For basic parsing, use one of the XMLFile.parse([...]) methods.
If you want better control over the parsing process (differentiated verbose mode, second level parsing, and so on), you'll have to copy the code from XMLFile.parse([...]) into your own code and adapt it there.
When you start parsing, you may want to indicate, which element should be the root element (in order to parse only a part of the structure). Do so by calling parse(reader, rootElementName).
If you want some verbose feedback while parsing, add a PrintWriter to the parser by setVerbose(printWriter).
For more explicit information, have a look at the example.

[top] The author

For any comments, bug reports ("it's not a bug, it's a feature!") and so on - I am aware of the insufficient quality of this documentation - just contact me:

Simon Bünzli, zeniko@gmx.ch