# XOM FAQ

Elliotte Rusty Harold
ERH
2002-2005, 2009, 2016, 2018, 2020 Elliotte Rusty Harold

What's the difference between XOM and JDOM?

XOM and JDOM are completely separate products. Originally, I had thought I could build XOM by forking JDOM, but it quickly became apparent that it would be simpler to start over from scratch. Some early versions of XOM did use one class from JDOM (Verifier) in its internal, non-public parts. This class has been rewritten substantially; and in the current version there's no JDOM code left. The rest of the API is completely free of JDOM code.

Conceptually, XOM definitely did adopt a number of ideas from JDOM, including:

- Using a SAX parser to build the object model.

- Using a factory to enable the parser to build subclasses of the core classes.

- Subclassing SAXSource and SAXResult to support TrAX.

- Array lists are faster than linked lists.

However, XOM also freely borrowed good ideas from DOM, XPath, and other systems, and invented not a few new ones of its own. Features in XOM that have no real equivalent in JDOM include:

- A common Node superclass

- The getValue method that returns the XPath value of any node.

- The toXML method that returns a string containing the XML serialization of that node. (JDOM actually did use the toString method for this in the first few betas. However, when JDOM decided to use the toString method for debugging info instead, they never replaced it with another method.)

- Canonical XML support

- XInclude support

- Streaming processing of documents larger than available memory

- Well-formedness safe subclassing

- Better support for invalid documents, including validating without rejecting invalid documents and reporting more than one validity error per document

There are also many features that JDOM and XOM share, but that are implemented very differently in the two APIs:

- In XOM namespaces are just strings. In JDOM namespaces are instances of the Namespace class.

- In JDOM, an Element contains a list. In XOM, an Element is a list. This makes for very different styles of navigation.

- JDOM exposes lists using the java.util.List class to expose live lists of attributes and content. XOM uses comatose, read-only lists implemented with custom classes. Unlike standard lists, XOM lists expose the types of the nodes they contain. That is, there are separate lists for attributes, elements, namespaces, and so forth.

- Internally, JDOM uses a very sophisticated filter list that knows a great deal about the types of nodes it contains. However, this information is not exposed in the public API. XOM is almost exactly backwards from this. Internally, it uses very simple lists that know nothing about the types of the things they contain. Externally, however, it exposes lists that contain nodes of very specific types.

- JDOM passes prefixes and local parts separately to setter methods. XOM expects them to be passed as a single qualified name.

- JDOM supports skipped entity references. XOM requires all entity references to be resolved.

- JDOM reports CDATA sections. XOM automatically merges them with their surrounding text.

- JDOM classes implement Cloneable and provide clone methods. XOM classes use a copy method instead.

- JDOM classes implement Serializable. XOM classes use XML as a persistence format.

Finally, XOM hews closely to the motto that Less is more. It deliberately eschews the many convenience methods that make the JDOM API so cluttered such as getChildText/getChildTextTrim/getChildTextNormalize/getText/getTextTrim/getTextNormalize. If overloaded variants are included, there are nine separate methods for reading the text of an element. XOM has one, getValue. If you need to trim or normalize the value, you can use the methods of the String class.

Does XOM support XML 1.1?

No. XML 1.1 is an abomination. You don't need it and you shouldn't use it. In general, XOM focuses on giving developers what they need instead of what they think they want.

XOM 1.0 through 1.3 will not support XML 1.1. Possible future versions might, provided someone can demonstrate an actual need for it. The following are not legitimate needs:

1. Your pointy-haired boss wants to use the latest version of XML.

2. You have documents that use version="1.1" for no good reason. Fix the documents instead.

3. Your documents contain NEL characters that are incompatible with almost every installed system (XML and non-XML) on the planet. Throw away your IBM dinosaur, and join the 21st century.

You just might convince me you have a legitimate need for C0 control characters, but I doubt it. That still leaves a couple of possible uses for XML 1.1, but they're very obscure. (Do you speak Burmese?) Note that a hypothetical use-case is not going to do it. You're going to have to show me that you actually need to do this, and that you are going to use XOM.

Can I make XOM smaller?

Yes. All you really need is the xom.jar file. This contains all the core packages, but not the samples or unit tests. It has no dependencies besides the JDK 1.5 or later.

If you want to trim XOM down even further, you can remove some of the non-core packages. All you really must have is in the nu.xom package. nu.xom.xslt, nu.xom.canonical, nu.xom.xinclude, and nu.xom.converters are only needed if you want their functionality. Nothing in the core nu.xom package depends on them.

Can I make XOM faster?

There are a number of techniques you can use to speed up your XOM programs. Among them:

- If you're making many instances of the same thing (Element, DocType, Text, whatever), make a prototype object and copy it using the copy constructor or the copy method instead of constructing it directly from strings. This avoids the overhead of reverifying element names, PCDATA, etc. for each object created.

- Don't use XPath. XPath is currently implemented for convenience, simplicity, and robustness; not performance. It has not yet been profiled or optimized. (This may change in the future.) If you do use XPath, you might want to consider using SAXON, both of which provide some options to speed up XPath, instead of XOM 1.1's built-in XPath support.

- Consider doing more work in the NodeFactory as the document is constructed.

- If you don't need pretty printed output or a document type declaration, experiment with using a Canonicalizer instead of a Serializer. All the options for setting the indenting, maximum line length, and the like in Serializer exact about a 30-40% performance penalty compared to just slamming the document onto an OutputStream without any options like Canonicalizer does.

As a last resort, the Text class is optimized for size, not speed. If size is not a major concern, you can fork this class to make Text objects faster but larger. Making this a build-time option is on the TODO list, but has not yet been implemented.

Can I make XOM use less memory?

Yes. If your documents are so large that you're running out of memory, you can use a custom NodeFactory to strip them down before processing. nu.xom.samples.NormalizingFactory demonstrates how to strip boundary whitespace from record-like XML while building the document. If you only want some of the content in the input document you can go even further, simply not building any of the parts of the document that correspond to things you aren't interested in. You can drop out elements, attributes, comments, processing instructions, and so on.

If the document you've built is still too large to handle, then you can try processing in streaming mode inside the NodeFactory as the document is being read. This doesn't permit random access to the entire document at the same time, but it does allow you to process arbitrarily large documents in a reasonable amount of memory. There are several examples of this in the `nu.xom.samples` package: StreamingElementLister, StreamingXHTMLPurifier, StreamingTreePrinter, StreamingROT13, etc.

Will XOM run with Java 1.1? 1.2? 1.3? 1.4? 1.5? 1.6? 1.7? 1.8?

XOM 1.3.x requires Java 1.5 or later. Earlier versions require 1.2 or later. It has been tested with Java 1.2.2_17, IBM's Java VM 1.3.1, Sun's JDK 1.4.2, IBM's JVM 1.4.1, and various betas of Java 1.5. A few of the unit tests fail in Java 1.2, but mostly these reflect encodings such as ISO-8859-6 that are not supported in that VM. All the core functionality is present. It has not yet been tested with anything past Java 1.8.

Isn't the LGPL incompatible with Java? Can I have a different license?

You should learn better than to believe everything you read on Slashdot. The LGPL is completely compatible with Java. Claims that it is not are based on severe misunderstandings of either Java, the LGPL, or both. The official word from the FSF's David Turner is,

> If you distribute a Java application that imports LGPL libraries, it's easy to comply with the LGPL. Your application's license needs to allow users to modify the library, and reverse engineer your code to debug these modifications. This doesn't mean you need to provide source code or any details about the internals of your application. Of course, some changes the users may make to the library may break the interface, rendering the library unable to work with your application. You don't need to worry about that -- people who modify the library are responsible for making it work.

> When you distribute the library with your application (or on its own), you need to include source code for the library. But if your application instead requires users to obtain the library on their own, you don't need to provide source code for the library.

> The only difference between Java and C from the LGPL's perspective is that Java is an object-oriented language, supporting inheritance. The LGPL contains no special provisions for inheritance, because none are needed. Inheritance creates derivative works in the same way as traditional linking, and the LGPL permits this type of derivative work in the same way as it permits ordinary function calls.

If you would like a license to use XOM under other conditions, feel free to make me an offer. Non-LGPL, closed source licenses are available for a reasonable fee.

How is nu.xom pronounced?

Like new dot zom.

Does this have anything to do with Omnimark?

No. I had no idea that the three letter extension for Omnimark files was `.xom` until someone brought it up in Q&A at my presentation at the New York XML SIG.

Why doesn't XOM implement the Visitor pattern?

I'm somewhat familiar with the visitor pattern. I did explore it when I was first designing XOM. I'm still not convinced it really fits the XML problem space well. I don't like adding the extra method to Node just to support this. I may be wrong here. So far nobody's shown me convincingly how Visitor would make their life easier than using the more traditional navigation techniques. I'm inclined to agree with the DOM FAQ here:

> Visitor was considered for inclusion in the Traversal module of the Level 2 DOM. There are negative as well as positive consequences to implementing the Visitor pattern. One of Visitor's advantages over Iterator is that Visitor can handle structures where the objects don't share a common ancestor class, which is not an issue when everything you're looking at is derived from Node. Since most of the things a Visitor could do can be emulated with a switch statement driven by an iterator, we decided to defer this issue.

Or at least I agree until someone shows me how much easier visitor would make important operations.

It's also a question of programmer familiarity. I think Visitor is one of those issues like interfaces vs. classes, push vs. pull, and pointers vs. stack variables, where the more advanced solution may be marginally better and more extensible for some uses, but really exceeds a lot of working programmers' comfort level. The level of abstraction and indirection can just get too high. Putting the client more in control is a lot more comfortable for most programmers since they can more easily see and visualize how the code flows. I am willing to trade some level of extensibility and generality in exchange for simplicity.

How can I validate against a schema in XOM?

XOM does not have built-in support for schema validation. However, you can use a schema-validating SAX XMLReader which XOM will treat the same as a DTD-validating XMLReader. For example, suppose you want to use Xerces to perform schema validation. You would set up the Builder thusly:

      String url = "http://www.example.com/";
      try {
        XMLReader xerces = XMLReaderFactory.createXMLReader("org.apache.xerces.parsers.SAXParser");
        xerces.setFeature("http://apache.org/xml/features/validation/schema", true);

        Builder parser = new Builder(xerces, true);
        parser.build(url);
        System.out.println(url + " is schema valid.");
      }
      catch (SAXException ex) {
        System.out.println("Could not load Xerces.");
        System.out.println(ex.getMessage());
      }
      catch (ParsingException ex) {
        System.out.println(args[0] + " is not schema valid.");
        System.out.println(ex.getMessage());
        System.out.println(" at line " + ex.getLineNumber()
          + ", column " + ex.getColumnNumber());
      }
      catch (IOException ex) {
        System.out.println("Due to an IOException, Xerces could not check " + url);
      }

Why do some of the unit tests fail when building XOM?

There are two known failures that arise in some environments and not others. testBuildFromFileWithPlane1CharactersInTheName in BuilderTest fails on the Mac. This test exposes a bug in the Mac OS X Java VM. The test passes on other platforms.

Several of the tests in XSLTransformTest including testOASISXalanConformanceSuite, testOASISMicrosoftConformanceSuite, and testKeysPerfRepro3 fail in Java 1.4 due to bugs in the version of Xalan bundled with Sun's JDK. These tests pass in Java 1.5. They will also pass in Java 1.4 if you put the version of Xalan found in the lib directory in your jre/lib/endorsed directory so it will override the one bundled with the JDK. You can find out which version of Xalan you have by running "ant version" in the main XOM directory. You'll need 2.6.1 or later for all the test to pass.

Roughly seven integration tests including `nu.xom.tests.BaseURITest` and `nu.xom.tests.SAXConverterTest` make connections to www.ibiblio.org. These fail if that site is not reachable. At least some of the time ibiblio.org has been blocked by the Great Firewall of China, likely because it hosts various Tibet-related content. IBiblio itself has been known to block access through VPNs. If any of these tests fail, check whether you can access www.ibiblio.org in a regular web browser.

Why does xsl:output have no effect when transforming with XOM?

xsl:output has no relevance to tree construction, only to the serialization of the result tree as text. Since XOM's XSLT constructs a result tree, but does not serialize it, xsl:output has no effect. You can set any necessary serialization options directly on the Serializer.

How do I find all the namespaces in scope on an element?

Use XPath. Specifically use the query

    Nodes namespaces = element.query("namespace::node()");