Home|Management Portal|Index
Using Caché XML Tools
Introduction to Caché XML Tools
« »
   
Server:docs.intersystems.com
Instance:ENS20121
User:UnknownUser
 
-
Go to:
Search:    

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, without adding complex middleware or conversion technologies.
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:
Representing Object Data in XML
Some of the Caché XML tools are intended for use mainly with XML-enabled classes. To XML-enable a class, you add %XML.Adaptor to its superclass list. The %XML.Adaptor class enables you to represent instances of that class as XML documents. You add class parameters and property parameters to fine-tune the projection. Because there are so many options, an entire book is devoted to them: Projecting Objects to XML.
For an XML-enabled class, your data can be available in all the following forms:
The following figure provides an overview of the tools that you use to convert your data among these forms:
The %XML.Writer class enables you to create XML documents. The output destination is typically a file or a stream. You identify the objects to include in the output, and the system generates output based on the rules established within the class definitions. For information, see Writing XML Output from Caché Objects and Serving XML from Caché.”
The %XML.Reader 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.
A DOM is also a useful way to work with an XML document. You can use the %XML.Reader class to read an XML document and create a DOM that represents it. In this representation, the DOM is a series of nodes, and you navigate among them as needed. Specifically, you create an instance of %XML.Document, which represents the document itself and which contains the nodes. Then you use %XML.Node to examine and manipulate the nodes. You can use %XML.Writer to write the XML document again, if needed. For information, see Representing an XML Document as a DOM.
The Caché XML tools provide many ways to access data in and modify both XML documents and DOMs.
Creating Arbitrary XML
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.
Or use %XML.Reader to read an arbitrary XML document and then create a DOM from that document.
Accessing Data
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:
In Caché, a DOM is an instance of %XML.Document. This instance represents the document itself and contains the nodes. You use the properties and methods of this class to retrieve values from the DOM. You use %XML.Node to examine and manipulate the nodes. For information, see Representing an XML Document as a DOM.
Modifying XML
The Caché XML tools also provide ways to modify data in XML form. The following figure shows a summary:
For an XML document, you can use class methods in %XML.XSLT.Transformer to perform XSLT transformations and obtain a modified version of the document. See Performing XSLT Transformations.”
For a DOM, you can use methods of %XML.Document to modify the DOM. For example, you can add or remove elements or attributes.
The SAX Parser
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é.
For special applications, you can customize the Caché XML support. This includes an easy way to create custom XML server code; see Serving XML from Caché.” You can also create custom entity resolvers and content handlers; see Customizing How the SAX Parser Is Used.”
You can validate any incoming XML using industry-standard XML DTD or schema validation. You can also specify which XML items to parse. See Customizing How the SAX Parser Is Used.”
Additional XML Tools
Caché XML support includes the following additional tools:
Considerations When Using the XML Tools
When you work with XML tools of any kind, there are at least three general points to consider:
Character Encoding of Input and Output
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. However, if the character encoding is not declared in that document, Caché assumes the following:
Choosing a Document Format
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:
The following subsections show the differences between these document formats.
Literal Format
The following sample shows an XML document in literal format:
<?xml version="1.0" encoding="UTF-8"?>
<Root>
   <Person>
      <Name>Klingman,Julie G.</Name>
      <DOB>1946-07-21</DOB>
      <GroupID>W897</GroupID>
      <Address>
         <City>Bensonhurst</City>
         <Zip>60302</Zip>
      </Address>
      <Doctors>
         <DoctorClass>
            <Name>Jung,Kirsten K.</Name>
         </DoctorClass>
         <DoctorClass>
            <Name>Xiang,Charles R.</Name>
         </DoctorClass>
         <DoctorClass>
            <Name>Frith,Terry R.</Name>
         </DoctorClass>
      </Doctors>
   </Person>
</Root>
Encoded Format
In contrast, the following example shows the same data in encoded format:
<?xml version="1.0" encoding="UTF-8"?>
<Root xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:s="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
...
   <DoctorClass id="id2" xsi:type="DoctorClass">
      <Name>Jung,Kirsten K.</Name>
   </DoctorClass>
...
   <DoctorClass id="id3" xsi:type="DoctorClass">
      <Name>Quixote,Umberto D.</Name>
   </DoctorClass>
...
   <DoctorClass id="id8" xsi:type="DoctorClass">
      <Name>Chadwick,Mark L.</Name>
   </DoctorClass>
...
   <Person>
      <Name>Klingman,Julie G.</Name>
      <DOB>1946-07-21</DOB>
      <GroupID>W897</GroupID>
      <Address href="#id17" />
      <Doctors SOAP-ENC:arrayType="DoctorClass[3]">
         <DoctorClass href="#id8" />
         <DoctorClass href="#id2" />
         <DoctorClass href="#id3" />
      </Doctors>
   </Person>
   <AddressClass id="id17" xsi:type="s_AddressClass">
      <City>Bensonhurst</City>
      <Zip>60302</Zip>
   </AddressClass>
...
</Root>
Note the following differences in the encoded version:
Note:
For SOAP 1.2, the encoded version is slightly different. To easily distinguish the versions, check the declaration for the SOAP encoding namespace:
Parser Behavior
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:
Standards Supported in Caché
Caché XML support follows these standards:
Also, 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/.
For information on additional standards related to web services and clients, see Creating Web Services and Web Clients in Caché and Securing Caché Web Services.
For information on the character sets expected in XML, see the W3 web site (http://www.w3.org/TR/2006/REC-xml-20060816/#charsets).
Note:
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.