1. // LexicalHandler.java - optional handler for lexical parse events.

  2. // Public Domain: no warranty.

  3. // $Id: LexicalHandler.java,v 1.1 2001/05/20 03:12:57 curcuru Exp $

  4. 

  5. package org.xml.sax.ext;

  6. 

  7. import org.xml.sax.SAXException;

  8. 

  9. /**

  10.  * SAX2 extension handler for lexical events.

  11.  *

  12.  * <blockquote>

  13.  * <em>This module, both source code and documentation, is in the

  14.  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>

  15.  * </blockquote>

  16.  *

  17.  * <p>This is an optional extension handler for SAX2 to provide

  18.  * lexical information about an XML document, such as comments

  19.  * and CDATA section boundaries; XML readers are not required to 

  20.  * support this handler, and it is not part of the core SAX2

  21.  * distribution.</p>

  22.  *

  23.  * <p>The events in the lexical handler apply to the entire document,

  24.  * not just to the document element, and all lexical handler events

  25.  * must appear between the content handler's startDocument and

  26.  * endDocument events.</p>

  27.  *

  28.  * <p>To set the LexicalHandler for an XML reader, use the

  29.  * {@link org.xml.sax.XMLReader#setProperty setProperty} method

  30.  * with the propertyId "http://xml.org/sax/properties/lexical-handler".

  31.  * If the reader does not support lexical events, it will throw a

  32.  * {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}

  33.  * or a

  34.  * {@link org.xml.sax.SAXNotSupportedException SAXNotSupportedException}

  35.  * when you attempt to register the handler.</p>

  36.  *

  37.  * @since 1.0

  38.  * @author David Megginson, 

  39.  *         <a href="mailto:sax@megginson.com">sax@megginson.com</a>

  40.  * @version 1.0

  41.  * @see org.xml.sax.XMLReader#setProperty

  42.  * @see org.xml.sax.SAXNotRecognizedException

  43.  * @see org.xml.sax.SAXNotSupportedException

  44.  */

  45. public interface LexicalHandler

  46. {

  47. 

  48.     /**

  49.      * Report the start of DTD declarations, if any.

  50.      *

  51.      * <p>This method is intended to report the beginning of the

  52.      * DOCTYPE declaration; if the document has no DOCTYPE declaration,

  53.      * this method will not be invoked.</p>

  54.      *

  55.      * <p>All declarations reported through 

  56.      * {@link org.xml.sax.DTDHandler DTDHandler} or

  57.      * {@link org.xml.sax.ext.DeclHandler DeclHandler} events must appear

  58.      * between the startDTD and {@link #endDTD endDTD} events.

  59.      * Declarations are assumed to belong to the internal DTD subset

  60.      * unless they appear between {@link #startEntity startEntity}

  61.      * and {@link #endEntity endEntity} events.  Comments and

  62.      * processing instructions from the DTD should also be reported

  63.      * between the startDTD and endDTD events, in their original 

  64.      * order of (logical) occurrence; they are not required to

  65.      * appear in their correct locations relative to DTDHandler

  66.      * or DeclHandler events, however.</p>

  67.      *

  68.      * <p>Note that the start/endDTD events will appear within

  69.      * the start/endDocument events from ContentHandler and

  70.      * before the first 

  71.      * {@link org.xml.sax.ContentHandler#startElement startElement}

  72.      * event.</p>

  73.      *

  74.      * @param name The document type name.

  75.      * @param publicId The declared public identifier for the

  76.      *        external DTD subset, or null if none was declared.

  77.      * @param systemId The declared system identifier for the

  78.      *        external DTD subset, or null if none was declared.

  79.      * @exception SAXException The application may raise an

  80.      *            exception.

  81.      * @see #endDTD

  82.      * @see #startEntity

  83.      */

  84.     public abstract void startDTD (String name, String publicId,

  85. 				   String systemId)

  86. 	throws SAXException;

  87. 

  88. 

  89.     /**

  90.      * Report the end of DTD declarations.

  91.      *

  92.      * <p>This method is intended to report the end of the

  93.      * DOCTYPE declaration; if the document has no DOCTYPE declaration,

  94.      * this method will not be invoked.</p>

  95.      *

  96.      * @exception SAXException The application may raise an exception.

  97.      * @see #startDTD

  98.      */

  99.     public abstract void endDTD ()

  100. 	throws SAXException;

  101. 

  102. 

  103.     /**

  104.      * Report the beginning of some internal and external XML entities.

  105.      *

  106.      * <p>The reporting of parameter entities (including

  107.      * the external DTD subset) is optional, and SAX2 drivers that

  108.      * support LexicalHandler may not support it; you can use the

  109.      * <code

  110.      * >http://xml.org/sax/features/lexical-handler/parameter-entities</code>

  111.      * feature to query or control the reporting of parameter entities.</p>

  112.      *

  113.      * <p>General entities are reported with their regular names,

  114.      * parameter entities have '%' prepended to their names, and 

  115.      * the external DTD subset has the pseudo-entity name "[dtd]".</p>

  116.      *

  117.      * <p>When a SAX2 driver is providing these events, all other 

  118.      * events must be properly nested within start/end entity 

  119.      * events.  There is no additional requirement that events from 

  120.      * {@link org.xml.sax.ext.DeclHandler DeclHandler} or

  121.      * {@link org.xml.sax.DTDHandler DTDHandler} be properly ordered.</p>

  122.      *

  123.      * <p>Note that skipped entities will be reported through the

  124.      * {@link org.xml.sax.ContentHandler#skippedEntity skippedEntity}

  125.      * event, which is part of the ContentHandler interface.</p>

  126.      *

  127.      * <p>Because of the streaming event model that SAX uses, some

  128.      * entity boundaries cannot be reported under any 

  129.      * circumstances:</p>

  130.      *

  131.      * <ul>

  132.      * <li>general entities within attribute values</li>

  133.      * <li>parameter entities within declarations</li>

  134.      * </ul>

  135.      *

  136.      * <p>These will be silently expanded, with no indication of where

  137.      * the original entity boundaries were.</p>

  138.      *

  139.      * <p>Note also that the boundaries of character references (which

  140.      * are not really entities anyway) are not reported.</p>

  141.      *

  142.      * <p>All start/endEntity events must be properly nested.

  143.      *

  144.      * @param name The name of the entity.  If it is a parameter

  145.      *        entity, the name will begin with '%', and if it is the

  146.      *        external DTD subset, it will be "[dtd]".

  147.      * @exception SAXException The application may raise an exception.

  148.      * @see #endEntity

  149.      * @see org.xml.sax.ext.DeclHandler#internalEntityDecl

  150.      * @see org.xml.sax.ext.DeclHandler#externalEntityDecl 

  151.      */

  152.     public abstract void startEntity (String name)

  153. 	throws SAXException;

  154. 

  155. 

  156.     /**

  157.      * Report the end of an entity.

  158.      *

  159.      * @param name The name of the entity that is ending.

  160.      * @exception SAXException The application may raise an exception.

  161.      * @see #startEntity

  162.      */

  163.     public abstract void endEntity (String name)

  164. 	throws SAXException;

  165. 

  166. 

  167.     /**

  168.      * Report the start of a CDATA section.

  169.      *

  170.      * <p>The contents of the CDATA section will be reported through

  171.      * the regular {@link org.xml.sax.ContentHandler#characters

  172.      * characters} event; this event is intended only to report

  173.      * the boundary.</p>

  174.      *

  175.      * @exception SAXException The application may raise an exception.

  176.      * @see #endCDATA

  177.      */

  178.     public abstract void startCDATA ()

  179. 	throws SAXException;

  180. 

  181. 

  182.     /**

  183.      * Report the end of a CDATA section.

  184.      *

  185.      * @exception SAXException The application may raise an exception.

  186.      * @see #startCDATA

  187.      */

  188.     public abstract void endCDATA ()

  189. 	throws SAXException;

  190. 

  191. 

  192.     /**

  193.      * Report an XML comment anywhere in the document.

  194.      *

  195.      * <p>This callback will be used for comments inside or outside the

  196.      * document element, including comments in the external DTD

  197.      * subset (if read).  Comments in the DTD must be properly

  198.      * nested inside start/endDTD and start/endEntity events (if

  199.      * used).</p>

  200.      *

  201.      * @param ch An array holding the characters in the comment.

  202.      * @param start The starting position in the array.

  203.      * @param length The number of characters to use from the array.

  204.      * @exception SAXException The application may raise an exception.

  205.      */

  206.     public abstract void comment (char ch[], int start, int length)

  207. 	throws SAXException;

  208. 

  209. }

  210. 

  211. // end of LexicalHandler.java