SAX

SAX, qui signifie Simple API for XML, est une API d'analyse XML. SAX a été la première API pour XML à connaître le succès en Java, et a ensuite été adaptée dans plusieurs autres environnements de programmation. À partir de Firefox 2, un analyseur SAX est accessible aux applications XUL et aux extensions. Pour plus d'informations, consultez la page d'accueil de SAX.

Pour commencer

Les fonctionnalités d'analyse SAX sont disponibles au travers du composant XML reader. Pour en créer un, utilisez le code suivant :

var xmlReader = Components.classes["@mozilla.org/saxparser/xmlreader;1"]
                          .createInstance(Components.interfaces.nsISAXXMLReader);

Après avoir créé l'analyseur SAX, il est nécessaire de définir des gestionnaires pour les évènements qui vous intéressent, et de déclencher le processus d'analyse. Toutes ces fonctionnalités sont disponibles au travers de l'interface nsISAXXMLReader.

Définition des gestionnaires

Les gestionnaires sont des objets créés par l'utilisateur, implémentant les interfaces de gestion de SAX selon le type d'informations qu'on désire obtenir de l'analyseur. Lorsque le processus d'analyse est lancé, les gestionnaire reçoivent une série d'appels pour le contenu du XML analysé. Les gestionnaires disponibles sont les suivants :

Un exemple d'implémentation des gestionnaires de contenu les plus courants :

function print(s) {
  dump(s + "\n");
}

xmlReader.contentHandler = {
  // nsISAXContentHandler
  startDocument: function() {
    print("startDocument");
  },
  
  endDocument: function() {
    print("endDocument");
  },
  
  startElement: function(uri, localName, qName, /*nsISAXAttributes*/ attributes) {
    var attrs = [];
    for(var i=0; i<attributes.length; i++) {
      attrs.push(attributes.getQName(i) + "='" + 
                 attributes.getValue(i) + "'");
    }

    print("startElement: namespace='" + uri + "', localName='" + 
          localName + "', qName='" + qName + "', attributes={" + 
          attrs.join(",") + "}");
  },
  
  endElement: function(uri, localName, qName) {
    print("endElement: namespace='" + uri + "', localName='" + 
          localName + "', qName='" + qName + "'");
  },
  
  characters: function(value) {
    print("characters: " + value);
  },
  
  processingInstruction: function(target, data) {
    print("processingInstruction: target='" + target + "', data='" + 
          data + "'");
  },
  
  ignorableWhitespace: function(whitespace) {
    // ne pas traiter
  },
  
  startPrefixMapping: function(prefix, uri) {
    // ne pas traiter
  },
  
  endPrefixMapping: function(prefix) {
    // ne pas traiter
  },
  
  // nsISupports
  QueryInterface: function(iid) {
    if(!iid.equals(Components.interfaces.nsISupports) &&
       !iid.equals(Components.interfaces.nsISAXContentHandler))
      throw Components.results.NS_ERROR_NO_INTERFACE;
    return this;
  }
};

Début de l'analyse

Le composant XML Reader peut analyser du XML contenu dans une chaîne, un flux nsIInputStream, ou de manière asynchrone via l'interface nsIStreamListener. Ci-dessous, un exemple d'analyse depuis une chaîne :

xmlReader.parseFromString("<f:a xmlns:f='g' d='1'><BBQ/></f:a>", "text/xml");

Cet appel conduit à la sortie suivante (en supposant qu'on utilise le gestionnaire de contenu de l'exemple ci-dessus) :

startDocument
startElement: namespace='g', localName='a', qName='f:a', attributes={d='1'}
startElement: namespace='', localName='BBQ', qName='BBQ', attributes={}
endElement: namespace='', localName='BBQ', qName='BBQ'
endElement: namespace='g', localName='a', qName='f:a'
endDocument