%XML.Writer

Class %XML.Writer Extends %RegisteredObject [ System = 3 ]

For details on using this class, see Writing XML Output from Objects.

The %XML.Writer controls export of XML from InterSystems IRIS. It generates a complete XML document including the <?xml> tag. %XML.Writer works sequentially, outputting the XML as it goes.

%XML.Writer works in two phases. During the first phase, any required parameters are set for the entire document, for example indentation, charset, output media. In the second phase the root element and its child elements are exported. The root element may be the export of a single object and its referenced objects. Or the root element may be a simple element with any number of objects exported as its children.

All parts of the XML document should be output using methods of this class. The Write method may be used to output unformatted and unescaped text inside the the root element of the document. In this case the user is responsible for proper management of namespaces and nesting. Additionally, the Object() and Element() may be used to output nested elements.

Namespace handling is for the most part automatic. %XML.Writer adds namespaces, with automatically created prefixes, to the XML output as needed. The usage of namespaces is controlled by the ElementQualified, AttributeQualified and DefaultNamespace properties, and any namespace argument to an Object or Element call. However, it is possible to control when a namespace is introduced into the document and the prefix used with the AddNamespace method.

The following usage example wraps two instances of the Sample.Person class in tags and sets the root tag to as an example of possible adherence to a business rule: set x1=##class(Sample.Person).%OpenId(1) set x2=##class(Sample.Person).%OpenId(2) set writer=##class(%XML.Writer).%New() set writer.Charset="UTF-8" set sc=writer.OutputToString() If $$$ISERR(sc) Do $system.OBJ.DisplayError(sc) Quit s sc=writer.RootElement("CustomerList") If $$$ISERR(sc) Do $system.OBJ.DisplayError(sc) Quit set sc=writer.Object(x1,"Customer") If $$$ISERR(sc) Do $system.OBJ.DisplayError(sc) Quit set sc=writer.Object(x2,"Customer") If $$$ISERR(sc) Do $system.OBJ.DisplayError(sc) Quit s sc=writer.EndRootElement() If $$$ISERR(sc) Do $system.OBJ.DisplayError(sc) Quit s string=writer.GetXMLString()

Properties

Format

Property Format As %String [ InitialExpression = "literal" ];

The format of the XML document: "literal", "encoded" or "encoded12", "literal" is the default. For "literal" formatting is according to the schema for this document. For "encoded" formatting use SOAP encoding as specified by section 5 of the SOAP 1.1 standard. For "encoded12" formatting use SOAP encoding as specified by part 2 of the SOAP 1.2 standard.

Charset

Property Charset As %String;

Charset is the charset to use for encoding the XML output. The default depends upon the output destination. "UTF-8" is the default for output to files and binary streams. "UTF-16" is the default for output to character streams and strings.

DocumentCharset

Property DocumentCharset As %String [ Internal, Private ];

Copy of Charset property for internal use within a document.

Indent

Property Indent As %Boolean [ InitialExpression = 0 ];

Indent specifies that indentation of the XML output should take place.

IndentChars

Property IndentChars As %String [ InitialExpression = "  " ];

IndentChars specifies the character sequence to be used for each indent level if Indent=1.

RuntimeIgnoreNull

Property RuntimeIgnoreNull As %String [ InitialExpression = 0 ];

If XMLIGNORENULL = "runtime", then the behavior of XMLIGNORENULL is determined by the RuntimeIgnoreNull property. RuntimeIgnoreNull specifies the value of XMLIGNORENULL at runtime as either 0, 1 or inputonly. RuntimeIgnoreNull="inputonly" is equivalent to RuntimeIgnoreNull=0.

Summary

Property Summary As %Boolean [ InitialExpression = 0 ];

If Summary is 1 (true), then export the summary that is specified by the XMLSUMMARY class parameter. Otherwise, export the entire object.

ReferencesInline

Property ReferencesInline As %Boolean [ InitialExpression = 0 ];

If ReferencesInline is 1 (true), then encoded objects are exported inline. By default, SOAP encoded XMLExport of a class uses idref's for class instances referenced by a class that is being exported. This change allows the referenced class instances to be exported inline as for "literal" format. Note that unlike most properties of %XML.Writer, changing the value of ReferencesInline has immediate effect on the next object exported.

Shallow

Property Shallow As %Boolean;

The Shallow controls shallow XML export of objects where referenced objects are not exported. Embedded (serial) objects will still be exported. To indicate shallow export, set Shallow to 1 (default is 0). Note that unlike most properties of %XML.Writer, changing the value of Shallow has immediate effect on the next object exported.

CycleCheck

Property CycleCheck As %Boolean [ InitialExpression = 1 ];

If CycleCheck is true (1), then any object to be exported is checked for cycles in the referenced classes which could result in error. The default is 1.

Base64LineBreaks

Property Base64LineBreaks As %Boolean [ InitialExpression = 0 ];

If Base64LineBreaks is true (1), then remove line breaks from base64 encoded XML output for all properties of type %Binary or %xsd.base64Binary. The default is 0 which will be to not include line breaks.

NoXMLDeclaration

Property NoXMLDeclaration As %Boolean;

If NoXMLDeclaration is 1 (true), then the XML declaration will not be written. The default is to write the XML declaration unless Charset is not specified and the output is directed to a string or character stream in which case no XML declaration is written.

Canonical

Property Canonical As %Boolean [ Internal, Private ];

If Canonical is 1 (true), then output is formatted according to XML Exclusive Canonicalization specification.

ElementQualified

Property ElementQualified As %Boolean;

ElementQualified indicates whether or not locally declared elements must be qualified. The default for Format="encoded"or "encoded12" = 0 and the default for Format="literal" is 1. See elementFormDefault schema attribute.

AttributeQualified

Property AttributeQualified As %Boolean [ InitialExpression = 0 ];

AttributeQualified indicates whether or not locally declared attributes must be qualified. See attributeFormDefault schema attribute.

DefaultNamespace

Property DefaultNamespace As %String;

DefaultNamespace is the XML namespace to use for any exported classes that do not have the NAMESPACE parameter specified. If the NAMESPACE parameter is specified for a class, then the namespace specified in the class is always used.

SuppressXmlns

Property SuppressXmlns As %Boolean [ InitialExpression = 0 ];

SuppressXmlns allows optionally suppression of the use of xmlns= to set default XML namespace when ElementQualified is false. If SuppressXmlns is true then a prefix is used for each tag rather than default namespace with xmlns=.

SuppressAutoPrefix

Property SuppressAutoPrefix As %Boolean [ InitialExpression = 0, Internal, Private ];

SuppressAutoPrefix allows optionally suppression of the prefix that is created for the default XML namespace even if it is not needed for the current element.

DefaultXmlns

Property DefaultXmlns As %String;

DefaultXmlns allows optional specification of the XML namespace to use as the default XML namespace when SuppressXmlns is false.

OutputTypeAttribute

Property OutputTypeAttribute As %Boolean [ InitialExpression = 0 ];

OutputTypeAttribute allows the user to force the inclusion of the xsi:type attribute for each element of object output.

Namespaces

Property Namespaces As %XML.Namespaces [ Internal ];

The namespace manager class.

InDocument

Property InDocument As %Boolean [ InitialExpression = 0, Internal, Private ];

True if we've started writing the XML document.

InternalStartDocument

Property InternalStartDocument As %Boolean [ InitialExpression = 0, Internal, Private ];

True if document was implictely started without StartDocument call.

InRootElement

Property InRootElement As %Boolean [ InitialExpression = 0, Internal, Private ];

True if we've started writing the root element.

InForest

Property InForest As %Boolean [ InitialExpression = 0, Internal, Private ];

True if forest allowed instead of just single root node. Note that this may not be a valid document.

InTag

Property InTag As %Boolean [ InitialExpression = 0, Internal, Private ];

True if we've written the tag and not yet finished the start element.

CurrentIndent

Property CurrentIndent As %String;

The current indent level.

IndentNext

Property IndentNext As %Boolean [ InitialExpression = 0, Private ];

If true, indenting to be done for next element, comment or processing instruction.

OrefList

Property OrefList As %String [ MultiDimensional, Private ];

Internal list of orefs for use by encoded output.

IdList

Property IdList As %String [ MultiDimensional, Private ];

Internal list of orefs for use by encoded output.

ElementStack

Property ElementStack As %String [ MultiDimensional, Private ];

Stack of end elements for currently started elements. ElementStack(index) == qname for element ElementStack(index,"ns") == previous default namespace

OutputDestination

Property OutputDestination As %String [ InitialExpression = "device", Private ];

Internal list of ids for use by encoded output. Destination for %XML.Writer output. Possible values are "file", "charstream", "binarystream", "charstring" and "device".

OutputTable

Property OutputTable As %String [ Private ];

Internal -- translate table used for output

OutputFilename

Property OutputFilename As %String [ Private ];

Filename for output to file.

OriginalTable

Property OriginalTable As %String [ Internal, Private ];

Internal -- original translate table for current output device

ExtendedDocument

Property ExtendedDocument As %Boolean [ Internal ];

True if a document has already been written to this file/stream. This property is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this property.

OutputStream

Property OutputStream As %RegisteredObject [ Private ];

Stream for output to stream or file. Will store a stream, but declare as %RegisteredObject to prevent auto create of serial object.

UserStream

Property UserStream As %RegisteredObject [ Private ];

User specified Global stream that will receive data. Will store a stream, but declare as %RegisteredObject to prevent auto create of serial object.

SaveIO

Property SaveIO As %String [ Internal, Private ];

Save current $io

Methods

DefaultXmlnsSet

Method DefaultXmlnsSet(value As %String) As %Status [ Internal ]

OutputTypeAttributeSet

Method OutputTypeAttributeSet(value As %Boolean) As %Status [ Internal ]

OutputToDevice

Method OutputToDevice() As %Status

OutputToDevice sets output to the current device which is the default if no output method is specified.

OutputToString

Method OutputToString() As %Status

OutputToString sets output to be directed to a string. GetXMLString may be called after output is complete to a string to retrieve the output.

GetXMLString

Method GetXMLString(ByRef status As %Status) As %String

GetXMLString gets output generated using OutputToString.

OutputToStream

Method OutputToStream(ByRef export As %BinaryStream) As %Status

OutputToStream sets output to be directed to a stream. export is the exported stream. If export is the oref of a stream, the XML document will be written to this existing stream at the current position. If export is "", then a new %FileBinaryStream will be created to contain the XML document and its oref returned. In this case, export must be passed by reference.

OutputToFile

Method OutputToFile(filename As %String) As %Status

OutputToFile sets output to be directed to a new file, named filename.

Reset

Method Reset() As %Status

The Reset method may be called after an XML document has been output by RootObject or RootElement to reintialize the properties and output method of the XML document.

InitNamespaces

Method InitNamespaces() As %Status [ Internal ]

Initialize the namespaces manager. This method is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this property.

AddNamespace

Method AddNamespace(namespace As %String, prefix As %String, schemaLocation As %String) As %Status

AddNamespace adds a namespace to the XML document for all elements added at this nesting level. The prefix to be used for the namespace may optionally be specified with the prefix argument. A schemaLocation attribute value for the first definition of this namespace may also specified. For example, if many children of an element will use the same namespace, it is better to add the namespace above the containing element, so that the prefix may be defined only once at the containing level using the xmlns:prefix attribute.

AddInstanceNamespace

Method AddInstanceNamespace(prefix As %String) As %Status

AddInstanceNamespace adds the schema instance namespace to the document using the optional prefix. If the prefix argument is not specifed, "xsi" is used as the prefix.

AddSchemaNamespace

Method AddSchemaNamespace(prefix As %String) As %Status

AddSchemaNamespace adds the schema namespace to the document using the optional prefix. If the prefix argument is not specifed, "s" is used as the prefix.

AddSOAPNamespace

Method AddSOAPNamespace(soapPrefix As %String, schemaPrefix As %String, xsiPrefix As %String) As %Status

AddSOAPNamespace adds the SOAP 1.1 encoding, schema and schema instance namespaces to the document using the optional prefixes soapPrefix, schemaPrefixPrefix and xsiPrefix.

AddSOAP12Namespace

Method AddSOAP12Namespace(soapPrefix As %String, schemaPrefix As %String, xsiPrefix As %String) As %Status

AddSOAP12Namespace adds the SOAP 1.2 encoding, schema and schema instance namespaces to the document using the optional prefixes soapPrefix, schemaPrefixPrefix and xsiPrefix.

StartDocument

Method StartDocument(allowForest As %Boolean = 0) As %Status

Start output of the XML document If allowForest = true, then mutiple root nodes are allowed.

EndDocument

Method EndDocument() As %Status

Finish output of the XML document

StartDocumentInternal

Method StartDocumentInternal(rootOK As %Boolean) As %Status [ Private ]

This method is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this property.

EndDocumentInternal

Method EndDocumentInternal() As %Status [ Private ]

This method is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this property.

RootObject

Method RootObject(object As %XML.Adaptor, tag As %String, namespace As %String, className As %String, bare As %Boolean) As %Status

RootObject will output the document as a single object instance and all its references. The RootObject method initializes itself based on the properties of the %XML.Writer instance and does the output. When output is complete, it writes the final end tag and closes the output device. At this point, the %XML.Writer properties may be modified and RootObject or RootElement called again to output another document.

• object is the XML enabled object instance to output.
• tag optionally specifies the tag name to be used for this element.
• namespace optionally specifies the default namespace for this object. If the NAMESPACE parameter is specified for a class, then the namespace specified in the class is always used.
• className is the expected name of this object's class. If the className is specified and this class's name is not equal to the name in className, then add a xsi:type attribute to the element.
• bare is for internal ISC use only. If the Format="encoded" property is used and RootObject called, then all object instances will be output as embedded in the top level object. This is usually not desired and therefore objects to be output using SOAP encoding should usually be enclosed in by a root element using RootElement and EndRootElement.

RootElement

Method RootElement(root, namespace As %String) As %Status

The RootElement method writes only the root element of the XML document Child elments must be written by the user. The RootElement method initializes based on the properties of the %XML.Writer instance and does the output. EndRootElement() writes the final end tag and closes the output device. After EndRootElement() is called, the properties may be modified and RootObject or RootElement called again to output another document.

There are two possible polymorphic formats for the RootElement method. The element to output may be either have its name specified as a %String or have the element specified as a %XML.Element instance. root is the root element specified either as a tag name or an %XML.Element instance.
namespace optionally specifies the default namespace for this element and any nested elements.

EndRootElement

Method EndRootElement() As %Status

EndRootElement is the method to end the root element.

ParsePrefixList

ClassMethod ParsePrefixList(PrefixList As %String, ByRef PrefixListArray)

The ParsePrefixList parses the PrefixList that is specified for Exclusive Canonicalization as a list of NMTOKENS. True (1) is returned if the parsing is successful.

Canonicalize

Method Canonicalize(node As %XML.Node, ByRef PrefixList, formatXML As %Boolean = 0, isSTR As %Boolean = 0, mimeAttachments As %Net.MIMEPart = "") As %Status

The Canonicalize method writes an XML document with root element specified by the %XML.Node class in canonicalized form specified by the Exclusive XML Canonicalization or Canonical XML (also called inclusive canonicalization) specification.

• node is the parse tree that represents the XML document to be output.
• For Exclusive XML Canonicalization PrefixList is a multidimensional array which specifies the prefixes that are included on the IncludedNamespaces list. PrefixList(prefix)="" if the prefix is on the list. If PrefixList is = "c14n", then inclusive canonicalization is performed.
• If formatXML is true, the formatting specified for %XML.Writer rather than the formatting specified by the XML Canonicalization specification is used. The output is not strictly speaking canonical XML, but has done the namespace processing for canonical XML. This behavior is useful for outputting a fragment of an XML document, such as the SOAP body in the ProcessBodyNode callback from a web service, while still having some control of the format.
• isSTR is for internal use. If true, keep xmlns="" on the APEX node as specified by WS-Security for canonicalization of XML freferenced by a SecurityTokenReference.
• If the XML document is in MTOM format, then mimeAttachments is a mime part which contains in the Parts property the list of attachments.

CanonicalTree

Method CanonicalTree(node As %XML.Node, ByRef PrefixList, isSTR As %Boolean = 0, mimeAttachments As %Net.MIMEPart = "") As %Status

The CanonicalTree method writes element content as represented by the %XML.Node class in canonicalized form specified by the Exclusive XML Canonicalization or Canonical XML (also called inclusive canonicalization) specification.

• node is the parse tree that represents the XML document to be output.
• For Exclusive XML Canonicalization PrefixList is a multidimensional array which specifies the prefixes that are included on the IncludedNamespaces list. PrefixList(prefix)="" if the prefix is on the list. If PrefixList is = "c14n", then inclusive canonicalization is performed.
• isSTR is for internal use. If true, keep xmlns="" on the APEX node as specified by WS-Security for canonicalization of XML freferenced by a SecurityTokenReference.
• If the XML document is in MTOM format, then mimeAttachments is a mime part which contains in the Parts property the list of attachments.

CanonicalTreeInternal

Method CanonicalTreeInternal(DocId As %String, NodeId As %String, baseChildlist As %String, ByRef PrefixList, isSTR As %Boolean, mimeAttachments As %Net.MIMEPart, addedPrefix) As %Status [ Internal ]

The CanonicalTreeInternal method is an internal method to implement recursion needed to canonicalize.

Document

Method Document(documentArg As %XML.Document) As %Status

The Document method writes the XML document represented by the %XML.Document class. The Document method initializes based on the properties of the %XML.Writer instance and does the output. document is the parse tree that represents the XML document to be output.

DocumentNode

Method DocumentNode(node As %XML.Node) As %Status

The DocumentNode method writes the XML document represented by the %XML.Node class. The DocumentNode method initializes based on the properties of the %XML.Writer instance and does the output. node is the parse tree that represents the XML document to be output.

Tree

Method Tree(node As %XML.Node, keepxmlns As %Boolean = 0) As %Status

The Tree method writes the XML document node represented by the %XML.Node class and its tree of descendants.. node is an %XML.Node class that is positioned at the node to output.

TreeInternal

Method TreeInternal(DocId As %String, NodeId As %String, baseChildlist As %String, keepxmlns As %Boolean = 0) As %Status [ Internal ]

The TreeInternal method is an internal method to implement recursion needed to output document from DOM.

Object

Method Object(objectArg As %XML.Adaptor, tag As %String, namespace As %String, local As %Boolean, className As %String, bare As %Boolean) As %Status

Object outputs objects nested in the root object of an XML document.

• object is the XML enabled object instance to output.
• tag optionally specifies the tag name to be used for this element.
• namespace optionally specifies the default namespace for this object. If the NAMESPACE parameter is specified for a class, then the namespace specified in the class is always used.
• local specifies if the element is treated as a local element. Default is 0 (false).
• className is the expected name of this object's class. If the className is specified and this class's name is not equal to the name in className, then add a xsi:type attribute to the element.
• bare is for internal ISC use only.

Element

Method Element(tag, namespace As %String) As %Status

Element outputs elements nested in the root object of an XML document.

There are two possible polymorphic formats for the Element method. The element to output may be either have its name specified as a %String or have the element specified as a %XML.Element instance. tag is the nexted element specified either as a tag name or an %XML.Element instance.
namespace optionally specifies the default namespace for this element and any nested elements.

WriteAttribute

Method WriteAttribute(name As %String, value As %String = "", namespace As %String, valueNamespace As %String = "", global As %Boolean = 0) As %Status

The WriteAttribute method writes an attribute for the last element started. This method may only be called immediately after StartElement or Element.
Arguments: - name is the attribute name and is required.
- value is the attribute value and is required.
- namespace is the optional namespace for the attribute name. If namespace is not specified, then the default XML namespace is used for the attribute name.
- valueNamespace is the namespace for the value.
If valueNamespace is not specified (the most usual case), no namespace prefix is used for the value. valueNamespace is used for attributes like xsi:type whose value comes from an XML schema namespace. - global is true if the attribute is global in the associated XML schema and thus should have a prefix. Default is false.

EndElement

Method EndElement() As %Status

EndElement outputs the end element for the matching element started with the Element method.

Write

Method Write(text) As %Status

Write writes arbitrary text in the XML document without any escaping being done. This method can be used in any part of the XML document.
Argument:
- text The character data to output. Type of %String or %CharacterStream.

StartWrite

Method StartWrite() As %Status

StartWrite sets the current device for writing arbitrary text in the XML document without any escaping being done. This method can be used in any part of the XML document.

EndWrite

Method EndWrite() As %Status

EndWrite restores the current device to before matching StartWrite. This method can be used in any part of the XML document.

WriteChars

Method WriteChars(text) As %Status

WriteChars writes XML element text performing any required escaping. This method is used to write element content.
Argument:
- text The character data to output. Type of %String or %CharacterStream.

CharsText

Method CharsText(text As %String, Output overflow) As %String

Do canonical formatting of element text

AttributeText

Method AttributeText(attrval As %String) As %String

Do canonical formatting of attribute text

WriteCData

Method WriteCData(text) As %Status

WriteCData writes XML element text in a CData section. This method is used to write element content.
Argument:
- text The character data to output. Type of %String or %CharacterStream.

WriteBase64

Method WriteBase64(binary) As %Status

WriteBase64 encodes the specified binary bytes as base64 and writes out the resulting text. This method is used to write element content.
Argument:
- binary The binary data to output. Type of %Binary or %BinaryStream.

WriteBinHex

Method WriteBinHex(binary) As %Status

WriteBinHex encodes the specified binary bytes as binhex and writes out the resulting text. This method is used to write element content.
Argument:
- binary The binary data to output. Type of %Binary or %BinaryStream.

WriteComment

Method WriteComment(text) As %Status

WriteComment writes out a comment containing the specified text. This method can be used in any part of the XML document.
Argument:
- text Text to place inside the comment. Type of %String or %CharacterStream.

WriteDocType

Method WriteDocType(name As %String, PublicId As %String, SystemId As %String, subset As %String) As %Status

WriteDocType writes the DOCTYPE declaration with the specified name and optional attributes. This method may only be called before the root element is written.
Arguments:
- name The name of the DOCTYPE. This must be non-empty.
- PublicId If non-null it also writes PUBLIC "PublicId" "SystemId" where PublicId and SystemId are replaced with the value of the given arguments.
- SystemId If PublicId is null and SystemId is non-null it writes SYSTEM "SystemId" where SystemId is replaced with the value of this argument.
- subset If non-null it writes [Subset] where Subset is replaced with the value of this argument.

WriteProcessingInstruction

Method WriteProcessingInstruction(name As %String, text As %String) As %Status

WriteProcessingInstruction writes out a processing instruction with a space between the name and text as follows: . This method may only be called outside the root element is written.
Arguments:
- name Name of the processing instruction.
- text Text to include in the processing instruction.