Source for org.xml.sax.ext.LexicalHandler

   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