balxml_encoder

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage

Purpose

Provide an XML encoder utility.

Classes

• balxml::Encoder: XML encoder utility class

See also

balxml_decoder, balber_berencoder

Description

This component provides a class for encoding value-semantic objects in XML format. In particular, the balxml::Encoder class contains a parameterized encode function that encodes a specified value-semantic object into a specified stream. There are three overloaded versions of this function:

• writes to an bsl::streambuf
• writes to an bsl::ostream
• writes to an balxml::Formatter

The encode function encodes objects in XML format, which is a very useful format for debugging. For more efficient performance, a binary encoding (such as BER) should be used.

This component can be used with types supported by the bdlat framework. In particular, types generated by the bas_codegen.pl tool can be used.

Usage

The following snippets of code illustrate the usage of this component. Suppose we have an XML schema inside a file named employee.xsd:

<?xml version='1.0' encoding='UTF-8'?>
<xs:schema xmlns:xs='http://www.w3.org/2001/XMLSchema'
           xmlns:test='http://bloomberg.com/schemas/test'
           targetNamespace='http://bloomberg.com/schemas/test'
           elementFormDefault='unqualified'>
 
    <xs:complexType name='Address'>
        <xs:sequence>
            <xs:element name='street' type='xs:string'/>
            <xs:element name='city'   type='xs:string'/>
            <xs:element name='state'  type='xs:string'/>
        </xs:sequence>
    </xs:complexType>
 
    <xs:complexType name='Employee'>
        <xs:sequence>
            <xs:element name='name'        type='xs:string'/>
            <xs:element name='homeAddress' type='test:Address'/>
            <xs:element name='age'         type='xs:int'/>
        </xs:sequence>
    </xs:complexType>
</xs:schema>

Using the bas_codegen.pl tool, we generate C++ classes for this schema as follows:

$ bas_codegen.pl -m msg -p test employee.xsd

This tool will generate the header and implementation files for the test_messages components in the current directory.

Now suppose we wanted to encode information about a particular employee using XML encoding to the standard output, and using the PRETTY option for formatting the output. The following function will do this:

#include <test_messages.h>
 
#include <balxml_encoder.h>
#include <balxml_encodingstyle.h>
 
#include <bsl_iostream.h>
#include <bsl_sstream.h>
 
using namespace BloombergLP;
 
void usageExample()
{
    test::Employee bob;
 
    bob.name()                 = "Bob";
    bob.homeAddress().street() = "Some Street";
    bob.homeAddress().city()   = "Some City";
    bob.homeAddress().state()  = "Some State";
    bob.age()                  = 21;
 
    balxml::EncoderOptions options;
    options.setEncodingStyle(balxml::EncodingStyle::BAEXML_PRETTY);
 
    balxml::Encoder encoder(&options, &bsl::cerr, &bsl::cerr);
 
    const bsl::string EXPECTED_OUTPUT =
     "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\n"
     "<Employee xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">\n"
     "    <name>Bob</name>\n"
     "    <homeAddress>\n"
     "        <street>Some Street</street>\n"
     "        <city>Some City</city>\n"
     "        <state>Some State</state>\n"
     "    </homeAddress>\n"
     "    <age>21</age>\n"
     "</Employee>\n";
 
    bsl::ostringstream os;
    const int rc = encoder.encodeToStream(os, bob);
 
    assert(0 == rc);
    assert(EXPECTED_OUTPUT == os.str());
}