Simple Usage

If you do not need to generate XML in a specific format or using specific attribute and element names, you actually don't need any configuration file at all to use XmlIO. Elements and attributes in the XML simply need to match the name and case of the Java class names and properties they correspond to.

XmlReader reads in XML and expects to either create objects or set properties each time it processes a tag or attribute. For that reason, the reader expects to return a single object which represents the root tag of the XML file.

XmlWriter, for the same reason, will take one root object and persist the object graphic of that one object to create the XML file.

Simple Example

Figure 1: Attributes in the configuration objects Say you wanted to configure an HTTP server you were creating. You've decided your object model for configuring the HTTP server is something simple like the conceptual diagram to the left, showing the attributes of the configuration objects. Since you want to have many Server objects in your application (and thus in your configuration file), you'd also create a Config object which is really just a collection of Server objects. The Config object would map to the root tag in your XML.

Setters

XmlIO uses JavaBean style getters and setters to do it's work. The XmlReader will use the setters to set properties as it reads in elements and attributes from the XML file. Setters names must match XML tag and attribute names exactly (unless you configure the framework to do otherwise). If you have a tag or attribute ipAddress, then setIpAddress will be called.

Getters

Getters must match the names of the setters in order for the same XML elements and attributes to be both read and written. If you have a setter with the signature setIpAddress(String ipAddress): void the getter for that property would be getIpAddress(): String.

Collections

One special note is about collections. You would normally name your getters and setters using a plural form when creating your configuration objects. The Config object you'd want to give methods like getServers() and setServers().

The setter for collections, however, must take a single object as it's parameter, and that object is the object which makes up the collection. If the collection contains strings, the setter must take a String parameter. As well, the setter for a collection of non-primative objects must match the name of the object you are putting in the collection. So you would use the setter signature setServer(Server server): void for the Collection of Server objects in the Config object. As a convenience, you can use the method signature addServer(Server server): void instead of setServer(Collection servers): void if you want.

The getters for collections, on the other hand, return a collection of objects. They can be primatives or any other kind of objects - XmlWriter will traverse the object graph, generating XML by using reflection to find all getters in an object.

Figure 2: Getters and setters in the configuration objects

Sample Code

You can download the source code for this example here.

Run the example by going to the bin folder and typing:
java -cp .;\path\to\XmlIO\jar\XmlIO.jar org.bifrost.xmlio.example.server.Main

Sample XML

Here is an example of what the XML might look like.

<Config>
  <Server>
    <ipAddress>127.0.0.1</ipAddress>
    <VirtualHost>
      <domainName>www.testdomain.com</domainName>
      <documentRoot>/home/httpd/htdocs/testdomain</documentRoot>
      <alias>testdomain.com</alias>
      <alias>clients.testdomain.com</alias>
    </VirtualHost>
    <port>80</port>
  </Server>
  <Server>
    <ipAddress>127.0.0.1</ipAddress>
    <VirtualHost>
      <domainName>admin.testdomain.com</domainName>
      <documentRoot>/home/httpd/htdocs/testdomainadmin</documentRoot>
    </VirtualHost>
    <port>8080</port>
  </Server>
</Config>