VM Tools User Documentation - v0.5

Overview

VM Tools is the beginning of a collection of XML-oriented tools for the java platform. The toolkit is developed by VM Systems, Inc. and is available under an open source license.

The initial release of the toolkit contains tools for automatically generating differences between two XML documents and may be of particular interest to members of the OpenTravel Alliance (OTA) who have developed XML standards using a document difference representation.

Features

The initial release has the following features:

Limitations

This implementation will work for data-oriented XML but not for document-oriented XML. Specific limitations are as follows:

System Requirements

VMTools has the following prerequisites:

Installation

Details go here.

Building from Source

Make sure that you have installed all necessary pre-requisites and your $CLASSPATH contains the required .jar files. The ant tool displays a list of available targets when invoked with the -projecthelp option. The following targets are available in the enclosed ant build.xml script:
ant -projecthelp
Searching for build.xml ...
Buildfile: ~/VMTools/build.xml
Main targets:

 all         default target; runs targets build and build-test
 build       compiles the normal code into ./build/classes
 build-test  compiles the test code into ./build/classes
 clean       deletes all compiled code
 docs        creates javadocs in ${docs}

Subtargets:

 init

BUILD SUCCESSFUL

Total time: 1 second
To build a given target just use the form ant targetname e.g. to build all classes and all tests issue the command: ant to build the default target all.

Why Updates are so Difficult

Update processing in a message-driven environment is not easy, and in a standards-based environment it's even more difficult. One camp wants to keep things simple and just send/receive the entire updated document. Another camp (the minimalist camp) wants to send a minimal difference representation so that the receiving end can apply the changes incrementally. A third camp wants to have access to both before and after images on the server-side so that they can calculate the differences in their own application-specific way.

The generic OTA_Update representation and this toolkit allows all three camps to process messages in their preferred way. Read on to find out how.

The 'diff' and 'patch' Conceptual Model

This same problem has been solved generically and well for text-oriented documents. The well-known 'diff' utility uses sophisticated and well-known algorithms to compare two text documents (or data streams) and represent the differences between them. The difference representation is not very human-readable and a cottage-industry has built up around providing front-ends to 'diff' which give colorized/visual representations of these differences.

However, 'diff's output is very machine intelligible and the 'patch' utility can take an original document, apply the diffs and generate an exact duplicate of the modified document. Essentially we have a simple equation: new - old = diffs from which we can see that the useful corollary: old + diffs = new follows immediately. This demonstrates the utility of 'diff' and 'patch' and this technology is at the core of all version control systems.

Now as we design wonderful new data respresentations in XML wouldn't it be useful if similar tools existed to perform similar operations on XML documents (or document fragments)? Unfortunately we can't use existing tools as XML is semantically very different from plain text. When we first started looking at this problem we found many people looking for solutions but only one implementation (XML Diff and Merge) over at IBM's Alphaworks site. However only binary object licenses are available and this utility didn't seem very adaptable to standard-specific applications (such as OTA).

Utilities and Examples

The following programs are provided as examples of how to use the toolkit. These tools may prove to be useful in their own right.

XmlDiff

Generates the difference between two XML documents.
Usage: java XmlDiff <OriginalURL> <ModifiedURL>
Differences are generated to stdout.

XmlPatch

Given a document and a difference document, produce a modified document:
Usage: java XmlPatch <OriginalURL> <DiffURL>
The modified document is generated to stdout.

Source code

Source for these utilities can be found in the examples directory of the distribution: