Rogue Wave banner
Previous fileTop of DocumentContentsIndex pageNext file
HydraExpress Web Service Development Guide
Rogue Wave web site:  Home Page  |  Main Documentation Page

6.3 Complex Data

For WSDL files that include or import an XML schema defining complex types, the code generator creates C++ classes to represent each complex type with relevant accessors and mutators to access the data.

For detailed information on these generated datatype classes and how to marshal and unmarshal them or otherwise manipulate them, please see the HydraExpress XML Binding Development Guide. This section focuses only on how to work with this data in a HydraExpress Web service.

This discussion is based on the provided WeatherSummary example. This example is not discussed in detail in this section other than to observe the data. For more information on this example and on the message patterns it illustrates, please see Chapter 10, "Implementing Solicit-Response and Notification Services,".

Other examples that work with complex data are Fault and MIME. All examples are located at <installdir>\examples\webservices\.

6.3.1 The WSDL and Schema

A schema can be a standalone document (mySchema.xsd), or can be embedded in a WSDL file in a <types> element.

In this excerpt from the WeatherSummary.wsdl, the message weatherUpdate has a part, weatherData, whose type is a WeatherSummary, used in the one-way operation weatherUpdate. (The fact that the operation is one-way rather than the more common request-response is not relevant to this discussion. For more information on one-way operations, see Chapter 9.)

The type WeatherSummary is complex and must therefore be defined elsewhere in the WSDL in a types element, or in a referenced schema. The WeatherSummary.wsdl file embeds the schema rather than referencing an external file, like so:

Note that the WeatherSummary complex type contains four simple types, zipcode, windSpeed, sky, and temp.

6.3.2 The Generated Data Classes

To see the code generated for the WeatherSummary.wsdl, ensure that your environment is set up as discussed in Chapter 2, "Setup," in the HydraExpress User Guide, open a command prompt, and navigate to the directory <installdir>\examples\webservicesug\WeatherSummary.

The command:

generates code into a code generation directory WeatherSummaryExample. Because the HydraExpress project file example-project.xml points to a WSDL file that contains a schema, the generated project structure will include data subdirectories as well as a relevant namespace directory, as illustrated in Table 3.

In order to simplify this discussion, this table does not list the generated client and server classes, but only the datatype classes.

Table 3: Relevant files generated for WeatherSummary.wsdl

Directory Files Description
WeatherSummaryExample/ WeatherSummaryExample.xml Project file defining all project elements. See Section 21.3.
    app/ makefile
makefile_debug
Makefiles for app directory. Overwrite protected.
        /data WeatherSummary_types_main.cpp
WeatherSummary_types_main.vcproj
Sample application file.Overwrite protected.
MSVC project file (Windows only)
    codegen/ makefile
makefile_debug
Makefiles for codegen directory. Overwrite protected.
        /data/ makefile
makefile_debug
Makefiles for data directory.
Overwrite protected.
            /wsx WeatherSummary.cpp
WeatherSummaryMarshal.cpp
Source files for the datatype classes sorted into separate namespace directories
    docs/ index.html HTML documentation files
    include/    
        /WeatherSummaryExample subdirectory projectname
  WeatherSummary_typesConverter.h Conversion utility class header file (to convert the simple types defined in the datamap to and from the underlying string class, string)
            wsx WeatherSummary.h
WeatherSummaryMarshal.h
Header files for the datatype classes

The docs directory contains HTML documentation. Single-click access is provided through the index.html file in the docs directory.

The generator creates one data type class named WeatherSummary, based on the complexType's name attribute. The source file for class WeatherSummary is placed into the codegen\data\wsx directory, where wsx is the namespace. The data type header file is placed into the include\WeatherSummary\wsx directory where WeatherSummary is the project name.

Class WeatherSummary provides accessors to work with the data, and also includes unmarshal() methods that populate an instance of the class from a serialized WeatherSummary type element, and marshal() methods for converting an instance of the class to a serialized format. These methods pass the marshaling and unmarshaling logic to the generated external marshaling class, WeatherSummaryMarshal. This class contains the logic to unmarshal and marshal the data and is called by WeatherSummary's unmarshal() and marshal() methods. Unless you are customizing the marshaling and unmarshaling process in some way, you do not need to explicitly use the marshaling class.

The directory app\data contains the sample application for manipulating datatypes (Section 6.3.4) , and the directory include contains relevant include and header files.


Source code other than that in the app directory is not overwrite protected. You should never add business logic or make any other changes to the generated source code, as these changes will be lost the next time the code is generated.

6.3.3 Working with the Generated Data Classes in the Client and Server Implementations

Let's take a look at the service operation method in the generated client implementation, WeatherSummaryClient.cpp:

Note that the generated code simply creates an instance of the datatype class WeatherSummary. The provided client implementation instantiates a WeatherSummary object, then uses the generated mutators to set a value on each simple type contained in the object:

The server-side implementation simply calls the weatherNotification notification-style service (See Chapter 9 for an explanation of the notification message pattern) with the WeatherSummary object. We can look at the weatherNotification operation to understand how to work with the data in WeatherSummary. Here's the generated server implementation:

The provided notification implementation WeatherSummaryNotificationImp.cpp uses the generated accessors to retrieve each simple type's value:

6.3.4 The Data "main" Sample Application

HydraExpress generates a sample application that you can use if you need to manipulate the data or marshal and unmarshal your code. This application is called WeatherSummary_types_main.cpp and is located in the directory WeatherSummaryExample\app\data. Edit this file to replace the TODO items with your application logic.

The example WeatherSummary does not ship with an implemented sample main application, as its primary focus is to illustrate various aspects of developing Web services.

For examples that do include implemented main applications, see any example in the <installdir>\examples\xmlbinding directory.



Previous fileTop of DocumentContentsIndex pageNext file

Copyright © Rogue Wave Software, Inc. All Rights Reserved.

The Rogue Wave name and logo are registered trademarks of Rogue Wave Software, and HydraExpress is a trademark of Rogue Wave Software. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.