RNGOM User's Guide

By Kohsuke Kawaguchi

Quick Start

See the sample code in the test directory to quickly get up to speed. Run the sample as follows:

$ java -jar rngom-sample.jar <schema file>

Basic Concepts

RNGOM defines several interface sets through which applications interact with RNGOM.

Parseable
Parseable is either a CompactParseable or SAXParseable, and it represents the source RELAX NG schema file to be parsed. RNGOM can parse them by invoking their parse method.
SchemaBuilder and the ast.builder package
The ast.builder package (rooted at SchemaBuilder) defines a set of callback interfaces to parse RELAX NG schemas. When the Parseable.parse method is called, it takes a SchemaBuilder as a parameter and then "parses" a schema by firing appropriate callbacks through the interfaces of the ast.builder package.
Application can implement those interfaces to build application-specific object model from RELAX NG schemas.
ast.om package
This package is a set of marker interfaces that defines the RELAX NG object model. These markers are used simply to increase type-safety throughout RNGOM. If you choose to define the custom object model, it has to implement those markers.
org.relaxng.datatype package
This package defines a set of interfaces for pluggable datatypes. See its javadoc for more details.

Default Implementations

RNGOM comes with a few default implementations of the above interface sets.

rngom.nc package
This package defines a default implementation of the name class portion of the ast.om/ast.builder packages.
rngom.binary package
This package defines a default implementation of the rest of the ast.om/ast.builder packages. This package models the simple syntax of RELAX NG, and it doesn't carry any annotations, comments, nor location information. Also, it does not preserve <grammar>, <include>, <define> and <ref>. This implementation might be useful for applications such as validators and editors which are typically interested in the structural relationship between elements and attributes.
rngom.digest package
This package defines another default implementation of the rest of the ast.om/ast.builder packages. This package is aimed toward databinding applications, which typically care about how patterns are <define>d and <ref>erenced. This model also captures the annotations.

Datatype Libraries

To use rngom.binary or rngom.digest packages, you need to have appropriate datatype library implementaions that implement the org.relaxng.datatype API. This typically means you'd want to have an XML Schema datatypes library implementation such as xsdlib.jar. By default, you just need to set classpath to include this jar and that should work. To customize this process, refer to javadoc.

Doing Full Check

The RELAX NG spec defines a series of "restrictions" that correct RELAX NG schemas have to follow. To check those, change your following normal code:

Parseable parseable = ...;
YourParsedPattern = (YourParsedPattern)parseable.parse(schemaBuilder);

... to the following:

import org.kohsuke.rngom.ast.util.CheckingSchemaBuilder;

Parseable parseable = ...;
YourParsedPattern = (YourParsedPattern)parseable.parse(new CheckingSchemaBuilder(schemaBuilder,errorHandler));

See its javadoc for more details. Doing this guarantees that your application will reject all the incorrect schemas.

Writing Your Own SchemaBuilder

For better or worse, James Clark didn't leave much comment in his code, so you are more than welcome to contribute javadoc on those interfaces :-)

The abovementioned sample program prints out the callbacks and their parameters, so try it to learn about how the callbacks are called.

JDK5.0 Support

If you can require JDK 5.0 as your runtime environment, use rngom.jar instead of rngom-1.3.jar. This is a generified version of RNGOM that provides additional type safety.

Redistribution

To use RNGOM with JDK 1.3 or later, redistribute jax-qname.jar, rngom-1.3.jar, and relaxngDatatype.jar. You also need the JAXP API and an implementation.

To use RNGOM with JDK 1.4 or later, the list is the same except that you don't need to have a JAXP API nor its implementation (because the JRE has one already)

To use RNGOM with JDK 5.0 or later, just redistribute rngom.jar and relaxngDatatype.jar.


Back