SweetXML User Guide

Table of Contents

Using SweetXML

Basic Usage Patterns

How you use SweetXML essentially boils down to one question: Where does the conversion to plain XML happen? There are several possible answers to that question, depending on the situation.

Conversion at Build Time

If your application needs XML configuration files at runtime and does not have built-in support for SweetXML, you can convert the files at build time. This is the most common way to use SweetXML: include a conversion step in your build process, during the resource copying phase.

SweetXML provides built-in support for doing this with Ant and Maven. Most other tools will be able to use the command line interface.

Applies to: configuration files for Macker, Hibernate, Tapestry, web application context, JSF, etc.

Conversion at Launch Time

Sometimes, you cannot convert a file at build time. This is usually for one of two reasons: either the file is not part of any build process, or the file controls the build process, and thus must be converted before the build can begin.

In either case, your best bet is to whip together a little shell script which first calls SweetXML's command-line interface to convert the necessary files, then launches the tool in question. Place that script so that your shell finds it instead of the tool's own launch script, and you'll hardly notice that it doesn't have native SweetXML support.

The SweetXML distribution includes such scripts for converting Ant and Maven build files, in the bin directory.

Applies to: Ant's build.xml, Maven's pom.xml, Jetty's jetty.xml, etc.

Conversion at Runtime

The easiest way to use SweetXML by far is to use a tool which has built-in support for it: just use the file extension .sxml instead of .xml, and you're off and running!

Since SweetXML is currently in early development, no such tools exist ... yet. However, Macker will be adding experimental support for it in the not-too-distant future. As the syntax stabilizes, you can start lobbying your favorite tool for native support as well!

Manual Conversion

For files which rarely change, it may be more trouble than it's worth to automate the conversion. You can always manually run the command-line interface to do a one-off conversion of a config file.

This is also a great low-risk way to get started with SweetXML: manually convert one XML config file to SweetXML, edit it a bit, and manually convert it back to test your changes. If you like the sweeter syntax, then you can think about automating the conversion — and if you don't like it, well, at least you haven't invested much time in it.

Table of Contents
innig