xom

nu.xom is the core package of XOM that contains all the basic classes representing the different kinds of nodes: elements, attributes, comments, text nodes, and so forth. It also contains the basic classes for parsing and serializing XML documents, as well as the various exception classes representing the different things that can go wrong while working with XOM.

nu.xom.benchmarks includes some basic benchmarks to test the speed and memory usage of XOM programs.

nu.xom.canonical supports the output of Canonical XML from XOM. For basic canonicalization of existing documents, this (or any other tree-based solution) is likely not as efficient as a streaming, SAX-based solution. However, this is useful for output from XOM in canonical form.

nu.xom.converters contains classes that convert XOM documents to other models such as SAX and DOM.

nu.xom.samples includes several dozen example programs that demonstrate different parts of the XOM API. These are intended for tutorial purposes. They are not designed as reusable code for the most part. Most of the examples are adapted from Processing XML with Java by Elliotte Rusty Harold. Please consult that book (available in its entirety online) if you'd like more information about what particular samples are intended to show. That book provides SAX, DOM, and/or JDOM implementations of most of these samples.

These classes are not officially part of the XOM API. They have not been extensively tested, and I make no promises that they will be part of any future XOM release; or, if they are, that their APIs will remain compatible. Should you find any of them useful and wish to use them in your own code, I recommend you copy the source code, and place it in your own package. It probably wouldn't hurt to add a lot of unit tests as well.

nu.xom.tests contains the JUnit based test suite for XOM. JUnit 3.7 or later is required. (Earlier versions don't have the assertTrue method these tests depend on.)

The XOMTests class runs all the tests, except those that take an exceptionally long time to run (MegaTest). Some of the tests, especially the builder tests, depend on the underlying parser, and are known to fail if the parser is buggy. Xerces 2.6.1 is the only parser which is currently known to be able to run all the tests. Earlier versions of Xerces 2.x cannot successfully run all the tests. The IBM JVM 1.4.1 bundles an earlier version of Xerces which overrides the one bundled with XOM. For this reason, a few tests will fail when using that VM. These tests should pass when using the Sun VMs.

Similarly some of the XSLT tests depend on the underlying TrAX engine. Xalan 2.7 and Saxon 6.5.4 both do a pretty good job, but neither can pass all thne tests included with XOM. testOASISMicrosoftConformanceSuite is the most likely test to fail.

A few tests rely on access to external network resources, and may fail sproadically if the remote server is down or unreachable. However, in general, they pass.

The only other test in this class which is known to fail is testBuildFromFileThatContainsPlane1CharacterInName. This test fails on Mac OS X due to bugs in that platform's VM. However, it passes on other platforms.

There are numerous public classes and methods in this package because JUnit requires all test cases to be public. However, the only published class is XOMTestCase which provides methods for asserting the equality of documents, elements, processing instructions, and other node types. This may be useful for your own tests. The remainder of this package should be treated as unstable and your code should not depend on it.

nu.xom.tools contains classes that are used to build XOM. They are not part of the published API.

nu.xom.xinclude supports XInclude processing of XOM documents and elements. It is conformant to the final recommendation of XML Inclusions (XInclude) Version 1.0 including fallbacks, XPointer bare names, the accept and accept-language attributes, and the XPointer element() scheme.

nu.xom.xslt connects XOM documents to TrAX-based XSLT processors.