19.3 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.
19.3.1 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 Section 8.7, "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>
<option name='project-name' value='CharConvert'/>
...
</options>
<mappings>
<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
<initialValue></initialValue>
</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. |
19.3.2 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.
19.3.2.1 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>
<option name='project-name' value='CharConvert'/>
...
</options>
<mappings>
Insert your mappings here.
</mappings>
<files>
<xsd file='D:\HydraExpress\xmlbinding\charConversion.xsd'/>
</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.
19.3.2.2 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>
<option name='project-name' value='CharConvert'/>
...
</options>
<mappings>
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 |
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 Section 20.6.3 for more information on conflicting options.
19.3.2.3 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 Section 20.3, "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.
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.