VM Tools User Documentation - v0.5
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.
The initial release has the following features:
- Uses sophisticated algorithm to calculate difference between two XML documents
- Supports generic OTA_Update message generation/processing
- The difference document generated is optimized for minimal size
- Core code is generic and extensible
- Designed to plug into your java application
- Minimal subset XPath implementation allows use of simple XPath notation
to reference change points within the source document.
This implementation will work for data-oriented XML but not for document-oriented XML.
Specific limitations are as follows:
- XML comments are not supported
- XML processing instructions are not supported
- There is no provision for dealing with small differences in extremely
lengthy CDATA sections
- Currently the only difference representation supported is the OTA
difference notation (however alternate representations may be developed
and plugged in through extensions)
VMTools has the following prerequisites:
- You'll need a Java 2 Standard Edition runtime environment
(1.2 or above is fine). If you are running a 1.2 environment, you'll also need:
- Java APIs for XML Processing (JAXP)
- A JAXP-compatible XML parser such as Xerces or
Crimson
- You'll also need the JDOM toolkit. (We recommend beta 7 or above).
- If you intend to rebuild the jars from source you will also need
Jakarta Ant.
- and if you intend to build/run the regression tests you'll need a copy of the
excellent testing framework JUnit.
Details go here.
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.
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.
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).
The following programs are provided as examples of how to use the toolkit.
These tools may prove to be useful in their own right.
Generates the difference between two XML documents.
Usage: java XmlDiff <OriginalURL> <ModifiedURL>
Differences are generated to stdout.
Given a document and a difference document, produce a modified document:
Usage: java XmlPatch <OriginalURL> <DiffURL>
The modified document is generated to stdout.
Source for these utilities can be found in the examples
directory of the distribution: