The schema2template project's objective is to provide an API for easily filling user templates from arbitrary XML schematas.

Introduction

This project allows you to process a RelaxNG schema file and to convert the definitions to any text based format you like. E.g. you can produce one source code file for each element defined in schema file. Or maybe you want to produce one single text or HTML based overview of the schema.

Since this project is based on the Sun Multi Schema Validator, it should be able to process multiple schema formats. However up to now it has only been tested with RelaxNG.

Several examples are delivered together with this project:

1. Read the OpenDocument Schema and produce a Java based DOM API
2. Read the OpenDocument Schema and produce an HTML overview of all ODF elements and attributes
3. Read the OpenDocument Schema and produce one single Python file which represents the element hierarchy

A non-trivial topic is the concept of multiple definitions for a single element or attribute, which is possible in RelaxNG. The easiest way would be to unite these definitions (we call them Multiples) to one common definition. However this way important information would be lost. E.g. one element may have the attribute foo whith possible value left. This attribute may also be possible in another element, but then with possible values left and right. That's why we decided to keep the distinction, even if it may make it harder to understand the API of this project. We might enhance this concept in the future, e.g. to exactly determine which of the multiple definitions holds for the current element in an ODF element tree.

Velocity Help

Schema2Template file structure

We use a 2-step procedure: First we generate a list of files we'd like to create. While we could write this list manually, the generation of this list frees us from having to write an entry for each schema element or attribute. The template to generate this list is called output-files.vm, the list itself (i.e. the result of running output-files.vm) is called output-files.xml.

Here's an example output-files.xml:

<?xml version="1.0" encoding="UTF-8"?>
<filelist>
    <file path="OdfHtmlSpecification.html" template="odf-reference-template.vm" />
    <file path="element/anim/AnimAnimateElement.java" 
    	     context="anim:animate" 
	     template="java-odfdom-element-template.vm" />
    ...
</filelist>

In the second step we parse output-files.xml. For every "file" entry we run the given Velocity "template", fill its context with the optional "context" property and write the output to the given "path". The "context" property (and as seen later - the optional "param" property as well) is used in templates which process only one element or attribute - to provide them with the name of this element or attribute. In the above example the template for the generation of a Java class is such a template, while the template to produce the whole OdfHtmlSpecification.html is a template whith a global context, i.e. it processes the whole Schema.

Schema2Template specific template help

In velocity templates, you have context objects, provided by the Java Velocity Runner Class. These are Java objects and you can call any method of these objects like you would do in Java. In Schema2Template we provide the following context objects (see JavaDoc of the given Classes):

Basically you could use every public method from the context objects in a Velocity template. But this is not in our intention. There are quite a few public methods which are only to be used internally, e.g. to extract our model from the Schema file.

To see the list of template-ready methods, you might want to look at the TemplateAPICoverageTest and the OdfTemplateAPICoverageTest from the source code bundle.

To give an example you will see that the PuzzleComponent method "canHaveText" is meant for template usage. On the other hand you wont find neither method compareTo nor extractPuzzlePieces from class PuzzlePiece there, so those methods are not meant to be used in templates. Only the methods covered by the two mentioned tests are protected against internal refactoring (especially against renaming).

Examples

Here's an example template to generate a ODF reference of attribute / elements. Here the PuzzlePieces are distinguished:

#foreach( $element in ${model.getElements()} )
#if (${element.withMultiples().size()} == 1)
#set ($duptext = "")
#set ($hasdup = false)
#else
#set ($duptext = "[${element.getMultipleNumber()}]")
#set ($hasdup = true)
#end
<h3>${element}${duptext} Element</h3>
#if ( $hasdup )
<p>There are more than one PuzzlePieces by this name.</p>
#end
#end

Here's an example output-files.vm which only produces one entry per name (processing just the element name so the Multiples can safely be removed):

<?xml version="1.0" encoding="UTF-8"?>
<filelist>
    <file path="OdfHtmlSpecification.html" template="odf-reference-template.vm" />
##
#foreach ( $element in ${model.getElements().withoutMultiples()} )
##
#set($classname = "${model.camelCase($element)}Element" )
    <file path="element/${element.getNamespace()}/${classname}.java" 
             context="$element" 
	     template="java-odfdom-element-template.vm" />
##
#end
</filelist>

Here's an example template to generate a Java class for an element name (by looking at all element Multiples at once).

To keep it short only the part where the Getter-Methods for all attribute names (by looking at all attribute multiples at once) are generated is shown:

## This will return a PuzzlePieceSet containing all element PuzzlePieces with name $context
#set($element = ${model.getElement($context)})
...
##
## Step 1: Iterate over all attributes with one random attribute PuzzlePiece per attribute name
#foreach ( $singleattr in ${element.getAttributes().withoutMultiples()} )
##
## Step 2: Get all attribute definitions for one attribute name. 
## Not needed if we're just processing the attribute name
#set($attribute = ${singleattr.withMultiples()}
##
#set($aClassname = "${model.camelCase($attribute)}Attribute" )
	/**
	 * Gets the value of the <code>$aClassname</code> attribute, 
	 * see {@odf.attribute ${attribute}}
	 *
	 * @return - the <code>String</code> attribute value
	 */
	public String get${aClassname}() {
	   ...
	}
#end
...

Example for the byParent method: Input value validation in attribute template

Implementation detail: one attribute and one parent class implemented per name - thus ignoring PuzzlePiece multiples at Java class level. However differences between attribute PuzzlePieces are respected by using a different validation:

  ## This will return a PuzzlePieceSet containing all attribute PuzzlePieces with name $context
  #set($attribute = ${model.getAttribute($context)})
  ...
  public void setValue(String value) {
  	boolean valid = false;
  ##
  ## Iterate over parent names and get all Multiples for each name
  #foreach ($singleparent in ${attribute.getParents().withoutMultiples()})
  #set ($parent = $singleparent.withMultiples())
  	if (getParent() instanceof ${model.camelCase($parent)}Element) {
  ##
  ## Allow only datatypes from attribute definitions reachable from $parent
  ## Thus here we're respecting the different definitions for the current attribute
  #foreach ($datatype in ${attribute.byParent($parent).getDatatypes()})
    		valid = valid || validate(${datatype}.class, value);
  #end
	}
  #end
  	if (!valid) {
		throw new IllegalArgumentException(
			"Invalid Value for attribute $attribute and parent "
			+ getParent().ELEMENT_NAME);
	}
	mValue = value;
  }