From 0bce70a0e483294b83b8bf9d5468838a63405612 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Sun, 8 Mar 2009 17:23:30 +0200 Subject: Add support for binary representations xsde/cxx/hybrid/insertion-*: insertion operators generator xsde/cxx/hybrid/extraction-*: extraction operators generator libxsde/xsde/cxx/hybrid/cdr/: CDR support code libxsde/xsde/cxx/hybrid/xdr/: XDR support code tests/cxx/hybrid/binary/: new tests examples/cxx/hybrid/binary/: new examples documentation/cxx/hybrid/guide/: new chapter --- documentation/cxx/hybrid/guide/index.xhtml | 289 +++++++++++++++++++++++++++++ documentation/xsde.1 | 28 +++ documentation/xsde.xhtml | 22 +++ 3 files changed, 339 insertions(+) (limited to 'documentation') diff --git a/documentation/cxx/hybrid/guide/index.xhtml b/documentation/cxx/hybrid/guide/index.xhtml index b555009..9a95473 100644 --- a/documentation/cxx/hybrid/guide/index.xhtml +++ b/documentation/cxx/hybrid/guide/index.xhtml @@ -303,6 +303,16 @@ + + 7Binary Representation + + + + +
7.1CDR (Common Data Representation)
7.2XDR (eXternal Data Representation)
7.3Custom Representations
+ + + @@ -398,6 +408,17 @@ that would otherwise not fit into memory.

+

Besides reading from and writing to XML, the C++/Hybrid mapping + also supports saving the object model to and loading it from a + number of predefined as well as custom binary formats. Binary + representations contain only the data without any meta information + or markup. Consequently, saving to and loading from a binary + format can be an order of magnitude faster as well as result + in a much smaller footprint compared to parsing and serializing + the same data in XML. Furthermore, the resulting representation + is normally several times smaller than the equivalent XML + representation.

+

The Embedded C++/Hybrid mapping was specifically designed and optimized for mobile and embedded systems where hardware constraints require high efficiency and economical use of @@ -5090,6 +5111,274 @@ age: 25 + + +

7 Binary Representation

+ +

Besides reading from and writing to XML, the C++/Hybrid mapping + also allows you to save the object model to and load it from a + number of predefined as well as custom data representation + formats. The predefined binary formats are CDR (Common Data + Representation) and XDR (eXternal Data Representation). A + custom format can easily be supported by providing + insertion and extraction operators for basic types.

+ +

Binary representations contain only the data without any meta + information or markup. Consequently, saving to and loading + from a binary representation can be an order of magnitude + faster as well as result in a much smaller footprint compared + to parsing and serializing the same data in XML. Furthermore, + the resulting representation is normally several times smaller + than the equivalent XML representation. These properties make a + binary representation ideal for internal data exchange and storage. + A typical application that uses this facility stores the data and + communicates within the system using a binary format and reads/writes + the data in XML when communicating with the outside world.

+ +

In order to request the generation of insertion and extraction + operators for a specific predefined or custom data representation + stream, you will need to use the --generate-insertion + and --generate-extraction compiler options. See the + XSD/e + Compiler Command Line Manual for more information.

+ +

The XSD/e runtime provides implementations of the base insertion + and extraction operators for the ACE (Adaptive Communication + Environment) CDR streams and the XDR API. The XDR API is available + out of the box on most POSIX systems as part of Sun RPC. On other + platforms you may need to install a third-party library which + provides the XDR API. + + The XSD/e compiler recognizes two special argument values to the + --generate-insertion and --generate-extraction + options: CDR and XDR. When one of these + arguments is specified, the corresponding implementation from the + XSD/e runtime is automatically used. The following two sections + describe each of these two formats in more detail. It is also + possible to add support for saving the object model to and loading + it from custom data representation formats as discussed in the + last section of this chapter.

+ +

The saving of the object model types to a representation stream + is implemented with stream insertion operators + (operator<<). Similarly, loading of the object + model from a representation stream is implemented with stream + extraction operators (operator>>). The insertion + and extraction operators for the built-in XML Schema types as + well as the sequence templates are provided by the stream + implementation (that is, by the XSD/e runtime in case of CDR and + XDR and by you for custom formats). The XSD/e compiler automatically + generates insertion and extraction operators for the generated object + model types.

+ +

When C++ exceptions are enabled (Section 3.3, "C++ + Exceptions"), the signatures of the insertion and extraction + operators are as follows:

+ + 
+void
+operator<< (ostream&, const type&);
+
+void
+operator>> (istream&, type&);
+
+ +

The insertion and extraction errors are indicated by throwing + stream-specific exceptions. When C++ exceptions are disabled, + the signatures of the insertion and extraction operators are + as follows:

+ + 
+bool
+operator<< (ostream&, const type&);
+
+bool
+operator>> (istream&, type&);
+
+ +

In this case the insertion and extraction operators return + true if the operation was successful and + false otherwise. The stream object may + provide additional error information.

+ + +

7.1 CDR (Common Data Representation)

+ +

When you request the generation of CDR stream insertion and extraction + operators, the ocdrstream and icdrstream + types are defined in the xml_schema namespace. Additionally, + if C++ exceptions are enabled, the cdr_exception exception + is also defined in xml_schema. The icdrstream + and ocdrstream types are simple wrappers for the + ACE_InputCDR and ACE_OutputCDR streams. The following code fragment + shows how we can use these types when C++ exceptions are enabled:

+ + 
+try
+{
+  const type& x = ... // Object model.
+
+  // Save to a CDR stream.
+  //
+  ACE_OutputCDR ace_ocdr;
+  xml_schema::ocdrstream ocdr (ace_ocdr);
+
+  ocdr << x;
+
+  // Load from a CDR stream.
+  //
+  ACE_InputCDR ace_icdr (buf, size);
+  xml_schema::icdrstream icdr (ace_icdr);
+
+  type copy;
+  icdr >> copy;
+}
+catch (const xml_schema::cdr_exception&)
+{
+  cerr << "CDR operation failed" << endl;
+}
+
+ +

The same code fragment but when C++ exceptions are disabled:

+ + 
+const type& x = ... // Object model.
+
+// Save to a CDR stream.
+//
+ACE_OutputCDR ace_ocdr;
+xml_schema::ocdrstream ocdr (ace_ocdr);
+
+if (!(ocdr << x))
+{
+  cerr << "CDR operation failed" << endl;
+}
+
+// Load from a CDR stream.
+//
+ACE_InputCDR ace_icdr (buf, size);
+xml_schema::icdrstream icdr (ace_icdr);
+
+type copy;
+
+if (!(icdr >> copy))
+{
+  cerr << "CDR operation failed" << endl;
+}
+
+ +

The cdr example which can be found in the + examples/cxx/hybrid/binary/ directory of the XSD/e + distribution includes complete source code that shows how to + save the object model to and load it from the CDR format.

+ +

7.2 XDR (eXternal Data Representation)

+ +

When you request the generation of XDR stream insertion and extraction + operators, the oxdrstream and xcdrstream + types are defined in the xml_schema namespace. Additionally, + if C++ exceptions are enabled, the xdr_exception exception + is also defined in xml_schema. The ixdrstream + and oxdrstream types are simple wrappers for the XDR + API. The following code fragment shows how we can use these types + when C++ exceptions are enabled:

+ + 
+try
+{
+  const type& x = ... // Object model.
+
+  // Save to a XDR stream.
+  //
+  XDR xdr;
+  xdrrec_create (&xdr, ...);
+  xml_schema::oxdrstream oxdr (xdr);
+
+  oxdr << x;
+
+  // Load from a XDR stream.
+  //
+  xdrrec_create (&xdr, ...);
+  xml_schema::ixdrstream ixdr (xdr);
+
+  type copy;
+  ixdr >> copy;
+}
+catch (const xml_schema::xdr_exception&)
+{
+  cerr << "XDR operation failed" << endl;
+}
+
+ +

The same code fragment but when C++ exceptions are disabled:

+ + 
+const type& x = ... // Object model.
+
+// Save to a XDR stream.
+//
+XDR xdr;
+xdrrec_create (&xdr, ...);
+xml_schema::oxdrstream oxdr (xdr);
+
+if (!(oxdr << x))
+{
+  cerr << "XDR operation failed" << endl;
+}
+
+// Load from a XDR stream.
+//
+xdrrec_create (&xdr, ...);
+xml_schema::ixdrstream ixdr (xdr);
+
+type copy;
+
+if (!(ixdr >> copy))
+{
+  cerr << "XDR operation failed" << endl;
+}
+
+ +

The xdr example which can be found in the + examples/cxx/hybrid/binary/ directory of the XSD/e + distribution includes complete source code that shows how to + save the object model to and load it from the XDR format.

+ + +

7.3 Custom Representations

+ +

To add support for saving the object model to and loading it + from a custom format, you will need to perform the following + general steps:

+ +
    +
  1. Generate a header file corresponding to the XML Schema + namespace using the --generate-xml-schema + compiler option.
    2. + +
  2. Implement custom stream insertion and extraction operators + for the built-in XML Schema types and sequence templates. + Include the header file obtained in the previous step to + get definitions for these types.
    3. + +
  3. Compile your schemas with the --generate-insertion + and --generate-extraction options. The arguments + to these options will be your custom output and input stream + types, respectively. Use the --hxx-prologue + option to include the definitions for these stream types + into the generated code. Also use the + --extern-xml-schema option to include the + header file obtained in the first step instead of generating + the same code directly.
    4. +
+ +

The custom example which can be found in the + examples/cxx/hybrid/binary/ directory of the XSD/e + distribution includes complete source code that shows how to + save the object model to and load it from a custom format using + the raw binary representation as an example. You can use the + source code from this example as a base to implement support + for your own format.

diff --git a/documentation/xsde.1 b/documentation/xsde.1 index 1f72eef..79a9179 100644 --- a/documentation/xsde.1 +++ b/documentation/xsde.1 @@ -944,6 +944,34 @@ Suppress the generation of validation code in parser. .IP "\fB\--suppress-serializer-val\fR" Suppress the generation of validation code in serializer. +.IP "\fB\--generate-insertion \fIos\fR" +Generate data representation stream insertion operators for the +.I os +output stream type. Repeat this option to specify more than one stream +type. The special +.B CDR +and +.B XDR +arguments are recognized as ACE CDR and Sun RPC XDR stream types and the +corresponding stream wrappers provided by the XSD/e runtime are automatically +used. For custom stream types use the +.B --hxx-prologue* +options to include the necessary declarations. + +.IP "\fB\--generate-extraction \fIis\fR" +Generate data representation stream extraction operators for the +.I is +input stream type. Repeat this option to specify more than one stream +type. The special +.B CDR +and +.B XDR +arguments are recognized as ACE CDR and Sun RPC XDR stream types and the +corresponding stream wrappers provided by the XSD/e runtime are automatically +used. For custom stream types use the +.B --hxx-prologue* +options to include the necessary declarations. + .IP "\fB\--generate-forward\fR" Generate forward declaration file. diff --git a/documentation/xsde.xhtml b/documentation/xsde.xhtml index ac01b91..d07197b 100644 --- a/documentation/xsde.xhtml +++ b/documentation/xsde.xhtml @@ -816,6 +816,28 @@
--suppress-serializer-val
Suppress the generation of validation code in serializer.
+
--generate-insertion os
+
Generate data representation stream insertion operators for + the os output stream type. Repeat this + option to specify more than one stream type. The special + CDR and XDR arguments + are recognized as ACE CDR and Sun RPC XDR stream types and + the corresponding stream wrappers provided by the XSD/e runtime + are automatically used. For custom stream types use the + --hxx-prologue* options to include the + necessary declarations.
+ +
--generate-extraction is
+
Generate data representation stream extraction operators for + the is input stream type. Repeat this + option to specify more than one stream type. The special + CDR and XDR arguments + are recognized as ACE CDR and Sun RPC XDR stream types and + the corresponding stream wrappers provided by the XSD/e runtime + are automatically used. For custom stream types use the + --hxx-prologue* options to include the + necessary declarations.
+
--generate-forward
Generate forward declaration file.
-- cgit v1.1