General
How GnAST works
General
- Where do I find the latest version of this document?
-
The latest version can be found at http://czt.sourceforge.net/dev/gnast/faq.html .
- What is GnAST?
-
GnAST is a source code generator that generates Java interfaces and classes from a W3C XML Schema. It was designed to generate an annotated syntax tree (AST) for standard Z from the schema describing ZML, an XML markup for the Z specification language. But GnAST can also be used to generate ASTs for Schemas describing Z extensions, and even Schemas that have nothing to do with the Z language.
- What does the name GnAST mean?
-
GnAST is short for GeNerate AST.
How GnAST works
- How is GnAST different from other source code generators like those included in Castor and JAXB?
-
Castor and JAXB are XML data binding frameworks that aim at providing a direct mapping between an XML document and Java objects as well as methods to translate between the two.
The code generated by GnAST was not designed to serve as an XML data binding framework. The purpose of GnAST is to generate user-friendly interfaces and a set of implementing classes for the objects described in the Schema. Even though the Java objects do contain the data of the corresponding XML document, the interfaces and classes are not designed to directly map to the XML document. They may, for instance, contain additional data or methods.
An important feature of the classes generated by GnAST is that they support the extensive use of the visitor design pattern. This enables the user of these classes to easily add functionality without changing the classes itself. Furthermore, a user is free to use the generated implementing classes or to provide its own implementation.
GnAST was born since none of the data binding frameworks provided all the required features for our classes. Meanwhile the tools have matured and its probably possible to customise at least some of them appropriately.
- Which XML Schema structures and features are supported by GnAST?
-
GnAST supports only a very limited subset of the rich XML Schema language. Supported Schema structures include:
- Extensions of complex types
- ...
- Restriction of complex types
- ...
- How should I design my Schema if I want GnAST to be able to handle it?
-
Use global Schema elements and the substitutionGroup attribute a lot. Since the class hierarchy generated by GnAST is derived from the substitution group hierarchy of the global Schema elements, you should use these structures extensively.
Try to avoid using the type attribute for local Schema elements. GnAST handles the type attribute of local Schema elements as strings. It does not check whether these strings refer to existing classes, or whether they are valid Java class names or Java types. However, you may provide a mapping file, this is basically a substitution which is applied before the code is generated. You could, for instance, provide a substitution from the Schema type xs:string to the Java type String, or from Foo to MyClass. But be aware that it is your responsibility to make sure that the results of the substitution really represent the type defined in the Schema.
Do not use names that are already used in an included Schema, even though they are in a different namespace. The reason for this is, that the object factory does contain a method createFoo() for each Foo element, and the object factory has to be extended.