Package org.eigenbase.xom
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:
- Each defined
Element
becomes a Java Class. The Java Class name matches the Element name. All classes representing Elements descend fromElementDef
. All classes from the same model are implemented as static inner classes of a single enclosure class. By convention, enclosure classes always end in "Def". - Each
Attribute
becomes a public member of its enclosing Element class. - Text (
PCDATA
) content becomes a single public String calledcdata
. - Element content becomes a series of public members. The members are of the appropriate types. The members' names are defined in the schema.
ANY
content becomes a single array ofElementDef
calledchildren
.
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):
- Instantiate your parser, parse the document (validation against the DTD is optional),
and retrieve the parsed
Document
object. - Call
Document.getDocumentElement()
to retrieve the toplevel Node in the document. - Wrap the toplevel node in an instance of
W3CDOMWrapper
. - Construct the appropriate
ElementDef
subclass from the wrapped node.
Specific instructions for parsing using Microsoft's XML Parser:
- Instantiate your parser, parse the document (validation against the DTD is optional),
and retrieve
com.ms.xml.om.Document
object representing the document. - Call
com.ms.xml.om.Document#getRoot()
to retrieve the toplevel Element in the document. - Wrap the toplevel element in an instance of
org.eigenbase.xom.wrappers.MSXMLWrapper
. - 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:
All the arguments are the same as the ones forjview <classpath_options> org.eigenbase.xom.MetaTester [-debug] [-msxml | -xerces] <XML model file> <output dir> [<tests>...]
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 exceptmeta.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
- 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.
-
ClassDescriptionAn element which has 'Any' content.todo:A
CdataDef
represents a CDATA element.todo:DefWalker is a class designed to help users of plugin elements and elements with content type ANY.DOMElementParser is a utility wrapper around DOMWrapper.DOMWrapper implements a Wrapper around the Element class from any DOM-style XML parser.ElementDef is the base class for all element definitions.AGenericDef
is aElementDef
whose attributes and children are stored in collections, not generated members.Represents the location of a node within its document.Callback to find the location of a node within its document.This model is the XOM Meta Model.The Any content is a special marker which allows an Element to contain any type of data.An Array is a set of multiple instances of Elements.The Attribute entity appears within any Element definition.The CData content is a special marker which allows an Element to contain a single CDATA section as its only content, yet still have attributes.A Class Definition defines a class of entities.The Content class contains all entities which represent types of content which may appear within an Element.The Definition class represents a generic type of element definition.An Element Definition defines a basic entity of the meta model.The FullDefinition class represents a fully-specified definition that may include content.An Import as a special type of element that represents another element stored in an external model.Model is the top-level element for a model description.An Object is a single instance of an Element type.A Plugin in a special type of element whose content may be derived from a different model.A StringElement is a simple type of element which has no attributes and whose content is a single String (usually represented as a CDATA section).MetaGenerator
is a utility class which reads a XOM Meta Model description in XML and generates the corresponding .dtd and .java definition files.The MetaTester class is a utility class for testing generated models.NodeDef
represents a node in a parse tree.TheParser
interface abstracts the behavior which theorg.eigenbase.xom
package needs from an XML parser.Test the MSParserStringEscaper
is a utility for replacing special characters with escape sequences in strings.ATextDef
represents piece of textual data in an XML document.XMLAttrVector is an class which assists in writing XML attributes to a stream.XMLOutput is a class which implements streaming XML output.Utilities for dealing with XML data.XOMException extends Exception and provides detailed error messages for xom-specific exceptions.XOMGenTask
is an ANT task with which to invokeMetaGenerator
.Unit tests for XOM module.Utility functions for theorg.eigenbase.xom
andorg.eigenbase.xom.wrappers
packages.