Component balxml_encoder [Package balxml]

Provide an XML encoder utility. More...

Namespaces
namespace	balxml

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage

Purpose:

Provide an XML encoder utility.

Classes:

balxml::Encoder

XML encoder utility class

See also:

Component balxml_decoder, Component 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());
  }