%XML.Reader

class %XML.Reader extends %Library.RegisteredObject

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.Opens in a new tab See Downloading SamplesOpens in a new tab.

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

Method Inventory

Close()
Correlate()
CorrelateRoot()
Next()
OpenFile()
OpenStream()
OpenString()
OpenURL()
Rewind()

Properties

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

Property methods: CheckRequiredDisplayToLogical(), CheckRequiredGet(), CheckRequiredIsValid(), CheckRequiredLogicalToDisplay(), CheckRequiredNormalize(), CheckRequiredSet()

property Document as %XML.Document;

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

Property methods: DocumentGet(), DocumentGetSwizzled(), DocumentIsValid(), DocumentNewObject()

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

Property methods: EntityResolverGet(), EntityResolverGetSwizzled(), EntityResolverIsValid(), EntityResolverNewObject(), EntityResolverSet()

property Format as %String;

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

Property methods: FormatDisplayToLogical(), FormatGet(), FormatIsValid(), FormatLogicalToDisplay(), FormatLogicalToOdbc(), FormatNormalize(), FormatSet()

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.

Property methods: IgnoreNullDisplayToLogical(), IgnoreNullGet(), IgnoreNullIsValid(), IgnoreNullLogicalToDisplay(), IgnoreNullLogicalToOdbc(), IgnoreNullNormalize(), IgnoreNullSet()

property IgnoreSAXWarnings as %Boolean [ InitialExpression = 0 ];

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

Property methods: IgnoreSAXWarningsDisplayToLogical(), IgnoreSAXWarningsGet(), IgnoreSAXWarningsIsValid(), IgnoreSAXWarningsLogicalToDisplay(), IgnoreSAXWarningsNormalize(), IgnoreSAXWarningsSet()

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.

Property methods: NodeDisplayToLogical(), NodeGet(), NodeIsValid(), NodeLogicalToDisplay(), NodeLogicalToOdbc(), NodeNormalize()

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

Property methods: SAXFlagsDisplayToLogical(), SAXFlagsGet(), SAXFlagsIsValid(), SAXFlagsLogicalToDisplay(), SAXFlagsNormalize(), SAXFlagsSet()

property SAXMask as %Integer [ InitialExpression = $$$SAXCONTENTEVENTS ];

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

Property methods: SAXMaskDisplayToLogical(), SAXMaskGet(), SAXMaskIsValid(), SAXMaskLogicalToDisplay(), SAXMaskNormalize(), SAXMaskSet()

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.

Property methods: SAXSchemaSpecDisplayToLogical(), SAXSchemaSpecGet(), SAXSchemaSpecIsValid(), SAXSchemaSpecLogicalToDisplay(), SAXSchemaSpecLogicalToOdbc(), SAXSchemaSpecNormalize(), SAXSchemaSpecSet()

property SSLConfiguration as %String;

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

Property methods: SSLConfigurationDisplayToLogical(), SSLConfigurationGet(), SSLConfigurationIsValid(), SSLConfigurationLogicalToDisplay(), SSLConfigurationLogicalToOdbc(), SSLConfigurationNormalize(), SSLConfigurationSet()

property Summary as %Boolean [ InitialExpression = 0 ];

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

Property methods: SummaryDisplayToLogical(), SummaryGet(), SummaryIsValid(), SummaryLogicalToDisplay(), SummaryNormalize(), SummarySet()

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.

Property methods: UsePPGHandlerDisplayToLogical(), UsePPGHandlerGet(), UsePPGHandlerIsValid(), UsePPGHandlerLogicalToDisplay(), UsePPGHandlerNormalize(), UsePPGHandlerSet()

Methods

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.

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.

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.

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.

method OpenFile(xmlsource As %String, format As %String) as %Status

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

method OpenStream(xmlsource As %AbstractStream, format As %String) as %Status

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

method OpenString(xmlsource As %String, format As %String) as %Status

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

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)

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.

Subclasses

%XML.Exchange.Reader