Class: SAXParser

$.util. SAXParser

Class for parsing XML. It is based on expat.

new SAXParser()

Example
//parse XML from String
var parser = new $.util.SAXParser();
var xml = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n\
          <!-- this is a note -->\n\
          <notes>\n\
              <note noteName="My first note">\n\
                  <to>To\n\
                  <from>From\n\
                  <date timezone="UTC">Thu, 09 Jul 2015 08:42:44\n\
                  <subject>Note subject\n\
                  <body contentType="text/plain">Note body	





\n\
              </note>\n\
              <note noteName="My second note">\n\
                  <to>To\n\
                  <from>From\n\
                  <date timezone="UTC">Fri, 10 Jul 2015 09:00:00\n\
                  <subject>Note subject\n\
                  <body>Note body\n\
              </note>\n\
          </notes>\n';

var rootElement;
var characterData = [];
var elementStack = [];

parser.startElementHandler = function(name, attrs) {
  var data = attrs; // use attrs object with all properties as template
  data.name = name; // add the name to the object

  if(!rootElement) { // the first element we see is the root element we want to send as response
     rootElement = data;
  } else {
     var currentElement = elementStack[elementStack.length - 1];
     if(!currentElement.children) { // first time we see a child we have to create the children array
       currentElement.children = [ data ];
     } else {
       currentElement.children.push(data)
     }
  }
  elementStack.push(data);
};

parser.endElementHandler = function(name) {
  elementStack.pop();
};

parser.characterDataHandler = function(s) {
  var currentElement = elementStack[elementStack.length - 1];
  if (!currentElement.characterData) { // the first time we see char data we store it as string
     currentElement.characterData = s;
  } else if (!Array.isArray(currentElement.characterData)) { // if we already have a string we convert it to an array and append the new data
     currentElement.characterData = [currentElement.characterData, s];
  } else { // just append new data to the existing array
     currentElement.characterData.push(s);
  }
};

parser.parse(xml);

$.response.contentType = "application/json";
$.response.setBody(JSON.stringify({
  rootElement: rootElement,
  characterData: characterData
}));

Members

attlistDeclHandler :function

This property holds a callback function with the following parameters: elname(String), attname(String), att_type(String), dflt(String) and isrequired(Integer).
Type:
  • function
Example
parser.attlistDeclHandler = function(elname, attname, att_type, dflt, isrequired) {
    // do some thing
}

characterDataHandler :function

This property holds a callback function with one parameter: s(String).
Type:
  • function
Example
parser.characterDataHandler = function(s) {
    // do some thing
}

commentHandler :function

This property holds a callback function with one parameter: data(String).
Type:
  • function
Example
parser.commentHandler = function(data) {
    // do some thing
}

currentByteIndex :Integer

This property holds the current byte index of the parser
Type:
  • Integer

currentColumnNumber :Integer

This property holds the current column position of the parser
Type:
  • Integer

currentLineNumber :Integer

This property holds the current line position of the parser
Type:
  • Integer

endCDataSectionHandler :function

This property holds a callback function with no parameters.
Type:
  • function
Example
parser.endCDataSectionHandler = function() {
    // do some thing
}

endDoctypeDeclHandler :function

This property holds a callback function with no parameters.
Type:
  • function
Example
parser.endDoctypeDeclHandler = function() {
    // do some thing
}

endElementHandler :function

This property holds a callback function with one parameter: name(String).
Type:
  • function
Example
parser.endElementHandler = function(name) {
    // do some thing
}

endNameSpaceDeclHandler :function

This property holds a callback function with one parameter: prefix(String).
Type:
  • function
Example
parser.endNameSpaceDeclHandler = function(prefix) {
    // do some thing
}

entityDeclHandler :function

This property holds a callback function with seven parameters: entityName(String), is_parameter_entity(Integer), value(String), systemId(String), publicId(String) and notationName(String).
NOTE: During parsing it is the application's responsibility to prevent large number of multiple XML entity expansions.
Type:
  • function
Example
parser.entityDeclHandler = function(entityName, is_parameter_entity, value, systemId, publicId, notationName) {
    // do some thing
}

externalEntityRefHandler :function

This property holds a callback function with four parameters: context(String), systemId(String) and publicId(String).
Type:
  • function
Example
parser.externalEntityRefHandler = function(context, systemId, publicId) {
    // do some thing
}

notationDeclHandler :function

This property holds a callback function with four parameters: notationName(String), systemId(String) and publicId(String).
Type:
  • function
Example
parser.notationDeclHandler = function(notationName, systemId, publicId) {
    // do some thing
}

processingInstructionHandler :function

This property holds a callback function with two parameters: target(String) and data(String).
Type:
  • function
Example
parser.processingInstructionHandler = function(target, data) {
    // do some thing
}

startCDataSectionHandler :function

This property holds a callback function with no parameters.
Type:
  • function
Example
parser.startCDataSectionHandler = function() {
    // do some thing
}

startDoctypeDeclHandler :function

This property holds a callback function with four parameters: doctypeName(String), sysid(String), pubid(String) and has_internal_subset(Integer).
Type:
  • function
Example
parser.startDoctypeDeclHandler = function(doctypeName, sysid, pubid, has_internal_subset) {
    // do some thing
}

startElementHandler :function

This property holds a callback function with two parameters: name(String) and atts(Object). atts contains key:value pairs of the attributes.
Type:
  • function
Example
parser.startElementHandler = function(name, atts) {
    // do some thing
}

startNameSpaceDeclHandler :function

This property holds a callback function with two parameters: prefix(String) and uri(String).
Type:
  • function
Example
parser.startNameSpaceDeclHandler = function(prefix, uri) {
    // do some thing
}

xmlDeclHandler :function

This property holds a callback function with three parameters: version(String), encoding(String), standalone(Integer).
Type:
  • function
Example
parser.xmlDeclHandler = function(version, encoding, standalone) {
    // do some thing
}

Methods

parse(xml)

This method parses the xmlString.
Parameters:
Name Type Description
xml String data that should be parsed
Throws:
Throws an error if there was a problem during parsing or the parser was stopped without the possibility of resuming
Example
var xmlString = //Some xml
var parser = new $.util.SAXParser()

//... set handlers

parser.parse(xmlString);

parse(xml, encoding)

This method parses the xmlArrayBuffer.
Parameters:
Name Type Argument Description
xml ArrayBuffer data that should be parsed
encoding String <optional>
 supported encodings are UTF-8, UTF-16 and US-ASCII. The default is UTF-8.
Throws:
Throws an error if there was a problem during parsing or the parser was stopped without the possibility of resuming
Example
var xmlArrayBuffer = //Some xml
var parser = new $.util.SAXParser()

//... set handlers

parser.parse(xmlArrayBuffer);

parse(xml, encoding)

This method parses the content of a $.web.Body object.
Parameters:
Name Type Argument Description
xml $.web.Body data that should be parsed. The body should contain the XML. Otherwise the parser throws an error.
encoding String <optional>
 supported encodings are UTF-8, UTF-16 and US-ASCII. The default is UTF-8.
Throws:
Throws an error if there was a problem during parsing or the parser was stopped without the possibility of resuming
Example
var body = $.request.body
var parser = new $.util.SAXParser()

//... set handlers

parser.parse(body);

reset()

This method resets the parser.
Example
var parser = new $.util.SAXParser()
// ...
parser.parse(xmlString1);
parser.reset();
parser.parse(xmlString2);

resume()

This method resumes the parser. It should not be called from a callback function.
Example
var parser = new $.util.SAXParser()
parser.startElementHandler = function(name, atts) {
    //... some logic here
    parser.stop(true);
    //...
}
parser.parse(xmlString);
parser.startElementHandler = function(name, atts) {
    //... some other logic here
}
parser.resume();

stop(isResumable)

This method stops the parser. It should be called from a callback function.
Parameters:
Name Type Description
isResumable Boolean if true than when called the parser is suspended and can be resumed. If false the parser cannot be resumed and an error is thrown.
Throws:
Throws an error if isResumable = false
Example
var parser = new $.util.SAXParser()
parser.startElementHandler = function(name, atts) {
    //... some logic here
    parser.stop(false);
    //...
}
try {
    parser.parse(xmlString);
} catch(error) {
    // handle parser.stop(false) error
}