Introduction to InterSystems XML Tools

Representing Object Data in XML

Some of the XML tools are intended for use mainly with XML-enabled classes. To XML-enable a class, you add %XML.AdaptorOpens in a new tab to its superclass list. The %XML.AdaptorOpens in a new tab class enables you to represent instances of that class as XML documents. You add class parameters and property parameters to fine-tune the projection. See Projecting Objects to XML.

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.

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

In the context of XML-enabled classes, the %XML.WriterOpens in a new tab class enables you to export data as XML documents. The output destination is typically a file or a stream.

The %XML.ReaderOpens in a new tab 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.

A DOM is also a useful way to work with an XML document. You can use the %XML.ReaderOpens in a new tab 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.DocumentOpens in a new tab, which represents the document itself and which contains the nodes. Then you use %XML.NodeOpens in a new tab to examine and manipulate the nodes. You can use %XML.WriterOpens in a new tab to write the XML document again, if needed.

The InterSystems IRIS XML tools provide many ways to access data in and modify both XML documents and DOMs.

Creating Arbitrary XML

With InterSystems IRIS XML tools, you can also 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.WriterOpens in a new tab. This class provides methods for adding elements, adding attributes, adding namespace declarations, and so on.

To create an arbitrary DOM, use %XML.DocumentOpens in a new tab. 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.ReaderOpens in a new tab 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:

• %XML.TextReaderOpens in a new tab — You can use this to read and parse a document, node by node. See Using %XML.TextReader.

• %XML.XPATH.DocumentOpens in a new tab — You can use this to obtain data, by using an XPATH expression that refers to a specific node in the document. See Evaluating XPath Expressions.

In InterSystems IRIS, a DOM is an instance of %XML.DocumentOpens in a new tab. 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.NodeOpens in a new tab 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.TransformerOpens in a new tab 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.DocumentOpens in a new tab 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. Also 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:

• The %XML.Utils.SchemaReaderOpens in a new tab class enables you to generates a set of XML-enabled classes that correspond to the types defined in the schema. You specify a package to contain the classes, as well as various options that control the details of the class definitions.

• The %XML.SchemaOpens in a new tab class enables you to generate an XML schema from a set of XML-enabled classes.

• The %XML.NamespacesOpens in a new tab class enables you to examine the XML namespaces and the classes in them, for an InterSystems IRIS namespace.

• The %XML.Security.EncryptedDataOpens in a new tab class and other classes enable you to encrypt XML documents, as well as decrypt encrypted documents.

• The %XML.Security.SignatureOpens in a new tab class and other classes enable you to digitally sign XML documents, as well validate digital signatures.