docs.intersystems.com
Home  /  Application Development: Additional Options  /  Using XML Tools  /  Introduction to InterSystems XML Tools


Using XML Tools
Introduction to InterSystems XML Tools
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


This book describes how to use InterSystems IRIS XML tools.
InterSystems IRIS brings the power of objects to XML processing — you can use objects as a direct representation of XML documents and vice versa. Because InterSystems IRIS includes a native object database, you can use such objects directly with a database. Furthermore, InterSystems IRIS provides tools for working with XML documents and DOMs (Document Object Model), even if these are not related to any InterSystems IRIS classes.
This chapter discusses the following topics:
Representing Object Data in XML
Some of the InterSystems IRIS 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 Objects.”
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 InterSystems IRIS 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 InterSystems IRIS XML tools provide many ways to access data in and modify both XML documents and DOMs.
Creating Arbitrary XML
You can also use InterSystems IRIS XML tools to create and work with arbitrary XML — that is, XML that does not map to any InterSystems IRIS 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 InterSystems IRIS 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 InterSystems IRIS, 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 InterSystems IRIS 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
InterSystems IRIS XML Tools use the InterSystems IRIS 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. InterSystems IRIS SAX communicates with an InterSystems IRIS process using a high-performance, in-process call-in mechanism. Using this parser, you can process XML documents using either the built-in InterSystems IRIS XML support or by providing your own custom SAX interface classes within InterSystems IRIS.
For special applications, you can 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, and you can specify which XML items to parse. See Customizing How the SAX Parser Is Used.”
Additional XML Tools
InterSystems IRIS 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, InterSystems IRIS chooses the encoding, depending on the destination:
For any XML document read by InterSystems IRIS, 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, InterSystems IRIS assumes the following:
For background information on character translation in InterSystems IRIS, see Localization Support in the Orientation Guide for Server-Side Programming.
Choosing a Document Format
When you work with an XML document, you must know the format to use when mapping the document to InterSystems IRIS 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 InterSystems IRIS SAX Parser is used whenever InterSystems IRIS reads an XML document, so it is useful to know its default behavior. Among other tasks, the parser does the following:
Standards Supported in InterSystems IRIS
InterSystems IRIS XML support follows these standards:
The InterSystems IRIS 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/.
InterSystems IRIS provides two XSLT processors:
For information on additional standards related to web services and clients, see Creating Web Services and Web Clients and Securing 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:
InterSystems IRIS does not support, within one element, multiple attributes with the same name, each in a different namespace.