%XML.Reader

Class %XML.Reader Extends %RegisteredObject [ System = 2 ]

For details on using this class, see Importing XML into Objects.

The sample class mentioned here (Sample.Person) is part of https://github.com/intersystems/Samples-Data. See Downloading Samples.

XML Objects Reader class. A usage example follows: #include %occStatus // Create a new XML Reader class Set reader = ##class(%XML.Reader).%New() // Begin processing of the XML input Set sc=reader.OpenFile(filename) If $$$ISERR(sc) Do $system.OBJ.DisplayError(sc) Quit // Associate a class name with the XML element name Do reader.Correlate("Person","Sample.Person") // read Sample.Person objects from xml file Set Count=0 While reader.Next(.person,.sc) { Write person.Name_" imported.",! Set Count=Count+1 Set sc=person.%Save() If $$$ISERR(sc) Do $system.OBJ.DisplayError(sc) Quit } If $$$ISERR(sc) Do $system.OBJ.DisplayError(sc) Quit Write Count_" Sample.Person instances found."

Properties

Format

Property Format As %String;

The format of the XML document: "literal", "encoded" or "encoded12". This parameter may be overriden by the Open... format parameter.

IgnoreNull

Property IgnoreNull As %String [ InitialExpression = 0 ];

The runtime specification of the XMLIGNORENULL parameter to %XML.Adaptor. IgnoreNull specifies the value of XMLIGNORENULL at runtime as either 0, 1 or inputonly. IgnoreNull="inputonly" is equivalent to IgnoreNull=1.

Summary

Property Summary As %Boolean [ InitialExpression = 0 ];

If true (1), then only the summary fields should be imported by the %XML.Adaptor.

CheckRequired

Property CheckRequired As %Boolean [ InitialExpression = 0 ];

Checking the existence of REQUIRED properties is off by default in %XML.Reader. To turn on REQUIRED property checking. set the CheckRequired property to 1 (default is 0).

SAXFlags

Property SAXFlags As %Integer [ InitialExpression = {$$$SAXFULLDEFAULT} ];

This property should be set to a combination of flags (see %occSAX.inc for details) if the default behavior of the parser is required to be modified

SAXMask

Property SAXMask As %Integer [ InitialExpression = {$$$SAXCONTENTEVENTS} ];

The SAXMask property is kept for compatibility only. The best mask is now computed and this property ignored.

SAXSchemaSpec

Property SAXSchemaSpec As %String;

This property specifies the schema specifications that should be used when validating the document. See %XML.SAX.Parser for a full description of this property.

EntityResolver

Property EntityResolver As %XML.SAX.EntityResolver;

This property should be set to an instance of %XML.SAX.EntityResolver OR a user-defined subclass IF the default EntityResolver is not required

SSLConfiguration

Property SSLConfiguration As %String;

The name of the activated TLS/SSL configuration to use for https requests by the entity resolver.

IgnoreSAXWarnings

Property IgnoreSAXWarnings As %Boolean [ InitialExpression = 0 ];

If true (1), then any warnings from the SAX parser will be not be reported and ignored.

UsePPGHandler

Property UsePPGHandler As %Boolean;

If UsePPGHandler is true (1), then force document parsing to use PPG memory. If UsePPGHandler is false (0), then force document parsing to use local array memory. If UsePPGHandler is not set ( or = ""), then use default memory -- usually local array memory.

Node

Property Node As %String [ InitialExpression = 0 ];

Current node in tree representation of XML document. Note that 0 means the document itself, i.e. the parent of the root element.

Childlist

Property Childlist As %String [ Internal, Private ];

Childlist associated with current element node

Descriptor

Property Descriptor As %String [ Internal, Private ];

Descriptor associated with current node

ParentNodeId

Property ParentNodeId As %String [ Internal, Private ];

NodeId of parent

ParentChildlist

Property ParentChildlist As %String [ Internal, Private ];

Childlist of parent

ParentDescriptor

Property ParentDescriptor As %String [ Internal, Private ];

Descriptor of parent

NodeIsCurrent

Property NodeIsCurrent As %Boolean [ Internal, Private ];

NodeisCurrent is true if the current node value has just been set to the next node to process.

OpenFormat

Property OpenFormat As %String [ Private ];

The internal format to be used for XMLImport. This property is set during Open.

Document

Property Document As %XML.Document;

The %XML.Document that holds the parsed XML document.

KeepWhitespace

Property KeepWhitespace As %Boolean [ InitialExpression = 1, Internal ];

Flag to keep whitespace. Used only when HandlerType is set to $$$IntHandler Default is true as required by XMLImport processing.

Idlist

Property Idlist As %String [ Internal, MultiDimensional, Private ];

The list of nodes that have already imported with id attribute.

CorrelationTable

Property CorrelationTable As %String [ Internal, MultiDimensional ];

This is the class to XML element correlation. To correlate a class to an element, call ..Correlate(,). Element names are unique but you can correlate more than one element to the same class. On import, if an element is not correlated to a class then it will be skipped by ..Next(). 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.

Methods

NodeSet

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

DocumentSet

Method DocumentSet(document As %XML.Document) As %Status [ Internal ]

Close

Method Close()

Close and cleanup the %XML.Document. This method is included for backward compatibility. The %XML.Document will be cleaned up anyway during object cleanup.

Rewind

Method Rewind()

Restart reading at the beginning of the XML document. All correlations are cleared and Correlate must be called again for the required elements.

Correlate

Method Correlate(element As %String, class As %String, namespace As %String)

Correlate() defines an XML Element to class correlation. Any elements encountered by Next() that are in the correlation table will cause the correlated class to be instantiated and its XMLImport method to be called with the current XML node passed as a parameter. Further examination of child nodes is skipped for correlated elements.

Matching of elements is based on the element name that is specified in the element argument. If the namespace argument is also specified, then the XML namespace of the element must also match.

CorrelateRoot

Method CorrelateRoot(class As %String)

CorrelateRoot defines the root element to be correlated to the specified class. The root element when encountered by Next() will cause the correlated class to be instantiated and its XMLImport method to be called with the root XML node passed as a parameter. Further examination of child nodes is skipped for correlated elements.

Next

Method Next(ByRef oref As %ObjectHandle, ByRef sc As %Status, namespace As %String = "") As %Integer

Get and return the next object.

Next returns 1 (true), if the next object matching one of the Correlate criteria is found and successfully imported.
Next returns 0 (false) and a %Status of $$$OK in sc after all objects have been imported.
Next returns 0 (false) and an error %Status in sc, if an error has occurred importing this object.

The namespace argument indicates the default namespace for this XML file.

GetNewDocument

ClassMethod GetNewDocument(usePPGHandler As %Boolean) As %XML.Document [ Internal ]

Internal method to get the appropriate document handler base on the UsePPGHandler property.

Open

Method Open(xmlsource, method As %String, format As %String, httprequest As %Net.HttpRequest) As %Status [ Internal, Private ]

Import XML source from a file (method="ParseFile"), stream (method="ParseStream") or string (method="ParseString"). Open() invokes the SAX parser to construct the XML tree using the %XML.Document, and initializes the iterator. We assume that elements have been already correlated to class names.

OpenFile

Method OpenFile(xmlsource As %String, format As %String) As %Status

Import XML source from a file using %XML.Document.

OpenStream

Method OpenStream(xmlsource As %AbstractStream, format As %String) As %Status

Import XML source from a stream object using %XML.Document.

OpenString

Method OpenString(xmlsource As %String, format As %String) As %Status

Import XML source from a string using %XML.Document.

OpenURL

Method OpenURL(xmlsource As %String, format As %String, httprequest As %Net.HttpRequest = "") As %Status

Import XML source from a URL using %XML.Document. If httprequest argument is specified, then this will be used as the %Net.HttpRequest object to open the URL.

To open https URLs: set reader=##class(%XML.Reader).%New() set httprequest=##class(%Net.HttpRequest).%New() set httprequest.SSLConfiguration="...." set status=reader.OpenURL("https://.....",,httprequest)

OpenBuffer

Method OpenBuffer(xmlsource As %List, format As %String) As %Status [ Internal ]

NOTE: For InterSystems internal use only!!!

ResolveElement

Method ResolveElement(element As %String, defaultNamespace As %String) As %String [ Internal ]

ResolveElement() returns the class name corresponding to an element name within the current XMLReader context.