Zeus Samples Documentation

The samples included with the Zeus source distribution will give you a feel for what Zeus is capable of, and how it works. Currently, the samples demonstrate:

Instructions for running the samples are below. It will be assumed that you're running the samples from the samples directory, and that you are using the latest CVS snapshot (not Beta 1; too much has changed!!). Make any necessary adjustments to the following instructions if you work from a different directory. Also, *nix bash syntax will be used - adjust depending on your platform.

Build Zeus

The very first thing we need to do is to build Zeus. We can use build.sh to do this (or build.bat if you're on Windows). cd to the top level directory that contains build.xml, and type: 

   ./build.sh

The generated classes will be placed in build/classes. We can now cd to the samples directory, where we'll be running the samples from.

Set your classpath

Your classpath must include dtdparser113.jar, jdom.jar, xerces.jar, the generated build/classes directory, and the directory where you will place the classes generated from compiling the files generated by TestDTDBinder. Since we're working from the samples directory, we will place the files generated by TestDTDBinder in samples/output. So we can set the classpath using relative paths like this:

   export CLASSPATH=../lib/dtdparser113.jar:../lib/jdom.jar:../lib/xerces.jar: \
      ../build/classes:./output

You would of course enter the above command on one line. And again, you should adjust depending on where you want to run the samples from, or you can use absolute paths.

Compile TestDTDBinder and TestUnmarshaller

With your classpath set, you can now compile TestDTDBinder.java and TestUnmarshaller.java. You can't compile TestUnmarshallSongs.java yet because it depends on the files that TestDTDBinder will generate. Type:

   javac TestDTDBinder.java -d ../build/classes
   javac TestUnmarshaller.java -d ../build/classes

We use the -d option to place the resulting classes files in build/classes.

Run TestDTDBinder Against song.dtd

Now we can generate the Java source files from song.dtd with TestDTDBinder. First create a directory called output, where TestDTDBinder will generate the Java source files into (otherwise, an exception will be thrown).

   java samples.TestDTDBinder ./dtd/song.dtd [package]

If you look in the output directory we created, there should be Java source files like SONG.java, ARTIST.java, etc.

The optional package argument specifies the package you want the generated classes to be a member of. If no package is specified, the classes are generated into the default package. So for example, if you wanted the classes from song.dtd to be part of the music package, you would type:

   java samples.TestDTDBinder ./dtd/song.dtd music

If you look in the output directory, the proper directory structure will be created (i.e. output/music), and the Java source files will all have the package declaration you specified. Note that the package you specify will be globally applied to all generated classes.

In either case, information on what TestDTDBinder is doing will also get written to standard out so you can see what's happening.

Compile the Generated Files

Next, we want to compile the generated Java source files from the output directory. We will simply generate the class files into the same directory as the source files (and we pointed the classpath to this directory earlier).

   javac output/*.java

You would of course adjust the above command if you generated into a particular package. With these generated source files compiled, we can also compile TestUnmarshallSongs.java, which we couldn't do at first.

   javac TestUnmarshallSongs.java -d ../build/classes

The only issue is that TestUnmarshallSongs has Java import statements that assume that the classes generated by TestDTDBinder are not part of any package. You would either have to use TestDTDBinder without specifying a package, or you would have to modify TestUnmarshallSongs to import the various classes from the package you specified.

Run the Samples

Now we can go ahead and run the samples. We have two classes to play with; TestUnmarshaller and TestUnmarshallSongs. We also have a sample XML file, song.xml that is constrained by song.dtd. TestUnmarshallSongs is tied to song.dtd, and it can only be used on XML files that are valid against song.dtd. TestUnmarshaller however, can be used with XML files constrained by other DTDs, but you must follow the same process as we did for song.dtd (i.e. run the DTD through TestDTDBinder, compile the generated Java source files, place the resulting class files on the classpath, and then run TestUnmarshaller against your XML file).

To run TestUnmarshaller against song.xml, type:

   java samples.TestUnmarshaller song.xml [package]

Like TestDTDBinder, TestUnmarshaller also takes an optional package argument that specifies the package that the classes you are unmarshalling belong to. So if you passed music as the package argument to TestDTDBinder, you would pass music as an argument to TestUnmarshaller. If no package argument is passed, Unmarshaller assumes that the classes are in the default package.

TestUnmarshaller unmarshalls song.xml into a Java object, and then uses reflection to print out the available methods on that object to standard out.

To run TestUnmarshallSongs against song.xml, type:

   java samples.TestUnmarshallSongs song.xml

The same issue that came up when you compiled TestUnmarshallSongs applies here. You either have to use TestDTDBinder without specifying a package, or you have to modify TestUnmarshallSongs to import the various classes from the package you specified.

TestUnmarshallSongs unmarshalls song.xml into a Java object, calls the methods on that object to print out the values of various properties (which should be the same values in song.xml), and then marshalls that object back into an XML file called output.xml, which should be equivalent to song.xml.

If you want to cleanup after you're done, delete the output directory, and delete output.xml.