This book describes how to use Caché XML tools.
Caché brings the power of objects to XML processing you can use objects as a direct representation of XML documents and vice versa. Because Caché includes a native object database, you can use such objects directly with a database. Furthermore, Caché provides tools for working with XML documents and DOMs (Document Object Model), even if these are not
related to any Caché classes.
This chapter discusses the following topics:
For an XML-enabled class, your data can be available in all the following forms:
Contained in class instances. Depending on the class, the data can also possibly be saved to disk, where it is available in all the same ways as other persistent classes.
Contained in XML documents, which could be files, streams, or other documents.
The following figure provides an overview of the tools that you use to convert your data among these forms:
class enables you to import a suitable XML document into a class instance. The source is typically a file or a stream. To use this class, you specify a correlation between a class name and an element contained in the XML document. The given element must have the structure that is expected by the corresponding class. Then you read the document, node by node. When you do so, the system creates in-memory instances of that class, containing the data found in the XML document. For information, see Importing XML into Caché Objects.
The Caché XML tools provide many ways to access data in and modify both XML documents and DOMs.
You can also use Caché XML tools to create and work with arbitrary XML that is, XML that does not map to any Caché class. To create an arbitrary XML document, use %XML.Writer
. This class provides methods for adding elements, adding attributes, adding namespace declarations, and so on.
To create an arbitrary DOM, use %XML.Document
. This class provides a class method that returns a DOM with a single empty node. Then use instance methods of that class to add nodes as needed.
The Caché XML tools provide several ways to access data in XML form. The following figure shows a summary:
For any well-formed XML document, you can use the following classes to work with data in that document:
The Caché XML tools also provide ways to modify data in XML form. The following figure shows a summary:
Caché XML Tools use the Caché SAX (Simple API for XML) Parser. This is a built-in SAX XML validating parser using the standard Xerces library. SAX is a parsing engine that provides complete XML validation and document parsing. Caché SAX communicates with a Caché process using a high-performance, in-process call-in mechanism. Using this parser, you can process XML documents using either the built-in Caché XML support or by providing your own custom SAX interface classes within Caché.
Caché XML support includes the following additional tools:
When you work with XML tools of any kind, there are at least three general points to consider:
When you export an XML document, you can specify the character encoding to use; otherwise, Cache chooses the encoding, depending on the destination:
For any XML document read by Caché, the XML declaration of the document should indicate the character encoding of that file, and the document should be encoded as declared. For example:
<?xml version="1.0" encoding="UTF-16"?>
However, if the character encoding is not declared in the document, Caché assumes the following:
When you work with an XML document, you must know the format to use when mapping the document to Caché classes. Similarly, when you create an XML document, you specify the document format to use when writing the document. The XML document formats are as follows:
Literal means that the document is a literal copy of the object instance. In most cases, you use literal format, even when working with SOAP.
Except where otherwise noted, the examples in the documentation use literal format.
The details are slightly different for SOAP 1.1 and SOAP 1.2.
The following subsections show the differences between these document formats.
The following sample shows an XML document in literal format:
<?xml version="1.0" encoding="UTF-8"?>
In contrast, the following example shows the same data in encoded format:
<?xml version="1.0" encoding="UTF-8"?>
<DoctorClass id="id2" xsi:type="DoctorClass">
<DoctorClass id="id3" xsi:type="DoctorClass">
<DoctorClass id="id8" xsi:type="DoctorClass">
<Address href="#id17" />
<DoctorClass href="#id8" />
<DoctorClass href="#id2" />
<DoctorClass href="#id3" />
<AddressClass id="id17" xsi:type="s_AddressClass">
Note the following differences in the encoded version:
The root element of the output includes declarations for the SOAP encoding namespace and other standard namespaces.
This document includes person, address, and doctor elements all at the same level. The address and doctor elements are listed with unique IDs that are used by the person elements that refer to them. Each object-valued property is treated this way.
The names of the top-level address and doctor elements are named the same as the respective classes
, rather than being named the same as the property that refers to them.
Encoded format does not include any attributes. The GroupID
property is mapped as an attribute in the Person
class. In literal format, this property is projected as an attribute. In the encoded version, however, the property is projected as an element.
Collections are treated differently. For example, the list element has the attribute ENC:arrayType
Each element has a value for the xsi:type
For SOAP 1.2, the encoded version is slightly different. To easily distinguish the versions, check the declaration for the SOAP encoding namespace:
The Caché SAX Parser is used whenever Caché reads an XML document, so it is useful to know its default behavior. Among other tasks, the parser does the following:
It verifies whether the XML document is well-formed.
It attempts to validate the document, using the given schema or DTD.
Here it is useful to remember that a schema can contain <import> and <include> elements that refer to other schemas. For example:
The validation fails unless these other schemas are available to the parser. Especially with WSDL
documents, it is sometimes necessary to download all the schemas and edit the primary schema to use the corrected locations.
It attempts to resolve all entities, including all external entities. (Other XML parsers do this as well.) This process can be time-consuming, depending on their locations. In particular, Xerces uses a network accessor to resolve some URLs, and the implementation uses blocking I/O. Consequently, there is no timeout and network fetches can hang in error conditions, which have been rare in practice.
Also, Xerces does not support https; that is, it cannot resolve entities that are at https locations.
Caché XML support follows these standards:
The Caché SAX Parser uses the standard Xerces-C++ library, which complies with the XML 1.0 recommendation. For a list of these standards, see http://xml.apache.org/xerces-c/
Caché provides two XSLT processors:
If you have enabled support for long string operations, an attribute can be larger than 32 KB. Otherwise, each attribute must be less than 32 KB. Also, Caché XML does not support, within one element, multiple attributes with the same name, each in a different namespace.