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()
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.
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.
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.
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.
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.
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 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.
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 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=.
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.
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.
AddSOAP12Namespace() adds the SOAP 1.2 encoding, schema and
schema instance namespaces to the document using the optional prefixes
soapPrefix, schemaPrefixPrefix and xsiPrefix.
AddSOAPNamespace() adds the SOAP 1.1 encoding, schema and
schema instance namespaces to the document using the optional prefixes
soapPrefix, schemaPrefixPrefix and xsiPrefix.
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.
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.
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.
method CharsText(text As %String, Output overflow) as %String
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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() 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.
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.
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.
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() 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() 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.
