Automatic Character Conversion through a Customized Mapping

Web Service Development Guide : PART IV Extending your Applications : Chapter 19 Internationalizing Your Services : Automatic Character Conversion through a Customized Mapping

You may create a custom mapping that defines an automatic character conversion to convert string members to an alternate encoding. This section describes how to create or edit a HydraExpress project file to contain a special mapping in order to customize conversions in HydraExpress.

Generally, the use of a specialized mapping that sets up an automatic mechanism to convert string members to an alternate encoding will take care of all your custom conversion needs.

The basic steps for setting up a special mapping are:

• Create a special mapping to identify the character encoding of your choice and the conversion routine to use. This allows HydraExpress to perform conversions automatically while marshaling and unmarshaling.

• Add the mapping to a HydraExpress project file, and generate code.

That’s it. The International Components of Unicode (ICU) libraries are dynamically loaded at runtime when needed.

Create a Customized Mapping

The mappings element in a HydraExpress project file defines a mapping between each XML element and a C++ type to be used during unmarshaling. For more complete information on the required and optional parts of a <mappings> element of a HydraExpress project file, see “Creating Customized Mappings,” in the HydraExpress XML Binding Development Guide.

The mapping must provide three items:

• The C++ type

• The code to be used to convert that type to and from the basic string type used (either string or RWCString). If you don’t specify any particular conversion code or information, the default is UTF-8.

• The header file that provides the conversion code

The following HydraExpress project file maps XML Schema elements to C++ types and identifies two converters, one that converts from UTF-8 to the desired encoding, and one that converts back from the desired encoding to UTF-8.

<rwsf-codegen-project>

...

</options>

<type xsdType="string" cppType="std::string"/> 1

<typeinfo cppType="std::string" include="international/myconverter.h"> 2

<fromString>convertToShiftJIS($value$)</fromString> 3

<toString>convertFromShiftJIS($value$)</toString> 4

<defaultValue>std::string("$value$")</defaultValue> 5

</typeinfo>

</mappings>

</rwsf-codegen-project>

//1 The attribute xsdtype maps the XML Schema type “string” to the desired C++ type, in this case the default “std::string”.

//2 Each cppType attribute under the type element requires the existence of a typeinfo element to define the C++ type that HydraExpress should generate. In this case, the typeinfo element contains an include attribute to specify the header file, myconverter.h, to perform the character conversion. See below for the possible contents of such a file.

Note that the mapping includes the path to the include file, given a project titled international.

//3 The fromString subelement provides the logic to convert the parent element type from a std::string instance to a user-specified type instance when unmarshaling. The $value$ parameter represents the std::string variable to be converted.

In this case, this line sets up a conversion from UTF-8 to ShiftJIS, provided by the referenced header file myconverter.h.

//4 The toString subelement provides the logic to convert the parent element type from a user-specified type instance to a string instance. The $value$ parameter represents the user-defined type instance to convert to a string.

In this case, this line sets up a conversion from ShiftJIS to UTF-8, provided by the referenced header file myconverter.h.

//5 Subelements <defaultValue> and <initialValue> required for mapping.

Following is one possible way to create a character converter. This example uses the conversion methods of utility class rwsf::XmlUtils.

// myconverter.h

#include <rwsf/core/XmlUtils.h> //1

#include <rwsf/core/CString.h>

#include <string>

class MyConverter

{

public:

static std::string convertFromShiftJIS(const std::string& str) { //2

return rwsf::XmlUtils::convertCharset(str, "Shift_JIS", "UTF-8");

}

static std::string convertToShiftJIS(const std::string& str) { //3

return rwsf::XmlUtils::convertCharset(str, "UTF-8", "Shift_JIS");

}

};

//1 Necessary includes

//2 Converts str from ShiftJIS to UTF-8.

//3 Converts str from UTF-8 to ShiftJIS.

Add the Mapping to a HydraExpress Project File and Generate Code

Copy the contents of your mappings element to an existing HydraExpress project file, or create a new HydraExpress project file; then generate code as always.

Adding the mappings to an existing HydraExpress Project File

If you have already generated code for a project and therefore have a generated HydraExpress project file, the easiest method is to add the mappings element’s contents directly to the HydraExpress project file. A default project file contains an empty mappings element.

For example, following is an excerpt of a generated HydraExpress project file based on an XML Schema charConversion.xsd:

<rwsf-codegen-project>

...

</options>

Insert your mappings here.

</mappings>

<files>

</files>

</rwsf-codegen-project>

Insert the contents of your mappings element into the empty mappings element, then generate code as always, providing the HydraExpress project file as an argument. For example,

prompt> rwsfgen CharConvert.xml

generates code into a directory CharConvert, based on the options in CharConvert.xml.

Creating a New HydraExpress Project File Containing the Mappings

If you have not yet generated code and therefore have no generated HydraExpress project file, you may create a simple HydraExpress project file containing only the mappings element. For example,

<rwsf-codegen-project>

...

</options>

Insert your mappings here.

</mappings>

</rwsf-codegen-project>

Then generate code, supplying both the HydraExpress project file containing the mappings, and the file to parse, such as

prompt> rwsfgen MyMapping.xml charConversion.xsd

NOTE >> When providing the generator more than one HydraExpress project file, be aware that the values in the last project file on the command line override any other provided values in the event of a conflict. See “Conflicting Options and Property Precedence” for more information on conflicting options.

A Look at the Generated Converter

Given a simple schema identifying just one element in charConversion.xsd, such as

<?xml version="1.0"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:element name="EncodedData">

<xs:complexType>

<xs:sequence>

<xs:element name="data" type="xs:string"/>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>

HydraExpress would generate a data class EncodedData, a converter utility class called CharConversionConverter.h, and a sample implementation, charConversion_main.cpp. (For a basic discussion on the various classes and code created by HydraExpress for an XML Schema, see “Invoking the Generator with an XML Schema.”

Let’s look at the rwsf::XmlUtils code that performs the conversion. The generated converter utility class CharConversionConverter.h contains methods used internally to convert the simple types defined in the default datamap to and from the underlying string class, string, used by HydraExpress. Generating code using the custom mapping in this example would result in the creation of an additional method in this class to convert your string, such as:

static std::string convertToString(const std::string& value,

std::string xsdType) {

return convertFromShiftJIS(value);

}

Note that this additional convertToString() method calls the convertCharset() method of rwsf::XmlUtils to perform the conversion.

When HydraExpress comes across a string in UTF-8, it will convert it to Shift-JIS automatically.