Usage Instructions

Overview

ManekiNeko implements a Xerces2 parser configuration that wraps James Clark's Jing validator for Relax NG using XNI. This allows application developers to validate XML documents against Relax NG grammars and access the document information using standard APIs such as DOM and SAX. Users of ManekiNeko can call the parser configuration directly but will most likely use the convenient parser classes included with this package.

The ManekiNeko parser configuration is defined in the JingConfiguration class located in the org.cyberneko.relaxng package. For convenience, this class provides a main method for easily verifying XML documents that conform to a Relax NG grammar. The program requires at least two parameters: the first parameter is the system identifier of the Relax NG grammar and the remaining parameters are the system identifiers of the documents that you want validated. For example: (Note: the command line should be on a single line)

> java org.cyberneko.relaxng.JingConfiguration 
       data/relaxng/personal.rng data/relaxng/personal-err.xml
# argv[1]: data/relaxng/personal-err.xml
[Error] personal-err.xml:5:43: unknown element "personA"
[Error] personal-err.xml:11:44: bad value for attribute "salary"

The JingConfiguration program does not output any of the document content. It will only display validation errors that occur.

Regardless of how ManekiNeko is used the program must set the location of the Relax NG grammar document before parsing documents that conform to that grammar. This is required because Relax NG does not provide a mechanism for specifying the grammar within the document instance. If such a mechanism is invented in the future, support will be added to ManekiNeko. But, for now, you must programmatically set the schema location by setting the "http://cyberneko.org/xml/properties/relaxng/schema-location" property. An example of how to set this property is included in the next section.

Note: In order to use ManekiNeko, you must download James Clark's Jing validator and include the Jing Jar file in the JVM's classpath.

Convenience Parser Classes

Separate DOM and SAX parser classes are included in the org.cyberneko.relaxng.parsers package for convenience. Both parsers use the JingConfiguration class to be able to parse XML documents. The following example shows how to use the ManekiNeko DOMParser directly:

org.cyberneko.relaxng.parsers.DOMParser parser = 
  new org.cyberneko.relaxng.parsers.DOMParser();
parser.setFeature("http://xml.org/sax/features/namespaces", true);
parser.setFeature("http://xml.org/sax/features/validation", true);

parser.setProperty("http://cyberneko.org/xml/properties/relaxng/schema-location", 
                   "data/relaxng/personal.rng");
parser.parse("data/relaxng/personal.xml");

Custom Parser Classes

Alternatively, you can construct any XNI-based parser class using the JingConfiguration parser configuration class found in the org.cyberneko.relaxng package. The following example shows how to extend the abstract SAX parser provided with the Xerces2 implementation by passing the ManekiNeko parser configuration to the base class in the constructor.

import org.apache.xerces.parsers.AbstractSAXParser;
import org.cyberneko.relaxng.JingConfiguration;

public class JingSAXParser extends AbstractSAXParser {
    public JingSAXParser() {
        super(new JingConfiguration());
    }
}