Skip navigation links

Package org.eigenbase.xom

Provides an object layer for reading and writing XML documents.

See: Description

Package org.eigenbase.xom Description

Provides an object layer for reading and writing XML documents.  The XML-Object Mapping layer generates a class for each entity in an XML schema, a member property for each attribute, collections for sub-objects, and methods to serialize to and from XML.

TODO jvs 15-Mar-2005: XOM is nice, but there's no longer a lot of reason for it to exist now that we have JAXB to do the same thing without any tricky bootstrapping issues. So we should phase out XOM.

 

Revision $Id: //open/util/resgen/src/org/eigenbase/xom/package.html#2 $
Copyright Copyright (C) 2005-2005 The Eigenbase Project
Copyright Copyright (C) 2005-2005 Disruptive Tech
Copyright Copyright (C) 2005-2005 Red Square, Inc.
Copyright Portions Copyright (C) 2001-2005 Kana Software, Inc.
Author Dan Sommerfield, Julian Hyde

Schema format

The schema is defined in an XML file, whose format is somewhat similar to an XML Schema.  The (self-describing) meta-schema is meta.xml (as you can see, an XSL style-sheet formats each schema into a javadoc-like web page).

Other schemas include resource.xml

Generated Java Classes

The utilities in this package enable conversion of XML (stored in a DOM-style model) into a typesafe Java representation. Roughly, conversion occurs as follows:

Converting an XML Document to its XOM representation is a two-step process. First, you parse the XML into a DOM representation using your favorite W3C DOM Level 1-compliant parser (note: MSXML is supported as well for backward compatibility). Then, you instantiate the XOM ElementDef subclass corresponding to the root element in the document, passing a portion of the DOM as input to the constructor. After this, the fully-constructed root element provides complete typesafe access to the whole document!

Specific instructions for parsing using a DOM-compliant parser (such as XERCES):

  1. Instantiate your parser, parse the document (validation against the DTD is optional), and retrieve the parsed Document object.
  2. Call Document.getDocumentElement() to retrieve the toplevel Node in the document.
  3. Wrap the toplevel node in an instance of W3CDOMWrapper.
  4. Construct the appropriate ElementDef subclass from the wrapped node.

Specific instructions for parsing using Microsoft's XML Parser:

  1. Instantiate your parser, parse the document (validation against the DTD is optional), and retrieve com.ms.xml.om.Document object representing the document.
  2. Call com.ms.xml.om.Document#getRoot() to retrieve the toplevel Element in the document.
  3. Wrap the toplevel element in an instance of org.eigenbase.xom.wrappers.MSXMLWrapper.
  4. Construct the appropriate ElementDef subclass from the wrapped node.

Generator

There is now an ANT target, XOMGen, implemented by XOMGenTask.

Tester

There is another helpful utility we use to verify that the stuff we generate works.  It is class MetaTester, and you invoke it as follows:

jview <classpath_options> org.eigenbase.xom.MetaTester [-debug]
        [-msxml | -xerces] <XML model file> <output dir> [<tests>...]
All the arguments are the same as the ones for MetaGenerator, except for tests.  <tests> is a list of test .xml files that should be valid according to the generated DTD.  The tester will validate the java files against the DTD and also against the java class.  It also runs some basic checks on the java class to make sure that it works.

Generation

For all XML files except meta.xml, we generate corresponding DTD and NameDef.java at build time.  MetaDef is tricky, because it depends upon itself; use the ant all target to rebuild it.

Guidelines for writing models

  1. Note that within an <Entity>, all <Attribute>s must occur before all <Object>, <Array> or <CData> elements.

Known Issues

Dependencies

This package is dependent upon the following other packages:

Class XOMGenTask only is dependent upon org.apache.tools.ant. You therefore require ant.jar to build, but not to run.

Class XercesDOMParser only is dependent upon org.xml.sax and org.apache.xerces.parsers.DOMParser. You therefore require xerces.jar to build, but not to run.

Skip navigation links