RelaxNGCC Tutorial 1

RelaxNGCC is a tool for generating Java source code from a given RELAX NG grammar. By embedding code fragments in the grammar, you can take appropriate actions while parsing valid XML documents against the grammar.

For first example, suppose the following XML instance. This is a list of Japan national team members for the soccer game, which was held on Aug 15, 2001 against Australia.

<?xml version="1.0" encoding="utf-8"?>
  <player number="1" ><name>Yoshikatsu Kawaguchi</name></player>
  <player number="3" ><name>Naoki Matsuda</name></player>
  <player number="4" ><name>Ryuzo Morioka</name></player>
  <player number="16"><name>Koji Nakata</name></player>
  <player number="21"><name>Yasuhiro Hato</name></player>
  <player number="14"><name>Teruyoshi Ito</name></player>
  <player number="17"><name>Kazuyuki Toda</name></player>
  <player number="6" ><name>Toshihiro Hattori</name></player>
  <player number="8" ><name>Hiroaki Morishima</name></player>
  <player number="9" ><name>Atsushi Yanagisawa</name></player>
  <player number="22"><name>Takayuki Suzuki</name></player>

This XML instance has a team element as the root element, and the team element has one or more player elements. Additionally, the each player element has a number attribute and name element. A RELAX NG grammar representing this structure is following.

<?xml version="1.0" encoding="utf-8"?>
<grammar xmlns=""
<start c:class="sample1">

<element name="team">
    <element name="player">
      <attribute name="number">
        <data type="positiveInteger" c:alias="number"/> [1]
        <c:java>System.out.println(number);</c:java> [2]
      <element name="name">
        <text c:alias="name"/> [3]
        <c:java>System.out.println(name);</c:java> [4]



Additional information peculiar to RelaxNGCC, which has the namespace prefix "c" is emphasized with red. At first, look the data element[1] that indicates the value of number attribute. It has an alias attribute. The alias attribute declares that the Java source code in java element can refer to the value of data element using the variable "number". In the same way, the value of name element[3] is associated with the variable "name".

Next, we introduce the "java" elements ([2],[4]). We can use a java element with a chip of Java source code to describe an action invoked by reading a fragment of XML instance. In the example above, the generated code prints the contents of number attribute and name element to System.out.

Be careful that the System.out.println is executed the same number of times as the number of player elements since all the java elements are enclosed by the oneOrMore element.

Now, let's compile this grammar using RelaxNGCC.

$ java -classpath msv.jar;relaxngcc.jar relaxngcc.RelaxNGCC sample1.rxm

As a result, RelaxNGCC generates a Java source file at current directory. A part of it is following, and complete source is available from here.

import java.math.BigInteger;
import org.xml.sax.SAXException;
import org.xml.sax.XMLReader;
import relaxngcc.runtime.NGCCPlainHandler;
import javax.xml.parsers.SAXParserFactory;
import javax.xml.parsers.ParserConfigurationException;

class sample1 extends NGCCPlainHandler {
public static final String DEFAULT_NSURI = "";
private int _ngcc_current_state;
private String name;
private String number;
(omitted some lines)
public void enterElement(String uri,String localname,String qname) throws SAXException
if(_ngcc_current_state==1) {
if(localname.equals("player") && uri.equals(DEFAULT_NSURI)) {

(omitted some lines)
public void text(String value) throws SAXException
if(_ngcc_current_state==4) {


else if(_ngcc_current_state==6) {

If you compile the file and run it, you will see the result as following.
$ javac -classpath msv.jar:relaxngcc.jar:.
$ java -classpath msv.jar:relaxngcc.jar:. sample1.xml
Yoshikatsu Kawaguchi
Naoki Matsuda
Ryuzo Morioka
Koji Nakata
Yasuhiro Hato
Teruyoshi Ito
Kazuyuki Toda
Toshihiro Hattori
Hiroaki Morishima
Atsushi Yanagisawa
Takayuki Suzuki

Thus, the most basic way of using RelaxNGCC is naming a data or a text element with an alias attribute, and embedding the action you want with a java element. Since you can write any Java code in the java elements, it is easy to perform flexible actions such as calling external libraries or accessing databases.

RelaxNGCC home