Invoking the Generator with an XML Schema
Given the command
<prompt> rwsfgen -projectname MyProject MySchema.xsd
the generator creates a project titled MyProject based on the schema MySchema.xsd and places it into a directory MyProject.
NOTE >> HydraExpress supports only file paths without spaces, so when naming your project, do not include spaces, since HydraExpress uses the project name as a basis for the name of the code generation directory.
“Architecture of the Generated Classes” illustrates the architecture of the generated classes.
“Generated Files” describes the generated output.
The generator creates a log file rwsfgen.log, located in the directory where the generator was invoked, listing all generated files. If you run the command again, HydraExpress regenerates only those files that need to be updated due to changes in the schema or generation options.
NOTE >> Be sure to back up any changes to the generated source code, such as added business logic, in a location outside the code generation directory. The files within the directory may be overwritten and changes lost, the next time code is generated.
HydraExpress creates several subdirectories containing the generated files, as well as a project file reflecting the various options used when generating the project. For more detail on the project file and the code generation directory, see
Chapter 21, “The Project File and Directory Structure.”Architecture of the Generated Classes
This section includes a UML diagram of the interfaces and sample applications generated by the schema compiler. (Additional internal and support files not included in the diagram are also generated, but these are for internal use only.)
The generator creates a C++ class for each complex type defined in the schema. Each of these classes is based on the handle/body idiom, as illustrated in
Figure 11 , and each one is derived from the library classes
rwsf::XmlBindingHandle and
rwsf::XmlBindingBody respectively.
These complex type classes are represented by the handle/body pair <complexType> and <complexType>Imp in the figure above. If the schema defines any top-level elements that are of type <complexType>, an XML binding for that element is created deriving from type <complexType>, shown by the handle/body pair <element name> and <element name>Imp.
The class <schema name>_main.cpp is a generated sample application to use the datatype classes, and is placed into the app/data directory. The file contains a main() method skeleton with comments.
A marshaler, <complextype>Marshal.cpp, is created for each complex type in the schema to provide marshaling functionality, and the file <schema name>Converter.cpp performs string conversions as necessary.
For more information on the generated XML bindings, see Chapter 2, “XML Binding Concepts,” in the HydraExpress XML Binding Development Guide.
Generated Files
Table 10 shows the output files HydraExpress would produce for the command line
<prompt> rwsfgen -projectname MyProject MySchema.xsd
where MyProject is the name of the project. MyProject is also the code generation directory into which HydraExpress places the generated code, and MySchema.xsd is the schema to compile.
The list below assumes that the schema file contains the complex type definitions TypeA and TypeB, in addition to the element definition, ElementA.
NOTE >> Files that are overwrite-protected will be generated with a “
.sample” extension if a file exists in the output directory of the same name. See
“Overwrite Protection” .
Table 10 – Generated files for an XML Schema
Directory | Files | Description |
MyProject/ | MyProject.xml | Project file defining all project elements. See “The Generated Project Directory.” |
| makefile
makefile_debug | Project-level makefiles. Calls all makefiles in subdirectories. Overwrite protected. |
| makefile.include | Include makefile. Contains all makefile compiler and linker options. Edits to this file cascade to all makefiles. Overwrite-protected. |
| MyProject.sln | MSVC solution file. Generated for Windows platforms. |
| deployRelease.bat
deployDebug.bat | Convenience debug and release deployment batch files generated for use with MSVC projects. |
app/ | makefile
makefile_debug | Makefiles for app directory.
Overwrite protected. |
/data | makefile
makefile_debug | Makefiles for data directory.
Overwrite protected. |
| <MySchema>_main.cpp or
<MySchema>_main.cpp.sample | Sample application file.
Overwrite protected. |
| <MySchema>_main.vcproj | MSVC project files generated for Windows platforms. |
bin | | Empty directory to contain .exe, .so, and .dll files, as well as Windows manifest files. |
codegen/ | makefile
makefile_debug | Makefiles for codegen directory. Overwrite protected. |
/data/ | makefile
makefile_debug | Makefiles for data directory. Overwrite protected. |
| [<MySchema>Statics.cpp] | Static element names class, generated when the property ‑noTopLevelClasses is specified. |
| <MySchema>Library.vcproj | MSVC project file generated for Windows platforms. |
/<namespace> | TypeA.cpp
TypeB.cpp
ElementA.cpp | Source files for the datatype classes sorted into separate namespace directories, if a namespace is specified. |
| TypeAMarshal.cpp
TypeBMarshal.cpp
ElementAMarshal.cpp | External marshaling classes for each datatype class. |
/etc/ | <MySchema>-manifest.xml | Manifest identifying marshalling classes for all generated datatypes. |
docs/ | index.html | HTML documentation files. |
include/ | | Header files, as follows: |
/<MyProject> | TypeAConverter.h
TypeBConverter.h
ElementAConverter.h | Subdirectories by <projectname>. Also includes conversion utility class header files (to convert the simple types defined in the datamap to and from the underlying string class, string) |
| [<MySchema>Statics.h] | Static element names class, generated when the property ‑noTopLevelClasses is specified. |
/<namespace> | TypeA.h
TypeB.h
ElementA.h
ElementAMarshal.h | Header files for the datatype classes sorted into separate namespace directories, if a namespace is specified. |
lib | | Empty directory to contain .lib or .so files after the project build. |
HTML Documentation
To view the HTML API documentation, open the index.html file, using the browser of your choice. For documentation about the non-generated classes on which these generated classes may depend, see the HydraExpress C++ API Reference Guide.
Sample Application Files
HydraExpress generates an implemented sample application named MySchema_main.cpp. This file is a simple template from which you can create an application that uses the generated XML binding.
C++ Makefiles
To help you build the C++ generated libraries and sample applications, HydraExpress also generates the following versions of makefiles:
• a debug version: makefile_debug
• a non-debug version: makefile
A project-level makefile is generated in the code generation directory. This makefile builds the entire project. Makefiles are also generated in the each subdirectory in the event that you wish to build individual directories. For more information on using the generated makefiles, or creating your own, see
Chapter 22, “Options for Compiling.”MSVC Project Files
For Windows users with Microsoft Visual C++, HydraExpress also generates project and solutions files for MSVC.
Issues with Large Complex Schemas
Large schemas can result in quite long generation times, and may also cause heap overflow in Java or create linking issues. To avoid these problems:
• Adjust your settings for the environment variable RW_JAVAOPT, which sends the specified options to Java at each invocation of the code generator By default, the generator sets RW_JAVAOPT to -Xmx512M, which sets the heap size to 512 MB. This heap size is sufficient for most large schemas, although some very large schemas may require an even higher value.
• Invoke rwsfgen with the -nohtml option. While the generated documentation is useful for understanding the generated code, its generation adds significantly to the total generation time for complex schemas.
• Generate code using the
-maxgentypes option (
“Generator Options” ) for schemas with more than 65,000 types. This option separates the generated types into several different libraries to avoid linker issues.
