SAX. cómo funciona? Introducción. La API de análisis basada en eventos

Transcripción

1 La API de análisis basada en eventos César Ignacio García Osorio SAX Introducción SAXReader Las excepciones de SAX ContentHandler: setdocumentlocator, startdocument, enddocument, processinginstruction, startprefixmapping, endprefixmapping,, endelement, characters, ignorablewhitespace Attributes:getLenght, geturi, getlocalname, getrawname, getvalue, gettype ErrorHandler: warning, error, fatalerror EntityResolver: resolveentity Configurar el analizador: setproperty, setfeature, getproperty, getfeature DTDHandler: notationdecl, unparsedentitydecl Otros manipuladores: LexicalHandler, DeclHandler 2 Introducción cómo funciona? SAX es la Simple API for XML. Proporciona una marco basado en eventos para el análisis de datos XML. La API SAX proporciona los medios para analizar un documento XML, pero no el analizador en si mismo. Necesitará encontrar alguno de los analizadores que hay disponibles y que se ajustan a esta API.! Apache Xerces: IBM XML4J: XP de James Clark: OpenXML: Oracle XML Parser: Sun Microsystems Project X: Lark y Larval de Tim Bray: La lectura del documento produce eventos que ocasionen la invocación de métodos. <?xml version="1.0" standalone="no"?> <encuesta target="alumnos"> <!-- un documento XML de ejemplo --> <pregunta> <texto> cuánto estudias a la semana? </texto> <?r-69 confidencial="si"?> <respuestas> <resp>menos de 10 horas</resp> <resp>entre 10 y 20</resp> <resp>mas de 20 horas>/resp> </respuestas> </pregunta> </encuesta> startdocument comment characters endelement processinginstruction characters fatalerror enddocument 3 4

2 Preparándonos Conseguir las clases e interfaces SAX:! Las clases de SAX están empaquetadas en org.xml.sax "17 clases en el directorio org.xml.sax "10 en org.xml.sax.helpers "2 en org.xml.sax.ext Obtener el analizador sintáctico! Vamos a usar el Xerces: Necesitamos el fichero xerces.jar Configurar el entorno Java xercesimpl.jar, xmlparserapis.jar! Actualizar CLASSPATH para localizar xerces.jar Tener un documento XML a mano: receta.xml receta.xml <?xml version="1.0" standalone="no"?> <!DOCTYPE rec:receta SYSTEM "recetans.dtd"> <rec:receta tipo="postre" tiempoprep="15" comensales="5" xmlns:rec = " > <rec:titulo>tarta de queso</rec:titulo> <rec:lista-ingredientes> <rec:item>3 yogures naturales</rec:item> <rec:item>3 huevos</rec:item> <rec:item>una cucharadita de maicena</rec:item> <rec:item>1 tarrina de crema de queso</rec:item> <rec:item>6 cucharadas de azucar</rec:item> </rec:lista-ingredientes> <rec:preparacion> <rec:paso necesario="no">tener a mano todos los ingredientes, la batidora y el recipiente para la tarta.</rec:paso> <rec:paso>batir todos los ingredientes.</rec:paso> <rec:paso>verter en un molde previamente caramelizado y cocer durante 13 minutos en el microondas a toda potencia</rec:paso> <rec:paso necesario="no">servir cubierto de mermelada</rec:paso> <rec:paso necesario="no">&acomer;</rec:paso> </rec:preparacion> </rec:receta> 5 6 Instanciar el Reader Lo primero que necesitamos es obtener una instancia de la clase que implementa la interfaz SAX org.xml.sax.xmlreader En el analizador SAX Xerces esta clase es org.apache.xerces.parsers.saxparser Una clase que implemente esta interfaz llevará a cabo el análisis de un documento de entrada invocando en determinadas situaciones una serie de métodos (agrupados en interfaces) que nosotros podemos modificar según sean las necesidades de la aplicación que queramos desarrollar. import org.xml.sax.xmlreader; // importar la implementación de XMLReader import org.apache.xerces.parsers.saxparser; public class SAXParserDemo { public void ejecutademo(string uri) { System.out.println("Analizando el fichero: " + uri + "\n\n"); // instanciar el analizador (parser) XMLReader parser = new SAXParser(); public static void main(string[] args) { if ( args.length!= 1 ) { System.out.println("Uso: java SAXParserDemo [URI]"); System.exit(0); String uri = arg[0]; SAXParserDemo parserdemo = new SAXPArserDemo(); parserdemo.ejecutademo(uri); 7 8

3 Analizar el documento Una vez cargado el analizador debemos indicarle que analice nuestro documento. Necesitamos añadir el método parse() a nuestro programa, así como dos manipuladores de excepción:! java.io.ioexception: si surgen problemas durante la carga del documento (local o remoto).! org.xml.sax.saxexception: si surgen problemas durante el análisis. El siguiente paso será definir las retrollamadas para decirle a SAX que acciones debe tomar durante el análisis. import java.io.ioexception; SAXDemo1 import org.xml.sax.saxexception; import org.xml.sax.xmlreader; import org.apache.xerces.parsers.saxparser; public void ejecutademo(string uri) { System.out.println("Analizando el fichero: " + uri + "\n\n"); // instanciar el analizador (parser) XMLReader parser = new SAXParser(); // analizar el documento parser.parse(uri); catch (IOException e) { System.out.println("Error al leer URI: " + e.getmessage()); catch (SAXException e) { System.out.println("Error analizando: " + e.getmessage()); 9 10 Los manejadores Son conjuntos de retrollamadas definidas en SAX y que permiten al código de la aplicación intervenir en el proceso de análisis. Para que nuestra aplicación pueda hacer algo útil con los datos XML según se van analizando, debemos registrar manejadores (handler) en el analizador SAX. De este modo el analizador puede invocar durante el análisis las retrollamadas del manejador adecuado Existen cuatro cuatro manejadores:! org.xml.sax.contenthandler se registra con setcontenthandler()! org.xml.sax.errorhandler se registra con seterrorhandler()! org.xml.sax.dtdhandler registrado con setdtdhandler()! org.xml.sax.entityresolver registrado con setentityresolver(). Nuestra aplicación debe proporcionar clases que implementen cada uno de estas interfaces y que lleven a cabo acciones específicas durante el proceso de análisis que proporcionen la funcionalidad a la aplicación. 11 import java.io.ioexception; import org.xml.sax.attributes; import org.xml.sax.contenthandler; import org.xml.sax.locator; import org.xml.sax.saxexception; import org.xml.sax.xmlreader; import org.apache.xerces.parsers.saxparser; class MyContentHandler implements ContentHandler { private Locator locator; public void setdocumentlocator(locator locator) { public void startdocument() public void enddocument() public void processinginstruction(string target, String data) { public void startprefixmapping(string prefix, String uri) { public void endprefixmapping(string prefix) { public void (String namespaceuri, String localname, String qname, Attributes atts) public void endelement(string namespaceuri, String localname, String qname) public void characters(char[] ch, int start, int end){ public void ignorablewhitespace(char[] ch, int start, int end) { public void skippedentity(string name) 12

4 El localizador de documento El primer método que necesitamos definir es el que fija un org.xml.sax.locator para los eventos SAX. Cuando un evento de retrollamada tiene lugar, una clase que implemente el manejador necesitará acceder a la localización dentro del fichero XML donde en esos momentos se encuentra el proceso de análisis. La clase Locator tiene varios métodos útiles como getlinenumber() y getcolumnnumber() que cuando se invocan devuelven la localización actual dentro del fichero XML. /** almacena el locator para poder obtener * la informaci'n de localizaci'on */ private Locator locator; import java.io.ioexception; public void setdocumentlocator(locator locator) { System.out.println("* setdocumentlocator() invocado"); // lo guardamos para su uso posterior this.locator = locator; La SAXException Los métodos de retrollamada pueden lanzar una SAXException. Este es el único tipo de excepción que puede lanzar un evento SAX, proporcionando otro interfaz estándar para el análisis. Esta excepción puede encapsular otras excepciones que pueden ser indicativas del problema acaecido. La clase SAXException proporciona un método, getexception(), que permite recuperar la excepción subyacente. Otras excepciones SAX son:! SAXParsedException! SAXNotRecognizedException! SAXNotSupportedException 15 Comienzo y final del documento El método startdocument()! se llama antes que todas las otras retrollamadas, incluso las de los otros manejadores de SAX,.! se invoca antes que todo el proceso de análisis, salvo por la llamada a setdocumentlocator(). El método enddocument()! es siempre el último método invocado, como antes esto cierto para todos los manipuladores.! si tiene lugar un error no recuperable, se invoca un método de retrollamada de ErrorHandler y a continuación tiene lugar una última invocación a enddocument() que finaliza el proceso de análisis. public void startdocument() System.out.println("Comienza el an'alisis"); public void enddocument() System.out.println(" an'alisis finalizado"); 16

5 Instrucciones de procesado Son un caso especial dentro de XML. No son elementos XML y se manejan de forma distinta cuando se pasan a la aplicación. SAX define para manipularlas una retrollamadas específica que recibe el nombre de objetivo y los datos de la PI. A través de las PIs la aplicación puede recibir instrucciones para fijar valores de variables o ejecutar métodos de procesado específico de la aplicación. La declaración XML no provoca una llamada a este método, dado que se trata de una PI dirigida al analizador y no a la aplicación. public void processinginstruction( String target, String data ) throws SAXException { System.out.println("PI: Objetivo: " + target + " y datos: " + data); 17 Retrollamadas de espacios de nombre En SAX 2.0 se da soporte a los espacios de nombres a nivel de los elementos. Esto permite distinguir entre el espacio de nombre de un elemento, que se materializa en un prefijo con un URI asociado, y el nombre local del elemento (nombre sin el prefijo). Para controlar los espacios de nombre hay dos retrollamadas:! startprefixmapping(): recibe el prefijo así como el URI asociado con ese prefijo. No sigue al funcionamiento secuencial usual de SAX; su invocación tiene lugar inmediatamente antes que la retrollamada para el elemento que declara el espacio de nombres.! endprefixmapping(): la asignación se considera finalizada cuando se cierra el elemento que declaró la asignación; su invocación se produce justo a continuación de la retrollamada de la etiqueta de cierre dicho elemento. public void xmlns:{prefijo="{prefijo" startprefixmapping(string prefix, String uri) { System.out.println("Comienza la asignaci'on de " + prefix + " al URI " + uri); public void endprefixmapping(string prefix) { System.out.println("Finalizada la asignaci'on de " + prefix ); 18 Retrollamadas de elementos La clase Attributes Los tres eventos fundamentales para la obtención de los datos son las retrollamadas de inicio y fin de elemento y las retrollamadas de obtención de datos de carácter. La retrollamada () proporciona a la aplicación información acerca de un elemento XML y cualquiera de los atributos que tenga. Los parámetros de esta retrollamada son:! el URI del espacio de nombre del elemento! el nombre local del elemento! el nombre en bruto (prefijo + nombre local)! una instancia del objeto org.xml.sax.attributes La llamada correspondiente al cierre de un elemento es el método endelement(). La principal razón de ser de esta llamada es informar a la aplicación de que los caracteres que vengan a continuación ya son parte de otro elemento. 19 Esta clase de ayuda contiene referencias a todos los atributos dentro del elemento. Esto hace sencillo el recorrer los atributos del elemento de una forma análoga a como se haría en un Vector. Los métodos que proporciona son:!getlength()!geturi(int index)!getlocalname(int index)!getqname(int index)!gettype(int index)!getvalue(int index)!getindex(string qname)!gettype(string qname)!getvalue(string qname)!getindex(string uri, String localpart)!gettype(string uri, String localname)!getvalue(string uri, String localname) Un punto importante a tener en cuenta es que los atributos se pasan no ordenados, es decir, no se proporcionan exactamente en el mismo orden en el que aparecen en el documento. 20

6 import org.xml.sax.attributes; public void (String namespaceuri, String localname, String qname, Attributes atts) System.out.print( "Comienzo del elemento: " + localname ); if (!namespaceuri.equals("") ) { System.out.println( " en el espacio de nombres " + namespaceuri + "(" + qname + ")" ); else { System.out.println( "no tiene asociado espacio de nombres" ); for (int i=0; i<atts.getlength(); i++) System.out.println( "Atributo: " + atts.getlocalname(i) + "=" + atts.getvalue(i) ); public void endelement(string namespaceuri, String localname, String qname) System.out.println( "Cierre del elemento: " + localname + "\n" ); 21 Datos de un elemento Los datos contenidos dentro un elemento pueden ser elementos adicionales, datos textuales, o una combinación de ambos. Los elementos anidados dentro de elementos dan lugar a retrollamadas anidadas dentro de retrollamadas. Los datos textuales son enviados a la aplicación a través de la retrollamada characters() que proporciona a la aplicación un array de caracteres y dos índices que indica el punto de inicio y de fin de los datos relevantes dentro de dicho array. Para grandes cantidades de datos de carácter el analizador puede elegir pasarlos todos en una única invocación del método characters(), o dividir los datos y pasarlos en varias invocaciones. Los analizadores no validantes pueden informar de los espacios en blanco bien a través de characters(), bien a través de ignorablewhitespace(), los validantes sólo a través del método ignorablewhitespace() que funciona de forma idéntica al método characters(). 22 public void characters(char[] ch, int start, int end) String s = new String(ch, start, end); System.out.println("caracteres: " + s); public void ignorablewhitespace(char[] ch, int start, int end) String s = new String(ch, start, end); System.out.println("espacios ignorables: [" + s + "]"); 23 Registrar el manipulador de contenido Por último, tenemos que registrar nuestro manipulador en el XMLReader que hemos instanciado. Esto se hace con el método setcontenthandler(), que toma una implementación de un ContentHandler como único argumento. public void ejecutademo(string uri) { System.out.println("Analizando el fichero: " + uri + "\n\n"); // Obtiene las instancias de nuestros manipuladores ContentHandler contenthandler = new MyContentHandler(); // Instancia un analizador XMLReader parser = new SAXParser(); // Registra el manipulador de contenido parser.setcontenthandler(contenthandler); SAXDemo2 // Analiza el documento parser.parse(uri); catch (IOException e) { System.out.println("Error al leer URI: " + e.getmessage()); catch (SAXException e) { System.out.println("Error al analizar: " + e.getmessage()); 24

7 El manipulador de errores Para tratar los eventos de análisis, SAX proporciona una interfaz ErrorHandler que puede implementarse para tratar con varios tipos de condiciones de error que puede aparecer durante el análisis. Esta interfaz define tres métodos de retrollamada:! warning: para condiciones de error normalmente relacionadas con la DTD y la validez del documento. Si no estamos validando, nunca tendrá lugar.! error: para errores que no impiden continuar con el análisis, pero constituyen una violación de alguna parte de la especificación XML. Deberían registrarse pero no es necesario informar al usuario, ni finalizar con el análisis.! fatalerror: para tratar los errores que obligan a detener el proceso de análisis. Errores de malformación del documento que hacen que el análisis posterior sea imposible. Se debe informar del error fatal al usuario. Cada método recibe información sobre el error o aviso a través de una SAXParseException. Este objeto contiene el número de línea donde se ha encontrado el problema, el URI del documento que estaba siendo tratado y los datos típicos de una excepción, como el mensaje a emitir y una traza imprimible de la pila. 25 import org.xml.sax.errorhandler; import org.xml.sax.saxparseexception; SAXDemo3 class MyErrorHandler implements ErrorHandler { public void warning(saxparseexception e) System.out.println("**Warning de an'alisis**\n" + " Line: " + e.getlinenumber() + "\n" + " URI: " + e.getsystemid() + "\n" + " Message: " + e.getmessage()); throw new SAXException("Se ha encontrado un warning"); public void error(saxparseexception e) public void fatalerror(saxparseexception e).. // Obtiene las instancias del manipulador ErrorHandler errorhandler = new MyErrorHandler(); // Registra el manipulador de errores parser.seterrorhandler(errorhandler); catch (IOException e) { 26 Una forma mejor de cargar el analizador El código desarrollado hasta ahora tiene un problema. Hemos importado de forma explícita la implementación del XMLReader, y a continuación la hemos instanciado de forma directa. De este modo nuestro código adolece de un problema de portabilidad. Una mejor forma de obtener la instancia de una clase es a través del nombre de la clase de implementación. Esto permite que se pueda cambiar de forma sencilla un parámetro String en nuestro código (o incluso recibir el valor como un argumento de la línea de comandos o leyéndolo de un fichero de configuración). En SAX 2.0 la clase org.xml.sax.helpers.xmlreaderfactory proporciona un método para hacer esto. SAXDemo4 import org.xml.sax.xmlreader; import org.xml.sax.helpers.xmlreaderfactory; // esto ya no es necesario //import org.apache.xerces.parsers.saxparser; // Instanciar el analizador XMLReader parser = XMLReaderFactory.createXMLReader( "org.apache.xerces.parsers.saxparser"); catch { 27 28

8 Tratar con entidades Cuando en el documento XML aparece una referencia entidad que no es tenida en cuenta por un analizador de no validación, SAX 2.0 usa la retrollamada skippedentity del ContentHandler. La retrollamada tiene como argumento el nombre de la entidad. En SAX 2.0 se define además una interfaz, EntityResolver. Si nuestra aplicación necesita intervenir en el proceso de resolución de entidades externas, deberá implementar dicha interfaz y registrarla usando el método setentityresolver. El método resolveentity de la interfaz EntityResolver permite a la aplicación resolver las entidades externas. El analizador invocará este método antes de abrir una entidad externa (incluida la DTD externa). El escritor de la aplicación puede usar este método para redireccionar un identificador de sistema externo a un URI local, buscar el identificador público en un catálogo, o leer la entidad de una base de datos u otra fuente de entrada (incluida un cuadro dialogo). public void skippedentity(string name) System.out.println("Omitiendo la entidad " + name); import org.xml.sax.entityresolver; import org.xml.sax.inputsource; public class MiResolver implements EntityResolver { public InputSource resolveentity (String pubid, String sysid) throws SAXException, java.io.ioexception { if (pubid.equals("-//cgosorio//dtd receta//es")) { // devuelve un InputSource a una DTD local java.io.file f = new java.io.file("dtds/receta.dtd"); InputSource inso = new InputSource( f.tourl().tostring() ); inso.setpublicid(pubid); return inso; else // usar el funcionamiento por defecto return null; Configurar el analizador Para la configuración del analizador, SAX 2.0 define un mecanismo estándar para dar valor a determinadas propiedades y características del mismo.! Una propiedad (property) requiere de algún objeto arbitrario para ser usado.! Una característica (feature) es una bandera (flag) usada por el analizador para indicar si cierto tipo de procesamiento va a tener lugar. Algunas de las características más comunes son: la validación, el soporte de espacio de nombres, la inclusión de entidades de parámetro externas. Los métodos para establecer y consultar estas propiedades y características de la interfaz XMLReader son:! Object getproperty(string nombre): Busca el valor de una propiedad.! void setproperty(string nombre, Object valor): Establece el valor de la propiedad.! boolean getfeature(string nombre): Busca el valor de una característica.! void setfeature(string nombre, boolean valor): Establece la característica. 31 Configurar el analizador Para cada uno de estos métodos el identificador o nombre de la característica o propiedad específica es un URI. Estos URIs son similares a los URIs de los espacios de nombres, sólo se usan como asociaciones con características o propiedades particulares, esto quiere decir que no es necesario tener acceso a la red; se trata simplemente de constantes con forma de URI. Además estos métodos pueden lanzar dos excepciones (extensiones de la SAXException):! SAXNotRecognizedException: Cuando el XMLReader no reconoce el nombre de la característica! SAXNotSupportedException: Cuando el XMLReader reconoce el nombre pero no puede determinar su valor en ese momento. 32

9 XMLReader r = new MiDriverSAX(); // intentar activar la validaci'on r.setfeature(" true); catch (SAXException e) { System.err.println("Imposible establecer validaci'on."); // registrar los manipuladores de eventos r.setcontenthandler(new MiManipuladorDeContenido ()); r.seterrorhandler(new MiManipuladorDeErrores()); // registrar un manipulador l'exico r.setproperty(" new MiManipuladorLexico() ); catch (SAXException e) { System.err.println("Imposible registrar manipulador l'exico."); // analizar el documento r.parse(" catch (IOException e) { catch (SAXException e) { 33 La interfaz DTDHandler Esta interfaz recibe notificaciones de eventos básicos relacionados con la DTD. Si se necesita información sobre notaciones y sobre entidades no analizadas, debe implementarse esta interfaz y registrar una instancia de la misma en el analizador SAX usando el método setdtdhandler. El orden con el que el analizador SAX notifica a la aplicación las declaraciones de notación y de entidad no tiene porque coincidir con el orden en que estas aparecen en la DTD, pero todos los eventos de la DTD deben tener lugar después del evento startdocument y antes del primer evento. Es responsabilidad de la aplicación almacenar esa información para su uso posterior (quizás usando una tabla de dispersión o un objeto árbol). Si la aplicación encuentra atributos de tipo NOTATION, ENTITY o ENTITIES puede usar la información almacenada para encontrar la entidad o la notación que se corresponde con el valor del atributo. Los métodos proporcionados por esta interfaz son:! void notationdecl(string name, String publicid, String systemid)! void unparsedentitydecl(string name, String publicid, String systemid, String notationname) 34 La interfaz LexicalHandler La interfaz DeclHandler Una extensión opcional de SAX2 que informa de los comentarios, las declaraciones DOCTYPE, las secciones CDATA y algunos límites de entidad. No es obligatorio que un analizador SAX soporte esta interfaz. Los eventos del manipulador léxico se disparan para la totalidad del documento (no únicamente para la entidad de documento) y tienen lugar entre los eventos startdocument y enddocument. Para establecer el LexicalHandler se usa el método setproperty y el nombre " Los métodos de esta interfaz son:! void comment(char[] ch, int start, int length)! void endcdata()! void enddtd()! void endentity(string name)! void startcdata()! void startdtd(string name, String publicid, String systemid)! void startentity(string name) 35 Otra extensión opcional de SAX2, informa de las declaraciones en la DTD. No es obligatorio que un analizador SAX soporte esta interfaz. Obsérvese que algunos que algunas declaraciones de la DTD (las de notaciones y entidades no analizadas) ya se pasan a través de la interfaz DTDHandler. Si se esta usando la DeclHandler junto con la LexicalHandler todos los eventos tendrán lugar entre los eventos startdtd y enddtd. Para establecer el DeclHandler se usa el método setproperty y el nombre " Los métodos de esta interfaz son:! void attributedecl(string ename, String aname, String type, String valuedefault, String value)! void elementdecl(string name, String model)! void externalentitydecl(string name, String pubid, String sysid)! void internalentitydecl(string name, String value) SAXDemo5 36