Skip to main content

%XML.SAX.ContentHandler

Class %XML.SAX.ContentHandler Extends %RegisteredObject [ Abstract, Not ProcedureBlock, System = 2 ]

For details on using this class, see Customizing How the SAX Parser Is Used.

This class defines the interface that a SAX document handler must implement. The SAX parser calls these methods while it parses a document. The default implementation of these methods is to do nothing; you can override these methods in a subclass to perform processing specific to your application.

Properties​

HandlerType​

Property HandlerType As %Integer [ InitialExpression = {$$$ClsHandler}, Internal ];

The type of content handler. If the value of this property is changed to $$$IntHandler, then the internal content handler is used that creates the proprietary DOM directly in the global named by GlobalName

KeepWhitespace​

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

Flag to keep whitespace. Used only when HandlerType is set to $$$IntHandler

GlobalName​

Property GlobalName As %String [ Internal ];

Name of global to write to. Used only when HandlerType is set to $$$IntHandler or $$$LocHandler

controlblock​

Property controlblock As %String [ Internal ];

Parser control block. Used only when HandlerType is set to $$$LocHandler

Methods​

OnPostParse​

Method OnPostParse() As %Status

Callback after XML parse complete.

LocatePosition​

Method LocatePosition(ByRef Line As %Integer, ByRef Offset As %Integer) As %Library.Status [ Final ]

Locate the current position within the parsed document.

  • Line: The current line position
  • Offset: The current line offset

Note: This method should ONLY be called during a parse, typically from the error related callbacks. Attempts to call at any other time will result in the ERROR #6019: Attempt to find location failed

PopHandler​

Method PopHandler() As %Status [ Final ]

Return to the previous handler.

PushHandler​

Method PushHandler(Handler As %XML.SAX.ContentHandler) As %Status [ Final ]

Push a new handler on the stack. Then all subsequent callbacks from SAX will goto this new handler. When this handler is finished processing its piece of the XML it will call PopHandler which will go back to its previous handler.

characters​

Method characters(chars As %Library.String, length As %Library.Integer)

Receive notification of character data inside an element.

By default, do nothing. Application writers may override this method to take specific actions for each chunk of character data (such as adding the data to a node or buffer, or printing it to a file).

  • chars: The characters.
  • length: The number of characters to use from the character array.

comment​

Method comment(chars As %String, length As %Integer)

Receive notification of comments.

The Parser will call this method to report each occurence of a comment in the XML document.

The application must not attempt to read from the array outside of the specified range.

  • chars: The characters from the XML document.
  • length: The number of characters to read from the array.

Exceptions thrown: SAXException - Any SAX exception, possibly wrapping another exception.

endCDATA​

Method endCDATA()

Receive notification of the end of a CDATA section.

The SAX parser will invoke this method at the end of each CDATA parsed.

Exceptions thrown: SAXException - Any SAX exception, possibly wrapping another exception.

/

endDTD​

Method endDTD()

Receive notification of the end of the DTD declarations.

The SAX parser will invoke this method at the end of the DTD

Exceptions thrown: SAXException - Any SAX exception, possibly wrapping another exception.

/

endDocument​

Method endDocument()

Receive notification of the end of the document.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the beginning of a document (such as finalising a tree or closing an output file).

endElement​

Method endElement(uri As %Library.String, localname As %Library.String, qname As %Library.String)

Receive notification of the end of an element.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the end of each element (such as finalising a tree node or writing output to a file).

  • uri: The URI of the associated namespace for this element
  • localname: The local part of the element name
  • qname: The QName of this element

endEntity​

Method endEntity(name As %String)

Receive notification of the end of an entity.

The SAX parser will invoke this method at the end of an entity

  • name: The name of the entity that is ending.

Exceptions thrown: SAXException - Any SAX exception, possibly wrapping another exception.

endPrefixMapping​

Method endPrefixMapping(prefix As %Library.String)

Receive notification of the end of an namespace prefix mapping.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the end of each namespace prefix mapping.

  • prefix: The namespace prefix used

error​

Method error(error As %Library.String)

Receive notification of a recoverable parser error.

The default implementation does nothing. Application writers may override this method in a subclass to take specific actions for each error, such as inserting the message in a log file or printing it to the console.

  • error: The error information encoded as a string

fatalError​

Method fatalError(fatalerror As %Library.String)

Report a fatal XML parsing error.

The default implementation throws an exeption Application writers may override this method in a subclass if they need to take specific actions for each fatal error (such as collecting all of the errors into a single report): in any case, the application must stop all regular processing when this method is invoked, since the document is no longer reliable, and the parser may no longer report parsing events.

  • fatalerror: The error information encoded as a string

ignorableWhitespace​

Method ignorableWhitespace(chars As %Library.String, length As %Library.Integer)

Receive notification of ignorable whitespace in element content.

By default, do nothing. Application writers may override this method to take specific actions for each chunk of ignorable whitespace (such as adding data to a node or buffer, or printing it to a file).

  • chars: The whitespace characters.
  • length: The number of characters to use from the character array.

processingInstruction​

Method processingInstruction(target As %Library.String, data As %Library.String)

Receive notification of a processing instruction in element content.

Application writers may override this method in a subclass if they need to take specific actions for processing instruction.

  • target: The target of the processing instruction
  • data: The associated data

skippedEntity​

Method skippedEntity(name As %Library.String)

Receive notification of a skipped entity

The parser will invoke this method once for each entity skipped. All processors may skip external entities, depending on the values of the features:

http://xml.org/sax/features/external-general-entities
http://xml.org/sax/features/external-parameter-entities

Introduced with SAX2

  • name: The name of the skipped entity. If it is a parameter entity, the name will begin with %, and if it is the external DTD subset, it will be the string [dtd].

startCDATA​

Method startCDATA()

Receive notification of the start of a CDATA section.

The SAX parser will invoke this method at the start of each CDATA parsed.

Exceptions thrown: SAXException - Any SAX exception, possibly wrapping another exception.

startDTD​

Method startDTD(name As %String, publicId As %String, systemId As %String)

Receive notification of the start of the DTD declarations.

The SAX parser will invoke this method at the start of the DTD

  • name: The document type name.
  • publicId: The declared public identifier for the external DTD subset, or null if none was declared.
  • systemId: The declared system identifier for the external DTD subset, or null if none was declared.

Exceptions thrown: SAXException - Any SAX exception, possibly wrapping another exception.

startDocument​

Method startDocument()

Receive notification of the beginning of the document.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the beginning of a document (such as allocating the root node of a tree or creating an output file)

startElement​

Method startElement(uri As %Library.String, localname As %Library.String, qname As %Library.String, attrs As %Library.List)

Receive notification of the start of an element.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the start of each element (such as allocating a new tree node or writin output to a file).

  • uri: The URI of the associated namespace for this element
  • localname: the local part of the element name
  • qname: the QName of this element
  • attrs: a list in $List format consisting of a repeating group of attributes.

The format of the repeating group is as follows:

  • +0 - uri: The URI of the associated namespace for this attribute
  • +1 - localname: The local part of the name of this attribute
  • +2 - qname: The QName of this attribute
  • +3 - type: The type of this attribute ("CDATA", NMTOKEN", "ENTITY", etc.)
  • +4 - value: The value of this attribute

startEntity​

Method startEntity(name As %String)

Receive notification of the start of an entity.

The SAX parser will invoke this method at the start of an entity

  • name: The name of the entity that is starting.

Exceptions thrown: SAXException - Any SAX exception, possibly wrapping another exception.

startPrefixMapping​

Method startPrefixMapping(prefix As %Library.String, uri As %Library.String)

Receive notification of the start of an namespace prefix mapping.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the start of each namespace prefix mapping.

  • prefix: The namespace prefix used
  • uri: The namespace URI used.

warning​

Method warning(warning As %Library.String)

Receive notification of a parser warning.

The default implementation does nothing. Application writers may override this method in a subclass to take specific actions for each warning, such as inserting the message in a log file or printing it to the console.

  • warning: The warning information encoded as a string

Mask​

Method Mask() As %Integer [ CodeMode = generator, ProcedureBlock = 1 ]

Calculate MASK for call to xerces parser. The mask is calculated from the overriden content handling methods.

Buffer​

Method Buffer(pList As %List) [ Internal ]

In buffered mode, callback with a list containing parsed data. It is the responsibility of the subclass to decode this list and act appropriately