Chapter 1 Introduction to InterSystems XML tools

Describes how to use the IRIS XML tool.

InterSystems IRIS brings the power of objects to XML processing — you can use objects as direct representations of XML documents, and vice versa. Because InterSystems IRIS includes a native object database, such objects can be used directly with databases. In addition, InterSystems IRIS provides tools for working with XML documents and the DOM(Document Object Model), even if they are unrelated to any InterSystems IRIS class.

Represent object data in XML

Some InterSystems IRIS XML tools focus on XML-enabled classes. To enable XML for a class, add % xml. Adaptor to its superclass list. The % xml. Adaptor class makes it possible to represent instances of the class as XML documents. You can add class and attribute parameters to fine-tune the projection.

For enabledXMLThe data can take all of the following forms:

  • Contained in the class instance. Depending on the class, you can also save the data to disk, where it can be used in all the same ways as any other persistent class.
  • Included in theXMLWithin a document, it can be a file, stream, or other document.
  • Included in theDOM(Document Object Model).

The following diagram summarizes the tools used to convert data between these forms:

The % xml. Writer class enables the creation of XML documents. The output destination is usually a file or stream. Determine the objects to be included in the output, which the system generates according to the rules established in the class definition.

The % xml.reader class makes it possible to import the appropriate XML document into the class instance. The source is usually a file or stream. To use this class, you specify an association between the class name and the elements contained in the XML document. The given element must have the structure required by the corresponding class. You then read the document node by node. When you do this, the system creates an in-memory instance of the class that contains the data found in the XML document.

DOM is also a useful way to work with XML documents. 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 that you can navigate between as needed. Specifically, an instance of % xml.document will be created that represents the Document itself and contains nodes. The nodes are then checked and manipulated using % xml.node. If necessary, you can rewrite the XML document using % xml.writer.

The InterSystems IRIS XML tool provides many ways to access and modify data in XML documents and the DOM.

Creating arbitrary XML

You can also use the InterSystems IRIS XML tool to create and use arbitrary XML — that is, XML that does not map to any InterSystems IRIS class. To create arbitrary XML documents, use % xml.writer. This class provides methods for adding elements, adding attributes, adding namespace declarations, and so on.

To create any DOM, use % xml.document. This class provides a class method that returns the DOM with a single empty node. Nodes are then added as needed using the instance methods of the class.

Or use % xml. Reader to read any XML document and then create the DOM from that document.

To access the data

The InterSystems IRIS XML tool provides several ways to access data in XML format. The following figure shows the summary:

For any well-formed XML document, you can use the following classes to process the data in that document:

  • %XML.TextReader– You can use it to read and parse documents node by node.
  • %XML.XPATH.Document– You can use it to retrieve data by referring to a specific node in the documentXPathExpression.

In InterSystems IRIS, DOM is an instance of % xml.document. This instance represents the document itself and contains nodes. You can use the properties and methods of this class to retrieve values from the DOM. Nodes can be checked and manipulated using % xml. Node.

Modify XML

The InterSystems IRIS XML tool also provides a way to modify data in XML format. The following figure shows the summary:

For XML documents, you can use class methods in % xml.XSLT.Transformer to perform an XSLT transformation and get a modified version of the document.

For the DOM, you can modify the DOM using the % xml.document method. For example, you can add or remove elements or attributes.

The SAX parser

The InterSystems IRIS XML tool uses the InterSystems IRIS SAX(Simple API For XML) parser. This is a built-in SAX XML validation parser that uses the standard Xerces library. SAX is a parsing engine that provides complete XML validation and document parsing. InterSystems IRIS SAX uses a high-performance in-process call-in mechanism to communicate with the InterSystems IRIS process. Using this parser, you can process XML documents using the built-in InterSystems IRIS XML support or by providing your own custom SAX interface classes in InterSystems IRIS.

For special applications, you can create custom entity resolvers and content handlers.

You can use the industry-standard XMLDTD or schema validation to validate any incoming XML, and you can specify which XML items to parse.

Other XML tools

InterSystems IRIS XML support includes the following additional tools:

  • The XML Schema wizard reads the XML schema document and generates a set of XML-enabled classes that correspond to the types defined in the schema. You can specify a package to contain the class, along with various options to control the details of the class definition.
  • %XML.SchemaClass enables XML schema generation from a set of XML-enabled classes.
  • %XML.NamespacesClass enables you to examine XML namespaces and the classes in them to find InterSystems IRIS namespaces.
  • %XML.Security.EncryptedDataClass and other classes enable the ability to encrypt XML documents and decrypt encrypted documents.
  • %XML.Security.SignatureClass and other classes enable digital signing of XML documents, as well as validating digital signatures.

Considerations when using XML tools

There are at least three general points to consider when using any type of XML tool:

  • Any XML document has a character encoding
  • Map XML documents to classes (literal orSOAPThere are different ways of coding
  • You should know the default behavior of the SAX parser

Character encoding of input and output

When exporting an XML document, you can specify the character encoding to use; Otherwise, InterSystems IRIS selects the encoding based on the target:

  • If the output target is a file or binary stream, the default value is “UTF-8”.
  • Default if the output target is a string or character streamFor "UTF - 16".

For any XML document read by InterSystems IRIS, the document’s XML declaration should indicate the file’s character encoding, and the document should be encoded as declared. Such as:

<? The XML version = "1.0" encoding = "utf-8 16"? >Copy the code

However, if no character encoding is declared in the document, InterSystems IRIS will assume that:

  • If the output target is a file or binary stream, the default is"Utf-8".
  • Default if the output target is a string or character stream"UTF-16".

Select document Format

When working with XML documents, you must know the format to use when mapping documents to InterSystems IRIS classes. Similarly, when you create an XML document, you need to specify the document format to use when writing the document. The XML document format is as follows:

  • Literals indicate that the document is a literal copy of the object instance. In most cases, even in useSOAP, text format is also used. Examples in the documentation are in text format unless otherwise noted.
  • Code means according toSOAP 1.1Standard orSOAP 1.2The encoding described in the standard.SOAP1.1andSOAP1.2The details are slightly different.

The following sections show the differences between these document formats.

Text 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>
Copy the code

Coding format

By contrast, the following example displays the same data in coded 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>
Copy the code

Please note the following differences in the encoded version:

  • The root elements of the output includeSOAPDeclaration of encoding namespaces and other standard namespaces.
  • This document includes personnel, address, and doctor elements at the same level.AddressandDoctorThe element lists the references to themPersonThe unique element used by theID. Each object value attribute is handled this way.
  • topAddressandDoctorThe names of the elements are the same as the names of their respective classes, not the names of the attributes that reference them.
  • The encoding format does not include any attributes.GroupIDProperty is mapped toPersonAttributes in a class. In literal format, this property is projected as a property. However, in the encoded version, attributes are projected as elements.
  • Sets are treated differently. For example, list elements have attributesENC:arrayType.
  • There’s one for each elementXsi: typeProperty value.

Note: For SOAP1.2, the encoding version is slightly different. To distinguish versions easily, check the declaration of the SOAP encoding namespace:

  • forSOAP1.1, SOAPThe encoding namespace is"http://schemas.xmlsoap.org/soap/encoding/"
  • forSOAP1.2, SOAPThe encoding namespace is"http://schemas.xmlsoap.org/wsdl/soap12/"

Unless the parser can use these other schemas, validation will fail. Especially for WSDL documents, sometimes you need to download all schemas and edit the main schema to use the correct location.

It tries to resolve all entities, including all external entities. (Other XML parsers do the same.) . This process can be time-consuming, depending on where they are located. Specifically, Xerces uses network accessors to resolve some urls, and the implementation uses blocking I/O. Therefore, there is no timeout and network acquisition may hang under error conditions, which is rare in practice.

In addition, Xerces does not support HTTPS; That is, it cannot resolve entities in HTTPS locations.

You can either create a custom entity resolver or disable entity resolution if desired;

Standards supported by IRIS

IRIS XML support follows the following standards:

  • XML 1.0 (www.w3.org/TR/REC-xml/)

  • Namespaces in XML 1.0 (www.w3.org/TR/REC-xml-…)

  • XML Schema 1.0 (www.w3.org/TR/xmlschem… , www.w3.org/TR/xmlschem… , www.w3.org/TR/xmlschem,…).

  • XPath 1.0 as specified by www.w3.org/TR/xpath

  • SOAP 1.1 encoding as specified in Section 5 of the SOAP 1.1 standard.

  • SOAP1.2 encoding, as in Section 3, Part 2: Adjuncts (www.w3.org/TR/soap12-p…) Of the SOAP 1.2 Standard.

  • XML Canonicalization Version 1.0 (also known as inclusive canonicalization), as specified by www.w3.org/TR/xml-c14n.

  • XML Exclusive Canonicalization Version 1.0 as Specified by www.w3.org/TR/xml-exc-… Including the InclusiveNamespaces PrefixList feature (www.w3.org/TR/xml-exc-…)

  • XML Encryption (www.w3.org/TR/xmlenc-c…)

InterSystems IRIS supports key encryption using RSA-OAEP or RSA-1.5, and data encryption for message bodies using AES-128, AES-192, or AES-256.

  • XML Canonicalization and RSA SHA-1 (www.w3.org/TR/xmldsig-…)

InterSystems IRIS provides two XSLT processors:

  • The Xalan processor supports XSLT 1.0.
  • The Saxon processor supports XSLT 2.0.

Note: InterSystems IRIS does not support multiple attributes with the same name within an element, each in a different namespace.