# XML Generators Package

Maintainer: Petr Kuzel and Libor Kramolis

Updated on: 11th Jun 2001

## Introduction

Generators in this package eliminates writing complex but routine code.

## To do

    What about sample implementation generate attributes switch

## Requirements

Provide Java and XML code generators:

1. Java code generator creating SAX parser of documents following given DTD.
2. Java code generator creating DOM scanner (a visitor) of DOM following given DTD.
3. DTD generator guessing it from an XML document.
4. All Java generators produces a JAXP compliant code to achieve parser neutrality.

## User's View

## SAX Document Handler Wizard

This wizard is useful for generating XML content parsers. As typical example can be taken a configuration file or incoming XML message. The wizard generates callback interface that a user implements. Implementing this interface is believed to be simpler and more versionable that implementing pure SAX intefaces directly. The higher level generated handler interface is well defined, type safe and is compatible for compatible DTDs. The concept also saves the user from writing complex dispatch code.

The generated code depends on DTD availability and therefore does not support namespaces.

Term: Parslet stay for a set of data convertors.

### Input

- DTD representing static vocabulary to be recognized
- DTD mapping allowing to define mapping between the vocabulary and a code. Mapping key is and element name.
- JAXP version - version of JAXP to be used in generated methods
- SAX version - version of SAX parser to be used (depends on JAXP version)
- Output file names where generated code will be placed. There are 1-2 interfaces, 1 recognizer file and empty implementations files.

A user will customize all above using several steps wizard. The logical steps are provided bellow.

#### DTD to Method Mapping Step

Four types of element declarations are recognized:

- Data element representing (#PCDATA). It represents a data holder.
- Empty element representing EMPTY. It represents a data holder.
- Mixed element representing mixed content. It represents a data holder or a container or both.
- Container element allowing just another elements. It represents a container.

A data holder can be mapped into a handling method taking actual data and meta-data where the actual data can be a result of parsing by a parslet. It can be also ignored.

A container can be mapped into delimiter methods taking meta-data. It can be also ignored.

The generator detects all DTD declarations and fills a mapping table.

It maps data holders into `handle_elementname(Object data, Attributes meta)` event methods using no parslet.

It maps containers into `start_elementname(Attributes meta)` and `end_elementname(Attributes meta)`.

#### Data Holders to Parslet Mapping Step

It could constitute next optional step, possibly let a user disable the parslet support at all (e.g. for Schema compatible parsers in future). A parslet accepts names on Java method names that will perform the conversion. Derending on return type the generator tries to guess an implementation. Every parslet is generated as `returnTYpe parsetMethodName(String data) throws SAXException` method.

#### Versions Step

JAXP and SAX versions compatibility is stated in following matrix.

SAX\JAXP | 1.0 | 1.1
1.0 | OK | OK
2.0 | not possible | OK

#### Output Destination Step

Generated files are placed into current package. Suggested file names can be modified by a user. Generator left intact users implemetation files if they exist. It replaces content of generated files leaving a backup copy of originals.

### Output

A code generated according the input. Files to be implemented are opened in editor.

Generator generates output files overwriting files that are not supposed to be modified by user. Anyway it keep a backup copy of rewritten files. Files to be automatically overwritten are parser, handler interface and parslet interface, these content is driven by the DTD file.

### Wizard Reentrance

Generator stores last customization done by user to a well known file. The file name is derived from DTD file name. On subsequent start is tries to locate this file and reuse it as much as possible (it depends on level od DTD changes). This mechanism also allows a user to design mappings by creating the settings file by hand. It is an XML document following "-//XML Module//DTD SAX Bindings 1.0//EN" DTD. On other hand by deleting this file user can simply remove wrong settings and let the generator generate defaults.

## DOM Scanner

It generates a DOM implematation independent visitor (a pattern) of passed DTD.