Copyright © 2000, Intalio, Inc
CASTOR XML
SOURCE CODE GENERATOR
USER DOCUMENT
Author: Arnaud Blandin [blandin@intalio.com]
Contributions:
Keith Visco [kvisco@intalio.com]
Revision: July 11, 2001
7/11/2001
Copyright © 2000, Intalio, Inc
2
1 Abstract....................................................................................................................................................3
1 Why a Source Code Generator?...................................................................................................4
1.1 XML Data Binding........................................................................................................................4
1.2 The role of the source generator...........................................................................................5
2 Usage, options & XML Schema support..................................................................................6
2.1 Usage...................................................................................................................................................6
2.2 Source Generator Options........................................................................................................6
2.2.1 Command Line Options........................................................................................................7
2.2.2 Collection types:........................................................................................................................8
2.2.3 Advanced options....................................................................................................................8
2.3 XML Schema support................................................................................................................15
2.3.1 Built-in types...........................................................................................................................16
2.3.2 Structure.....................................................................................................................................27
2.4 Requirements................................................................................................................................40
2.4.1 Castor packages......................................................................................................................40
2.4.2 External libraries...................................................................................................................40
3 Example..................................................................................................................................................41
3.1 The schema file............................................................................................................................41
3.2 The generated code....................................................................................................................48
4 FAQ 55
5 Open Issues: possible improvements....................................................................................61
6 Glossary..................................................................................................................................................62
7 References.............................................................................................................................................63
7/11/2001
Copyright © 2000, Intalio, Inc
3
1 Abstract
As a complete XML
1
data binding framework, Castor XML offers the ability to
generate Java code from an XML Schema.
The aim of this document is to describe the Castor XML Source Code Generator,
including the main options and features, as well as to illustrate the mechanism
used to generate java classes with a simple example. Open issues of the project are
also discussed.
1: all bold names (except in section 2.3) are defined in the glossary.
7/11/2001
Copyright © 2000, Intalio, Inc
4
1 Why a Source Code Generator?
1.1XML Data Binding
Many current applications which manipulates XML documents rely on XML
Schemas which define the structure, the content and even the meaning of these
XML documents.
In order to deal with the XML ‘constraints’ defined in the schema, applications
need some tools to create and manipulate XML documents that are instances of the
given XML Schema.
Such tools might be written using the SAX API or the DOM API, however these
approaches are more focused on the structure of an XML document than the data
itself.
Moreover all data in these APIs are treated as strings and must likely need to be
cast to an appropriate data type.
It would be much easier if these applications could map directly an XML document
to its in-memory object representation that contains all the information provided
by the XML Schema, this is what we call XML data binding.
7/11/2001
Copyright © 2000, Intalio, Inc
5
1.2The role of the source generator
To represent the data model of an XML document in memory, developers need to
hard-code the description of the XML document. They need to describe the
structure and the data of the document provided by the XML Schema.
Sometimes it could be easy when you only need to map a String or a Boolean, you
can find the exact mapping in any Object Oriented language but when it is time to
describe a more complex structure with some inner XML Schema types it can
become very tedious and complex.
The aim of the source generator is to provide the necessary code to describe XML
instances of a specific XML Schema with the proper fields and access methods.
To sum up, we can draw a parallel between the relations XML Schema-XML and
Class-Object: an XML document is an instance of an XML Schema and an Object is
an instance of a Class. Thus to represent an XML document as an Object in
memory, we need to provide the Class that describes this object.
The Source Code Generator is merely generating the code for this class.
The Castor XML Source Code Generator – from now on referred to the Source
Generator –generates Java source code from a W3C XML Schema. The generated
source includes an object model of the schema as well as the necessary Class
Descriptors used by the marshalling framework to obtain information about the
generated classes.
