Support for schema evolution using substitution groups

New examples: hybrid/evolution/ignore and hybrid/evolution/passthrough.

1 files changed, 104 insertions, 0 deletions

diff --git a/examples/cxx/hybrid/evolution/passthrough/README b/examples/cxx/hybrid/evolution/passthrough/README
new file mode 100644
index 0000000..a4a3803
--- /dev/null
+++ b/examples/cxx/hybrid/evolution/passthrough/README
@@ -0,0 +1,104 @@
+This example shows how to handle schema evolution using substitution groups.
+The general idea is as follows: the initial version of the schema defines
+extension points using the XML Schema substitution group mechanism. The
+subsequent versions of the schema add new elements to the substitution
+groups. The goal here is for applications that were built using earlier
+versions of the schema to be able to handle documents corresponding to the
+newer versions without validation errors or any other failures. This example
+shows how to pass the unknown content through parsing and serialization so
+that the output XML contains all the unknown elements. The 'ignore' example
+shows how to ignore such unknown elements. 
+
+This example uses XML Schema polymorphism in the form of substitution groups.
+If you are not familiar with how to work with polymorphic object models,
+refer to the C++/Hybrid Mapping Getting Started Guide as well as the 
+'polymorphism' example in the examples/cxx/hybrid/ directory.
+
+This example also customizes a generated object model type as well as parser
+and serializer implementations. If you are not familiar with the customization
+mechanisms, refer to the C++/Hybrid Mapping Getting Started Guide as well as
+the examples in the examples/cxx/hybrid/custom/ directory.
+
+The example consists of the following files:
+
+transform.xsd
+  The initial version of the schema that describes simple transformations,
+  such as move and rotate. The schema makes it possible to add new
+  transformations in subsequent versions of the schema. It also defines a
+  special unknown_type type which is used to handle unknown transformations.
+  Our example is built using this schema.
+
+transform-v2.xsd
+  The second version of the schema which adds the scale transformation. This
+  schema is provided as an example.
+
+transform.xml
+  Sample XML document corresponding to the second version of the schema. In
+  particular, it contains the scale transformation which is unknown in
+  transform.xsd.
+
+transform.hxx
+transform.cxx
+
+transform-pskel.hxx
+transform-pskel.cxx
+transform-pimpl.hxx
+transform-pimpl.cxx
+
+transform-sskel.hxx
+transform-sskel.cxx
+transform-simpl.hxx
+transform-simpl.cxx
+  Object model (the first pair of files), parser skeletons (the second pair),
+  parser implementations (the third pair), serializer skeletons (the fourth
+  pair), and serializer implementations (the fifth pair). These files are
+  generated by the XSD/e compiler from transform.xsd. The --generate-parser,
+  --generate-serializer, and --generate-aggregate options were used to request
+  the generation of the parsing and serialization code. The 
+  --generate-polymorphic option was used to request the generation of the
+  polymorphism-aware code. The --custom-type, --custom-parser, and 
+  --custom-serializer options were used to customize the object model class
+  as well as the parser and serializer implementations for the unknown_type
+  XML Schema type.
+
+xml.hxx
+xml.ixx
+xml.cxx
+  Simple in-memory representation for raw XML. It is used to store the content
+  of unknown transformations.
+
+unknown-type.hxx
+unknown-type.cxx
+  Custom unknown_type class. It uses the generated version as a base and adds
+  members that store the raw XML representation of an unknown transformation
+  as well as the parsed element name and namespace from the substitution group.
+
+unknown-type-pimpl.hxx
+unknown-type-pimpl.cxx
+  Custom unknown_type parser implementation. It uses the implementation
+  generated by the XSD/e compiler as a base and overrides the raw XML
+  callbacks to parse the unknown content and store it in the customized
+  unknown_type class.
+
+unknown-type-simpl.hxx
+unknown-type-simpl.cxx
+  Custom unknown_type serializer implementation. It uses the implementation
+  generated by the XSD/e compiler as a base and overrides the raw XML
+  callbacks to serialize the unknown content stored in the customized
+  unknown_type class.
+
+driver.cxx
+  Driver for the example. It first sets the substitution map callbacks that
+  are used to alter the default element mapping in the parser and serializer.
+  The driver then calls the parser that constructs the object model from the
+  input XML file. It then prints the content of the object model to STDERR.
+  Finally, the driver calls the serializer to serialize the object model
+  back to XML.
+
+To run the example on the sample XML instance document simply execute:
+
+$ ./driver transform.xml
+
+The example reads from STDIN if input file is not specified:
+
+$ ./driver <transform.xml