Introduction to InterSystems XML Tools
In InterSystems IRIS®, 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 the database. Furthermore, InterSystems IRIS provides tools for working with arbitrary XML documents and DOMs (Document Object ModelOpens in a new tab) — even documents that are not related to any InterSystems IRIS classes.
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:
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.
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.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.
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 Schema Wizard reads an XML schema document and 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.NamespacesOpens in a new tab class enables you to examine the XML namespaces and the classes in them, for an InterSystems IRIS namespace.