Invoking the Generator with a WSDL File

HydraExpress Web Service Development Guide
Rogue Wave web site: Home Page | Main Documentation Page

20.4 Invoking the Generator with a WSDL File

Given the command

<prompt> rwsfgen -projectname MyProject MyService.wsdl

HydraExpress generates a project named MyProject containing server and client side code, and creates a code generation directory MyProject, where it places all the generated files.

Section 20.4.1 illustrates the architecture of the generated classes. Section 20.4.2 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. It also produces errors and warnings for unrecognized or unsupported features in the WSDL file. Errors halt the generation process; warnings are treated as diagnostic messages only, so the generator attempts to produce code from any WSDL document, regardless of whether it is valid. Providing an invalid document to the generator may result in code that does not compile.

Errors halt the code generation process by default. You may override this with the switch
-nohaltonerror; however using this switch may result in code generation errors or uncompilable code.

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."

20.4.1 Architecture of the Generated Classes

This section includes UML diagrams of the interfaces that HydraExpress creates.

Additional files may be generated, depending on your project. For instance, if you use a
-standalone option when generating code, a special standalone server is generated; or if your WSDL contains the message pattern notification, notification classes are generated.

20.4.1.1 Server Classes

Figure 13: Generated server classes

The server-side class architecture shown above supports the common Web service request-response message pattern and the one-way, client-to-server message pattern.

The servlet class, rwsf:WebServiceServlet, is in the Web Services library. By default, the servlet uses the HTTP transport configured in server-transports.xml.

The servlet processes service messages through the message handlers configured in <serviceName>handlers.xml. The above diagram shows the minimum number of such handlers, <binding>Skeleton, which handles the SOAP binding, and <portType>Imp, which is the server implementation containing the business logic.

Both the binding skeleton and the service implementation derive from base classes, the library class rwsf::ServiceSkeletonBase for the binding, and the generated class <portType>Base for the implementation. By default, HydraExpress generates a sample implementation, <portType>Imp. You can implement your service by editing this file, or you can derive your own implementation class from <portType>Base. If you use a different name for your own derived class, there are a few changes you need to make to the configuration. See Section 8.2.2, "Using the Server Implementation."

20.4.1.2 Client Classes

Figure 14: Generated Client Classes

HydraExpress generates a client proxy class, <binding>Proxy, which contains the service operation methods, and a sample client implementation, <port>Client. The implementation obtains an instance of the proxy by calling one of several make() convenience functions in the proxy class. The make() methods handle the details of obtaining a rwsf::Transport instance of the correct type for communicating with the server. The transports in HydraExpress are message handlers, derived from rwsf::MessageHandler.

20.4.2 Generated Files

Table 10 shows the output files the HydraExpress code generator would produce for the command line

<prompt> rwsfgen -projectname MyProject MyService.wsdl

where MyProject is the project name, and therefore MyProject is the code generation directory into which HydraExpress will place the generated code.

The output listing assumes

that the service name, service binding, and service port type are all specified in the WSDL as "MyService".
that the WSDL does not include notification or solicit-response message patterns. If your WSDL contains these patterns, the output results in additional files not listed here. For more information on notification, see Chapter 9, "Introduction to Message Patterns."For more information on solicit-response, see Section 9.2.5, "The Solicit-Response Pattern."

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 Section 20.7

Table 10: Files generated by HydraExpress with default options

Directory	Files	Description
MyProject/	MyProject.xml	The project file defining all project elements (options, configurations, schemas, WSDLs, etc.). See Section 21.2, "The Project File."
	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 down to all makefiles. Overwrite-protected.
	MyProject.sln	MSVC 7 or 8 solution files. Generated for Windows platforms, depending on value of `-projectversion` flag.
app/	makefile makefile_debug	Makefiles. Calls all makefiles in subdirectories. Overwrite-protected.
/client	<MyService>Client.cpp	Sample client implementation using the client proxy. Overwrite-protected.
	makefile makefile_debug	Makefiles. Builds contents of `app/client` directory. Overwrite-protected.
	<MyService>Client.vcproj	MSVC 7 or 8 project files generated for Windows platforms.
/server	<MyService>Imp.cpp <MyService>Imp.h	Sample service implementation and header files. Derives from MyService Base. You can implement your service by implementing the methods of this class, or you can derive your own class from MyServiceBase. Overwrite-protected.
	makefile makefile_debug	Makefiles. Builds contents of `app/server` directory. Overwrite-protected.
	<MyService>Service.vcproj	MSVC 7 or 8 project files generated for Windows platforms.
/data	<MySchema>_main.cpp	Generated sample implementation for marshaling and unmarshaling XML. Generated only if the WSDL contains or references a schema. Overwrite-protected.
	makefile makefile_debug	Makefiles. Builds contents of `app/data` directory. Overwrite-protected.
	MySchema_main.vcproj	MSVC 7 or 8 project files generated for Windows platforms.
codegen/	makefile makefile_debug	Makefiles. Builds contents of `codegen/`directory. Overwrite-protected.
/client	MyServiceProxy.cpp	Implementation file for the generated client proxy class.
	makefile makefile_debug	Makefiles. Builds contents of `codegen/client` directory. Overwrite-protected.
	MyService.vcproj	MSVC 7 or 8 project files generated for Windows platforms.
/common	[fault_message.cpp]	Optional common directory contains source files common to both client and server, generally faults.
	makefile makefile_debug	Makefiles. Builds contents of `codegen/common` directory. Overwrite-protected.
	project-<name>_sxcommonLibrary.vcproj	MSVC 7 or 8 project files generated for Windows platforms.
/etc	[marshallers.xml]	Contains marshalling configuration file for any generated datatypes. Generated only if datatype classes are generated.
/server	<MyService>Skeleton.cpp <MyService>Base.cpp	Implementation files for the class that handles messaging and the base class for the server-side implementation.
	makefile makefile_debug	Makefiles. Builds contents of `codegen/server` directory. Overwrite-protected.
	<MyService>Service.vcproj	MSVC 7 or 8 project files generated for Windows platforms.
/data	makefile makefile_debug	Makefiles. Builds contents of `codegen/data` directory. Overwrite-protected
	[<MySchema>Statics.cpp]	Static element names class, generated when the property `-noTopLevelClasses` is specified.
	<datatype>_1.vcproj	MSVC 7 or 8 project files generated for Windows platforms.
/<namespace>	<Datatype>.cpp <Datatype>Marshal.cpp	The implementation file(s) and marshaler classes for all datatypes generated, if the file input to the generator is or contains a schema.
conf/	server-transports.xml client-transports.xml	Configuration files for: 1. Server and client transports.
	<MyService>_handlers.xml	2. Server-side handlers to support handler chaining and configuration.
	client-handlers.xml	3. Client-side handlers containing default client logger.
	<MyService>_objects.xml	4. All named objects required by this service. These are registered and created when the container is started.
	<MyService>_web.xml	5. Service descriptor XML file for the service.
	makefile makefile_debug	Deployment makefiles. Overwrite-protected.
docs/	index.html	The generated documentation. Use `index.html` as the entry point to all docs contained in the docs subdirectories.
include/		Header files, as follows:
/MyProject		subdirectory `<projectname>`
	<MyService>Proxy.h	Client proxy class
	<MyService>Skeleton.h	Class that handles messaging
	<MyService>Base.h	Base class for the server-side implementation.
	<datatype>_typesConverter.h	Conversion utility class (converts the simple types defined in the datamap to and from the underlying string class, *string*).
	[<fault>_message.h]	Fault class headers (optional)
	[<MySchema>Statics.h]	static element names class, generated when the property `-noTopLevelClasses` is specified.
/<namespace>	<datatype>.h	Datatype header file, if there was a datatype generated.
	<datatype>Marshal.h	Datatype marshaling class, if there was a datatype generated.

20.4.2.1 HTML Documentation

HTML API documentation is generated for each client and server class, the datatype classes, and all sample implementations. To view the HTML API documentation, open the index.html file in the docs directory. For documentation about the non-generated classes on which these generated classes may depend, see the HydraExpress C++ API Reference Guide.

20.4.2.2 Sample Application Files

If the WSDL defines XML Schema types, a data subdirectory under the directories apps, codegen, docs, and include contain generated files and documentation for the C++ XML binding classes.

The generator may produce other support files. The generator uses the support files while generating code, but the files are not required for compiling and running the generated code. These files can be preserved with the -noclean option.

20.4.2.3 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.

20.4.2.4 MSVC Project Files

For Windows users with Microsoft Visual C++, HydraExpress also generates project files and solutions. Files are generated for MSVC 7.1 by default. You can change the default behavior by specifying the -projectversion flag when you generate the project, as described in Table 11.

© Copyright Rogue Wave Software, Inc. All Rights Reserved. All Rights Reserved. Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. HydraExpress is a trademark of Rogue Wave Software, Inc. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.