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 enabledXML
The 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 the
XML
Within a document, it can be a file, stream, or other document. - Included in the
DOM
(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 documentXPath
Expression.
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.Schema
Class enables XML schema generation from a set of XML-enabled classes.%XML.Namespaces
Class enables you to examine XML namespaces and the classes in them to find InterSystems IRIS namespaces.%XML.Security.EncryptedData
Class and other classes enable the ability to encrypt XML documents and decrypt encrypted documents.%XML.Security.Signature
Class 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 or
SOAP
There 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 stream
For "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 use
SOAP
, text format is also used. Examples in the documentation are in text format unless otherwise noted. - Code means according to
SOAP 1.1
Standard orSOAP 1.2
The encoding described in the standard.SOAP1.1
andSOAP1.2
The 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 include
SOAP
Declaration of encoding namespaces and other standard namespaces. - This document includes personnel, address, and doctor elements at the same level.
Address
andDoctor
The element lists the references to themPerson
The unique element used by theID
. Each object value attribute is handled this way. - top
Address
andDoctor
The 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.
GroupID
Property is mapped toPerson
Attributes 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 attributes
ENC:arrayType
. - There’s one for each element
Xsi: type
Property value.
Note: For SOAP1.2, the encoding version is slightly different. To distinguish versions easily, check the declaration of the SOAP encoding namespace:
- for
SOAP1.1, SOAP
The encoding namespace is"http://schemas.xmlsoap.org/soap/encoding/"
- for
SOAP1.2, SOAP
The 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.