# 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