El API JAXP

Vimos anteriormente que si estamos escribiendo texto como XML, nocesitamos conocer si estamos en una secci�n CDATA. Si lo estamos, los �ngulos (<) y ampersands (&) deber�an salir sin modificar. Pero si no estamos en una secci�n CDATA, deber�an ser reemplazados por las entidades predefinidas &lt; y &amp;. �Pero, c�mo sabemos si estamos procesando una secci�n CDATA?

De la misma forma, si estamos filtrando XML de alguna forma, querr�amos pasar tambi�n los comentarios. Normalmente el analizador ignora los comentarios. �C�mo podemos obtener los comentarios para poder sacarlos por la salida?

Finalmente, est�n las definiciones de entidades del analizador. Si una aplicaci�n de filtrado XML vee una &myEntity; necesita sacar la misma cadena -- no el texto que se inserta en su lugar. �C�mo podemos hacer esto?

Esta p�gina del tutorial responde estas preguntas. Muestra c�mo usar com.sun.xml.parser.LexicalEventListener para identificar comentarios, secciones CDATA y referencias a entidades del analizador

� Nota: Este material es espec�fico de Project X, la implementaci�n de referencia de Sun. El material de esta secci�n no forma parte del est�ndard. En su lugar, representa funcionalidades �tiles que podr�amos necesitar para aprovecharnos hasta que se haya estandarizado alg�n mecanismo equivalente. Como no forma parte del est�ndard JAXP, las funcionalidades descritas aqu� podr�an muy bien no existir en otros analizadores est�ndards JAXP.

Los comentarios, las etiquetas CDATA, y las referencias a entidades del analizador constituyen inform�ci�n l�xica -- es decir, informaci�n que concierte al texto del propio XML, en vez de a la informaci�n contenida en el XML. Por supuesto, a muchas aplicaciones, s�lo les importa el contenido de un documento XML. Dichas aplicaciones no usar�n el API LexicalEventListener. Pero las aplicaciones que sacan texto XML lo encontrar�n muy �til.

�C�mo Funciona LexicalEventListener

Para ser informados cuando el analizador SAX ve informaci�n l�xica, configuramos el analizador con un LexicalEventListener en vez de un DocumentHandler. El interface LexicalEventListener extiende el interface DocumentHandler para a�adirle.

• comment(String comment)
  Pasa comentarios de la aplicaci�n.


• startCDATA(), endCDATA()
  Dicen cuando empieza y termina una secci�n CDATA, lo que le dice a nuestra aplicaci�n que clases de caracteres puede esperar la pr�xima vez que se llame a characters().


• startParsedEntity(String name), EndParsedEntity(String name, Boolean included)
  Obtienen el nombre de una entidad de analizador. El valor booleano included dice si el valor de la entidad fue pasado a la aplicaci�n. Aunque los analizadores con validaci�n tienen que procesar entidades externas, la especificaci�n permite a los analizadores sin validaci�n saltarselas. Este valor nos dice si el analizador sin validaci�n lo hizo o no.

�Trabajar con un LexicalEventListener

En el resto de esta p�gina, convertiremos la aplicaci�n Echo en un oyente de eventos l�xicos y jugaremos con sus caracter�sticas.

Para empezar, a�dimos el c�digo en negrita de abajo para implementar el interface LexicalEventListener y a�adir los m�todos apropiados.

import com.sun.xml.parser.LexicalEventListener;

public class Echo extends HandlerBase
   implements LexicalEventListener
{ 
    ...
        public void processingInstruction (String target, String data)
      ...
    }
     
    public void comment(String text)
              throws SAXException
    {
    }

    public void startCDATA()
              throws SAXException
    {
    }

    public void endCDATA()
              throws SAXException
    {
    }

    public void startParsedEntity(String name)
              throws SAXException
    {
    }

    public void endParsedEntity(String name,
                                boolean included)
              throws SAXException
    {
    }

  private void emit (String s)
    ...

Estos son los �nicos cambios que necesitamos hacer para convertir la clase Echo en un oyente de eventos l�xicos. El analizador chequea el tipo de la clase, y sabe que el "document handler" que especificamos con:

parser.setDocumentHandler ( new Echo() );

es realmente la clase extendida LexicalEventListener.

�Sacar Comentarios

El siguiente paso es hacer algo con uno de los nuevos m�todos. A�adimos el c�digo en negrita de abajo para mostrar los comentarios del fichero XML:

    public void comment(String text)
              throws SAXException
    {
       nl(); emit ("COMMENT: "+text);
    }

Cuando compilamos el programa Echo y lo ejecutamos sobre nuestro fichero XML, el resultado se parece a esto:

COMMENT:  A SAMPLE set of slides  
COMMENT:  
    DTD for a simple "slide show".
COMMENT:  Defines the %inline; declaration 
COMMENT:  ...

Los finales de l�nea en los comentarios son pasados como parte de la cadena de comentarios, normalizados a nuevas l�neas (\n). Tambi�n podemos ver que los comentarios en el DTD son mostrados junto con los comentarios del fichero. (Esto puede crear alg�n problema cuando queremos mostrar s�lo los comentarios del fichero de datos. Para resolver este problema, usamos los m�todos startDTD y endDTD del interface DtdEventListener.)

�Mostrar Otra Informaci�n L�xica

Para finalizar esta secci�n, ejercitaremos los m�todos restantes de LexicalEventHandler.

Hacemos los cambios en negrita de abajo para eliminar la visualizaci�n de comentarios y mostrar los otros eventos.

public void comment(String text)
     throws SAXException
{

  nl(); emit ("COMMENT: "+text);
}

public void startCDATA()
      throws SAXException
{
  nl(); emit ("START CDATA SECTION");
}

public void endCDATA()
      throws SAXException
{
  nl(); emit ("END CDATA SECTION");
}

public void startParsedEntity(String name)
               throws SAXException
{
  nl(); emit ("START PARSED ENTITY: "+name);
}

public void endParsedEntity(String name,
                    boolean included)
             throws SAXException
{
  nl(); emit ("END PARSED ENTITY: "+name);
  emit (", INCLUDED="+included);
}

Aqu� vemos lo que sucede cuando la entidad interna products es procesada con la �ltima versi�n del programa:

ELEMENT: <slide-title>
CHARS:   Wake up to 
START PARSED ENTITY: products
CHARS:   WonderWidgets
END PARSED ENTITY: products, INCLUDED=true
CHARS:   !
END_ELM: </slide-title> 

Y aqu� est� el resultado del procesamiento de la entidad externa copyright:

            START PARSED ENTITY: copyright
            CHARS:   
This is the standard copyright message ...
            END PARSED ENTITY: copyright, INCLUDED=true

Finalmente, obtenemos una salida como est� para la secci�n CDATA:

START CDATA SECTION
CHARS:   Diagram.
         
frobmorten <------------ fuznaten
   |            <3>        ^
   | <1>                   |   <1> = fozzle
   V                       |   <2> = framboze    
staten --------------------+   <3> = frenzle
            <2>

END CDATA SECTION

En suma, el LexicalEventListener nos ofrece las notificaciones de eventos que necesitamos para producir una copia segura del texto XML original.