Generating Code from Schema

XML Binding Development Guide : PART II Code Generation Examples : Chapter 3 Basic Purchase Order Example : Generating Code from Schema

Generating Code from Schema

For a given schema, HydraExpress generates C++ classes, HTML API documentation, and a sample application. HydraExpress also generates makefiles for building the C++ classes and the sample application. By default, HydraExpress places the output into a new code generation directory based on the provided project name.

Execute the Code Generator

To use the HydraExpress code generator with the Purchase Order schema, po.xsd:

1. Set up your environment, following the instructions in Chapter 2, “Setup,” in the HydraExpress User Guide.

2. Go to the directory installdir\examples\xmlbinding\basic\.

3. Invoke the HydraExpress code generator, using the command shown below.

rwsfgen example-project.xml

The HydraExpress project file example-project.xml directs the compiler rwsfgen to generate a project named basicExample, based on the po.xsd schema, with the whitespace=true option. The project name is required, provided either as a command line option (-projectname projectname) or in the HydraExpress project file.

NOTE >> The HydraExpress project file example-project.xml includes all options and files to be used as an argument to the code generator; so using this file results in exactly the same generated code as providing the options and files directly. For more information on the use of HydraExpress project files in the shipped examples, see “The Use of the HydraExpress Project File in Shipped Examples,” in the HydraExpress User Guide.

For complete information about the command-line options, see Generator Options,” in the HydraExpress Web Service Development Guide.

Code Generator Output

HydraExpress generates a C++ class for each complex type, top-level element, and sequence or choice defined in the XML Schema. Table 3 shows the schema definitions and the corresponding classes.

Table 1 – Classes generated for po.xsd schema
Schema definition	Type of definition	Resulting C++ Class
purchaseOrder	Top-level element	PurchaseOrder
PurchaseOrderType	Named complex type	PurchaseOrderType
USAddress	Named complex type	USAddress
Items	Named complex type	Items
item	Anonymous complex type	ItemsItem

The item anonymous complex type takes its name from the enclosing element, and the resulting class name reflects the fact that the element is nested within the Items complex type. For a complete description of how schema definitions are reflected in the generated code, see Chapter 8, “Mapping XML Schema to C++.”

The generator creates many additional files to support the XML data binding, including marshaling classes, makefiles, a sample application, and HTML documentation. For a complete listing, see “Generated Files”.

Files are separated into several subdirectories according to type, as shown below.

basicExample/

app/

data

codegen/

data

docs/

include/

<projectname>

<namespace>

The directory app contains the sample application, and the directory include contains relevant include and header files organized by project name and then by namespace, if the schema includes one. The directory codegen contains the source files for the datatype and marshaling classes, and it contents should not be modified. The docs directory contains HTML documentation, with single-click access provided through the index.html file.

For more information on the code generation directory structure, see “The Generated Project Directory,” in the HydraExpress Web Service Development Guide.

To use the sample application located in the directory basicExample\apps\data, add your application logic to it. For the purposes of this example, use the provided implemented application, po_main.cpp, located in the directory installdir\examples\xmlbinding\basic.

NOTE >>	Source code files other than those in the app directory are not overwrite protected. You should never add business logic or make any other changes to the generated source code as these changes are lost the next time the code is generated. 

Generated Files

Table 2 lists the generated files for the Basic example.

NOTE >>	Files that are overwrite-protected are generated with a “.sample” extension if a file exists in the code generation directory of the same name. See “Overwrite Protection,” in the HydraExpress Web Service Development Guide.

Table 2 – Generated files for an XML Schema
Directory	Files	Description
basicExample\	basicExample.xml	Project file, named according to the project name, and defining all project elements.
	makefile makefile_debug	Project-level makefiles. Calls all makefiles in subdirectories. Overwrite protected.
	basicExample.sln	Windows only. MSVC projects and solutions. See description in “Generator Options,” in the HydraExpress Web Service Development Guide.
	make.include	Master makefile configuration file. Contains all compiler and linker options. Edits to this file cascade to all makefiles, allowing you to make just one change instead of editing each makefile individually.
	deployDebug.bat deployRelease.bat	Convenience debug and release deployment batch files generated for use with MSVC projects.
app\	makefiles MSVC project files	Makefiles and MSVC project files for the app directory. Overwrite protected.
data\	po_main.cpp or po_main.cpp.sample	Sample application file.Overwrite protected.
codegen\	makefiles MSVC project files	Makefiles and MSVC project files for the codegen directory. Overwrite protected.
data\	makefiles MSVC project files	Makefiles and MSVC project files for the data directory. Overwrite protected.
po\	Items.cpp ItemsItem.cpp PurchaseOrder.cpp PurchaseOrderType.cpp USAddress.cpp	Source files for the datatype classes. Since the schema defines a namespace prefix, these files are placed in a subdirectory named for the prefix.
	[poStatics.cpp]	A poStatics.cpp class is generated only if the noTopLevelClasses property is specified at code generation. See “Working Without Top-Level Element Classes”
	ItemsMarshal.cpp ItemsItemMarshal.cpp PurchaseOrderTypeMarshal.cpp USAddressMarshal.cpp	Marshaling classes for each datatype class.
docs\	index.html	HTML documentation files.
include\ projectname\ namespaces\	Items.h ItemsItem.h PurchaseOrder.h PurchaseOrderType.h USAddress.h ItemsMarshal.h ItemsItemMarshal.h PurchaseOrderTypeMarshal.h USAddressMarshal.h	Header files for the datatype classes, organized in subdirectories based on project name and namespace. (If the schema defines a namespace prefix, these files are placed in a subdirectory named for the prefix.)
	[poStatics.h]	A poStatics.h header is generated only if the noTopLevelClasses property is specified at code generation.