libjava/external/sax/org/xml/sax/ext/LexicalHandler.java

   1 // LexicalHandler.java - optional handler for lexical parse events.
   2 // http://www.saxproject.org
   3 // Public Domain: no warranty.
   4 // $Id: LexicalHandler.java,v 1.1 2004/12/23 22:38:42 mark Exp $
   5
   6 package org.xml.sax.ext;
   7
   8 import org.xml.sax.SAXException;
   9
  10 /**
  11  * SAX2 extension handler for lexical events.
  12  *
  13  * <blockquote>
  14  * <em>This module, both source code and documentation, is in the
  15  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
  16  * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
  17  * for further information.
  18  * </blockquote>
  19  *
  20  * <p>This is an optional extension handler for SAX2 to provide
  21  * lexical information about an XML document, such as comments
  22  * and CDATA section boundaries.
  23  * XML readers are not required to recognize this handler, and it
  24  * is not part of core-only SAX2 distributions.</p>
  25  *
  26  * <p>The events in the lexical handler apply to the entire document,
  27  * not just to the document element, and all lexical handler events
  28  * must appear between the content handler's startDocument and
  29  * endDocument events.</p>
  30  *
  31  * <p>To set the LexicalHandler for an XML reader, use the
  32  * {@link org.xml.sax.XMLReader#setProperty setProperty} method
  33  * with the property name
  34  * <code>http://xml.org/sax/properties/lexical-handler</code>
  35  * and an object implementing this interface (or null) as the value.
  36  * If the reader does not report lexical events, it will throw a
  37  * {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}
  38  * when you attempt to register the handler.</p>
  39  *
  40  * @since SAX 2.0 (extensions 1.0)
  41  * @author David Megginson
  42  * @version 2.0.1 (sax2r2)
  43  */
  44 public interface LexicalHandler
  45 {
  46
  47     /**
  48      * Report the start of DTD declarations, if any.
  49      *
  50      * <p>This method is intended to report the beginning of the
  51      * DOCTYPE declaration; if the document has no DOCTYPE declaration,
  52      * this method will not be invoked.</p>
  53      *
  54      * <p>All declarations reported through
  55      * {@link org.xml.sax.DTDHandler DTDHandler} or
  56      * {@link org.xml.sax.ext.DeclHandler DeclHandler} events must appear
  57      * between the startDTD and {@link #endDTD endDTD} events.
  58      * Declarations are assumed to belong to the internal DTD subset
  59      * unless they appear between {@link #startEntity startEntity}
  60      * and {@link #endEntity endEntity} events.  Comments and
  61      * processing instructions from the DTD should also be reported
  62      * between the startDTD and endDTD events, in their original
  63      * order of (logical) occurrence; they are not required to
  64      * appear in their correct locations relative to DTDHandler
  65      * or DeclHandler events, however.</p>
  66      *
  67      * <p>Note that the start/endDTD events will appear within
  68      * the start/endDocument events from ContentHandler and
  69      * before the first
  70      * {@link org.xml.sax.ContentHandler#startElement startElement}
  71      * event.</p>
  72      *
  73      * @param name The document type name.
  74      * @param publicId The declared public identifier for the
  75      *        external DTD subset, or null if none was declared.
  76      * @param systemId The declared system identifier for the
  77      *        external DTD subset, or null if none was declared.
  78      *        (Note that this is not resolved against the document
  79      *        base URI.)
  80      * @exception SAXException The application may raise an
  81      *            exception.
  82      * @see #endDTD
  83      * @see #startEntity
  84      */
  85     public abstract void startDTD (String name, String publicId,
  86                                    String systemId)
  87         throws SAXException;
  88
  89
  90     /**
  91      * Report the end of DTD declarations.
  92      *
  93      * <p>This method is intended to report the end of the
  94      * DOCTYPE declaration; if the document has no DOCTYPE declaration,
  95      * this method will not be invoked.</p>
  96      *
  97      * @exception SAXException The application may raise an exception.
  98      * @see #startDTD
  99      */
 100     public abstract void endDTD ()
 101         throws SAXException;
 102
 103
 104     /**
 105      * Report the beginning of some internal and external XML entities.
 106      *
 107      * <p>The reporting of parameter entities (including
 108      * the external DTD subset) is optional, and SAX2 drivers that
 109      * report LexicalHandler events may not implement it; you can use the
 110      * <code
 111      * >http://xml.org/sax/features/lexical-handler/parameter-entities</code>
 112      * feature to query or control the reporting of parameter entities.</p>
 113      *
 114      * <p>General entities are reported with their regular names,
 115      * parameter entities have '%' prepended to their names, and
 116      * the external DTD subset has the pseudo-entity name "[dtd]".</p>
 117      *
 118      * <p>When a SAX2 driver is providing these events, all other
 119      * events must be properly nested within start/end entity
 120      * events.  There is no additional requirement that events from
 121      * {@link org.xml.sax.ext.DeclHandler DeclHandler} or
 122      * {@link org.xml.sax.DTDHandler DTDHandler} be properly ordered.</p>
 123      *
 124      * <p>Note that skipped entities will be reported through the
 125      * {@link org.xml.sax.ContentHandler#skippedEntity skippedEntity}
 126      * event, which is part of the ContentHandler interface.</p>
 127      *
 128      * <p>Because of the streaming event model that SAX uses, some
 129      * entity boundaries cannot be reported under any
 130      * circumstances:</p>
 131      *
 132      * <ul>
 133      * <li>general entities within attribute values</li>
 134      * <li>parameter entities within declarations</li>
 135      * </ul>
 136      *
 137      * <p>These will be silently expanded, with no indication of where
 138      * the original entity boundaries were.</p>
 139      *
 140      * <p>Note also that the boundaries of character references (which
 141      * are not really entities anyway) are not reported.</p>
 142      *
 143      * <p>All start/endEntity events must be properly nested.
 144      *
 145      * @param name The name of the entity.  If it is a parameter
 146      *        entity, the name will begin with '%', and if it is the
 147      *        external DTD subset, it will be "[dtd]".
 148      * @exception SAXException The application may raise an exception.
 149      * @see #endEntity
 150      * @see org.xml.sax.ext.DeclHandler#internalEntityDecl
 151      * @see org.xml.sax.ext.DeclHandler#externalEntityDecl
 152      */
 153     public abstract void startEntity (String name)
 154         throws SAXException;
 155
 156
 157     /**
 158      * Report the end of an entity.
 159      *
 160      * @param name The name of the entity that is ending.
 161      * @exception SAXException The application may raise an exception.
 162      * @see #startEntity
 163      */
 164     public abstract void endEntity (String name)
 165         throws SAXException;
 166
 167
 168     /**
 169      * Report the start of a CDATA section.
 170      *
 171      * <p>The contents of the CDATA section will be reported through
 172      * the regular {@link org.xml.sax.ContentHandler#characters
 173      * characters} event; this event is intended only to report
 174      * the boundary.</p>
 175      *
 176      * @exception SAXException The application may raise an exception.
 177      * @see #endCDATA
 178      */
 179     public abstract void startCDATA ()
 180         throws SAXException;
 181
 182
 183     /**
 184      * Report the end of a CDATA section.
 185      *
 186      * @exception SAXException The application may raise an exception.
 187      * @see #startCDATA
 188      */
 189     public abstract void endCDATA ()
 190         throws SAXException;
 191
 192
 193     /**
 194      * Report an XML comment anywhere in the document.
 195      *
 196      * <p>This callback will be used for comments inside or outside the
 197      * document element, including comments in the external DTD
 198      * subset (if read).  Comments in the DTD must be properly
 199      * nested inside start/endDTD and start/endEntity events (if
 200      * used).</p>
 201      *
 202      * @param ch An array holding the characters in the comment.
 203      * @param start The starting position in the array.
 204      * @param length The number of characters to use from the array.
 205      * @exception SAXException The application may raise an exception.
 206      */
 207     public abstract void comment (char ch[], int start, int length)
 208         throws SAXException;
 209
 210 }
 211
 212 // end of LexicalHandler.java