| // LexicalHandler.java - optional handler for lexical parse events. |
| // Public Domain: no warranty. |
| // $Id: LexicalHandler.java,v 1.4 2000/02/25 14:55:59 david Exp $ |
| |
| package org.xml.sax.ext; |
| |
| import org.xml.sax.SAXException; |
| |
| /** |
| * SAX2 extension handler for lexical events. |
| * |
| * <blockquote> |
| * <em>This module, both source code and documentation, is in the |
| * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> |
| * </blockquote> |
| * |
| * <p>This is an optional extension handler for SAX2 to provide |
| * lexical information about an XML document, such as comments |
| * and CDATA section boundaries; XML readers are not required to |
| * support this handler.</p> |
| * |
| * <p>The events in the lexical handler apply to the entire document, |
| * not just to the document element, and all lexical handler events |
| * must appear between the content handler's startDocument and |
| * endDocument events.</p> |
| * |
| * <p>To set the LexicalHandler for an XML reader, use the |
| * {@link org.xml.sax.XMLReader#setProperty setProperty} method |
| * with the propertyId "http://xml.org/sax/handlers/LexicalHandler". |
| * If the reader does not support lexical events, it will throw a |
| * {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException} |
| * or a |
| * {@link org.xml.sax.SAXNotSupportedException SAXNotSupportedException} |
| * when you attempt to register the handler.</p> |
| * |
| * @since SAX 2.0 |
| * @author David Megginson, |
| * <a href="mailto:sax@megginson.com">sax@megginson.com</a> |
| * @version 2.0beta |
| * @see org.xml.sax.XMLReader#setProperty |
| * @see org.xml.sax.SAXNotRecognizedException |
| * @see org.xml.sax.SAXNotSupportedException |
| */ |
| public interface LexicalHandler |
| { |
| |
| /** |
| * Report the start of DTD declarations, if any. |
| * |
| * <p>Any declarations are assumed to be in the internal subset |
| * unless otherwise indicated by a {@link #startEntity startEntity} |
| * event.</p> |
| * |
| * <p>Note that the start/endDTD events will appear within |
| * the start/endDocument events from ContentHandler and |
| * before the first startElement event.</p> |
| * |
| * @param name The document type name. |
| * @param publicId The declared public identifier for the |
| * external DTD subset, or null if none was declared. |
| * @param systemId The declared system identifier for the |
| * external DTD subset, or null if none was declared. |
| * @exception SAXException The application may raise an |
| * exception. |
| * @see #endDTD |
| * @see #startEntity |
| */ |
| public abstract void startDTD (String name, String publicId, |
| String systemId) |
| throws SAXException; |
| |
| |
| /** |
| * Report the end of DTD declarations. |
| * |
| * @exception SAXException The application may raise an exception. |
| * @see #startDTD |
| */ |
| public abstract void endDTD () |
| throws SAXException; |
| |
| |
| /** |
| * Report the beginning of an entity in content. |
| * |
| * <p><strong>NOTE:</entity> entity references in attribute |
| * values -- and the start and end of the document entity -- |
| * are never reported.</p> |
| * |
| * <p>The start and end of the external DTD subset are reported |
| * using the pseudo-name "[dtd]". All other events must be |
| * properly nested within start/end entity events.</p> |
| * |
| * <p>Note that skipped entities will be reported through the |
| * {@link org.xml.sax.ContentHandler#skippedEntity skippedEntity} |
| * event, which is part of the ContentHandler interface.</p> |
| * |
| * @param name The name of the entity. If it is a parameter |
| * entity, the name will begin with '%'. |
| * @exception SAXException The application may raise an exception. |
| * @see #endEntity |
| * @see org.xml.sax.ext.DeclHandler#internalEntityDecl |
| * @see org.xml.sax.ext.DeclHandler#externalEntityDecl |
| */ |
| public abstract void startEntity (String name) |
| throws SAXException; |
| |
| |
| /** |
| * Report the end of an entity. |
| * |
| * @param name The name of the entity that is ending. |
| * @exception SAXException The application may raise an exception. |
| * @see #startEntity |
| */ |
| public abstract void endEntity (String name) |
| throws SAXException; |
| |
| |
| /** |
| * Report the start of a CDATA section. |
| * |
| * <p>The contents of the CDATA section will be reported through |
| * the regular {@link org.xml.sax.ContentHandler#characters |
| * characters} event.</p> |
| * |
| * @exception SAXException The application may raise an exception. |
| * @see #endCDATA |
| */ |
| public abstract void startCDATA () |
| throws SAXException; |
| |
| |
| /** |
| * Report the end of a CDATA section. |
| * |
| * @exception SAXException The application may raise an exception. |
| * @see #startCDATA |
| */ |
| public abstract void endCDATA () |
| throws SAXException; |
| |
| |
| /** |
| * Report an XML comment anywhere in the document. |
| * |
| * <p>This callback will be used for comments inside or outside the |
| * document element, including comments in the external DTD |
| * subset (if read).</p> |
| * |
| * @param ch An array holding the characters in the comment. |
| * @param start The starting position in the array. |
| * @param length The number of characters to use from the array. |
| * @exception SAXException The application may raise an exception. |
| */ |
| public abstract void comment (char ch[], int start, int length) |
| throws SAXException; |
| |
| } |
| |
| // end of LexicalHandler.java |