# Package org.eigenbase.xom

package org.eigenbase.xom
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:

- Each defined `Element` becomes a Java Class. The Java Class name matches the Element name. All classes representing Elements descend from `ElementDef`. 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 called `cdata`.
- 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 of `ElementDef` called `children`.

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
   invalid reference

       com.ms.xml.om.Document

   object representing the document.
2. Call
   invalid reference

       com.ms.xml.om.Document#getRoot()

   to retrieve the toplevel Element in the document.
3. Wrap the toplevel element in an instance of
   invalid reference

       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:

- `java.lang`, `java.io`, `java.util`

Class `XOMGenTask` only is dependent upon

invalid reference

    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

invalid reference

    org.apache.xerces.parsers.DOMParser

. You therefore require `xerces.jar` to build, but not to run.

Related Packages
Package
Description
org.eigenbase.xom.wrappers
Class
Description
Any
An element which has 'Any' content.
AssertFailure
todo:
CdataDef
A `CdataDef` represents a CDATA element.
CommentDef
todo:
DefWalker
DefWalker is a class designed to help users of plugin elements and elements with content type ANY.
DOMElementParser
DOMElementParser is a utility wrapper around DOMWrapper.
DOMWrapper
DOMWrapper implements a Wrapper around the Element class from any DOM-style XML parser.
ElementDef
ElementDef is the base class for all element definitions.
GenericDef
A `GenericDef` is a `ElementDef` whose attributes and children are stored in collections, not generated members.
Location
Represents the location of a node within its document.
Locator
Callback to find the location of a node within its document.
MetaDef
This model is the XOM Meta Model.
MetaDef.Any
The Any content is a special marker which allows an Element to contain any type of data.
MetaDef.Array
An Array is a set of multiple instances of Elements.
MetaDef.Attribute
The Attribute entity appears within any Element definition.
MetaDef.CData
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.
MetaDef.Class
A Class Definition defines a class of entities.
MetaDef.Content
The Content class contains all entities which represent types of content which may appear within an Element.
MetaDef.Definition
The Definition class represents a generic type of element definition.
MetaDef.Element
An Element Definition defines a basic entity of the meta model.
MetaDef.FullDefinition
The FullDefinition class represents a fully-specified definition that may include content.
MetaDef.Import
An Import as a special type of element that represents another element stored in an external model.
MetaDef.Model
Model is the top-level element for a model description.
MetaDef.Object
An Object is a single instance of an Element type.
MetaDef.Plugin
A Plugin in a special type of element whose content may be derived from a different model.
MetaDef.StringElement
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
`MetaGenerator` is a utility class which reads a XOM Meta Model description in XML and generates the corresponding .dtd and .java definition files.
MetaTester
The MetaTester class is a utility class for testing generated models.
NodeDef
`NodeDef` represents a node in a parse tree.
Parser
The `Parser` interface abstracts the behavior which the `org.eigenbase.xom` package needs from an XML parser.
ParserTester
Test the MSParser
StringEscaper
`StringEscaper` is a utility for replacing special characters with escape sequences in strings.
TextDef
A `TextDef` represents piece of textual data in an XML document.
WrapperElementDef
`WrapperElementDef` is an `ElementDef` which retains the underlying XML `DOMWrapper`.
XMLAttrVector
XMLAttrVector is an class which assists in writing XML attributes to a stream.
XMLOutput
XMLOutput is a class which implements streaming XML output.
XMLUtil
Utilities for dealing with XML data.
XOMException
XOMException extends Exception and provides detailed error messages for xom-specific exceptions.
XOMGenTask
`XOMGenTask` is an ANT task with which to invoke `MetaGenerator`.
XomTest
Unit tests for XOM module.
XOMUtil
Utility functions for the `org.eigenbase.xom` and `org.eigenbase.xom.wrappers` packages.