Skip to main content

Introduction to InterSystems XML Tools

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.

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.

A class with multiple properties can be represented as an object or an XML document.

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.

  • Contained in a DOM (Document Object Model).

The following figure provides an overview of the tools that you use to convert your data among these forms:

%XML.Writer can create an XML document from an XML-enabled class or a DOM. %XML.Reader can do the reverse operation.

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:

The XML Document tools are %XML.TextReader and %XML.XPATH.Document. The DOM tools are %XML.Document and %XML.Node.

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:

%XML.XSLT.Transformer can modify an XML Documents, while %XML.Document can modify a DOM.

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:

  • If the output destination is a file or a binary stream, the default is "UTF-8".

  • If the output destination is a string or a character stream, the default is "UTF-16".

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:

  • If the document is a file or a binary stream, InterSystems IRIS assumes that the character set is "UTF-8".

  • If the document is a string or a character stream, InterSystems IRIS assumes the character set is "UTF-16".

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:

  • 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.

  • Encoded means encoded as described in the SOAP 1.1 standard or the SOAP 1.2 standard. For links to these standards, see “Standards Supported in InterSystems IRIS,” later in this chapter.

    The details are slightly different for SOAP 1.1 and SOAP 1.2.

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:

  • 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 attribute.

Note:

For SOAP 1.2, the encoded version is slightly different. To easily distinguish the versions, check the declaration for the SOAP encoding namespace:

  • For SOAP 1.1, the SOAP encoding namespace is "http://schemas.xmlsoap.org/soap/encoding/"

  • For SOAP 1.2, the SOAP encoding namespace is "http://schemas.xmlsoap.org/wsdl/soap12/"

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:

  • 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:

    <xsd:import namespace="target-namespace-of-the-importing-schema"
                  schemaLocation="uri-of-the-schema"/>

<xsd:include schemaLocation="uri-of-the-schema"/>

    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.

    If needed, you can create custom entity resolvers and you can disable entity resolution; see “Customizing How the SAX Parser Is Used.”

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:

  • The Xalan processor supports XSLT 1.0.

  • The Saxon processor supports XSLT 2.0.

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 (https://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.

Next sectionWriting XML Output from Objects
Feedback