Class %XML.Writer

class %XML.Writer extends %RegisteredObject

The %XML.Writer controls export of XML from Caché. 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()

Inventory

Parameters	Properties	Methods	Queries	Indices	ForeignKeys	Triggers
	38	45

Summary

Properties
AttributeQualified	Charset	CurrentIndent	CycleCheck
DefaultNamespace	DefaultXmlns	ElementQualified	Format
Indent	IndentChars	NoXMLDeclaration	OutputTypeAttribute
ReferencesInline	RuntimeIgnoreNull	Shallow	Summary
SuppressXmlns

Methods
%%OIDGet	%AddToSaveSet	%ClassIsLatestVersion	%ClassName
%ConstructClone	%DispatchClassMethod	%DispatchGetModified	%DispatchGetProperty
%DispatchMethod	%DispatchSetModified	%DispatchSetMultidimProperty	%DispatchSetProperty
%Extends	%GetParameter	%IsA	%IsModified
%New	%NormalizeObject	%ObjectModified	%OriginalNamespace
%PackageName	%RemoveFromSaveSet	%SerializeObject	%SetModified
%ValidateObject	AddInstanceNamespace	AddNamespace	AddSOAP12Namespace
AddSOAPNamespace	AddSchemaNamespace	AttributeText	CanonicalTree
Canonicalize	CharsText	DefaultXmlnsSet	Document
DocumentNode	Element	EndDocument	EndElement
EndRootElement	EndWrite	GetXMLString	Object
OutputToDevice	OutputToFile	OutputToStream	OutputToString
OutputTypeAttributeSet	ParsePrefixList	Reset	RootElement
RootObject	StartDocument	StartWrite	Tree
Write	WriteAttribute	WriteBase64	WriteBinHex
WriteCData	WriteChars	WriteComment	WriteDocType
WriteProcessingInstruction

Properties

• property AttributeQualified as %Boolean [ InitialExpression = 0 ];

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

• 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. On a Unicode Caché, "UTF-16 is the default for output to character streams and strings. On an 8 bit Caché, the default charset for the locale is the default charset for output to character streams and strings.

• property CurrentIndent as %String;

The current indent level.

• 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.

• 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.

• property DefaultXmlns as %String;

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

• 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.

• 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.

• property Indent as %Boolean [ InitialExpression = 0 ];

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

• property IndentChars as %String [ InitialExpression = " " ];

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

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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=.

Methods

• 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.

• 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.

• 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.

• 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.

• 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.

• method AttributeText(attrval As %String) as %String

Do canonical formatting of attribute text

• method CanonicalTree(node As %XML.Node, ByRef PrefixList, isSTR As %Boolean = 0) 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.

• method Canonicalize(node As %XML.Node, ByRef PrefixList, formatXML As %Boolean = 0, isSTR As %Boolean = 0) 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.

• method CharsText(text As %String, Output overflow) as %String

Do canonical formatting of element text

• method Document(document 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.

• 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.

• 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.

• method EndDocument() as %Status

Finish output of the XML document

• method EndElement() as %Status

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

• method EndRootElement() as %Status

EndRootElement is the method to end the root element.

• 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.

• method GetXMLString(ByRef status As %Status) as %String

GetXMLString gets output generated using OutputToString.

• method Object(object 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.

• method OutputToDevice() as %Status

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

• method OutputToFile(filename As %String) as %Status

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

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• method StartDocument(allowForest As %Boolean = 0) as %Status

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

• 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.

• method Tree(node As %XML.Node) 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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: <?name text?>. 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.


[%SYS] > [%XML] > [Writer]		Private Storage