001// LexicalHandler.java - optional handler for lexical parse events. 002// Public Domain: no warranty. 003// $Id: LexicalHandler.java,v 1.2 2001/03/30 16:42:54 jstrachan Exp $ 004 005package org.xml.sax.ext; 006 007import org.xml.sax.SAXException; 008 009/** 010 * SAX2 extension handler for lexical events. 011 * 012 * <blockquote> 013 * <em>This module, both source code and documentation, is in the 014 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 015 * </blockquote> 016 * 017 * <p>This is an optional extension handler for SAX2 to provide 018 * lexical information about an XML document, such as comments 019 * and CDATA section boundaries; XML readers are not required to 020 * support this handler, and it is not part of the core SAX2 021 * distribution.</p> 022 * 023 * <p>The events in the lexical handler apply to the entire document, 024 * not just to the document element, and all lexical handler events 025 * must appear between the content handler's startDocument and 026 * endDocument events.</p> 027 * 028 * <p>To set the LexicalHandler for an XML reader, use the 029 * {@link org.xml.sax.XMLReader#setProperty setProperty} method 030 * with the propertyId "http://xml.org/sax/properties/lexical-handler". 031 * If the reader does not support lexical events, it will throw a 032 * {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException} 033 * or a 034 * {@link org.xml.sax.SAXNotSupportedException SAXNotSupportedException} 035 * when you attempt to register the handler.</p> 036 * 037 * @since 1.0 038 * @author David Megginson, 039 * <a href="mailto:sax@megginson.com">sax@megginson.com</a> 040 * @version 1.0beta 041 * @see org.xml.sax.XMLReader#setProperty 042 * @see org.xml.sax.SAXNotRecognizedException 043 * @see org.xml.sax.SAXNotSupportedException 044 */ 045public interface LexicalHandler 046{ 047 048 /** 049 * Report the start of DTD declarations, if any. 050 * 051 * <p>This method is intended to report the beginning of the 052 * DOCTYPE declaration; if the document has no DOCTYPE declaration, 053 * this method will not be invoked.</p> 054 * 055 * <p>All declarations reported through 056 * {@link org.xml.sax.DTDHandler DTDHandler} or 057 * {@link org.xml.sax.ext.DeclHandler DeclHandler} events must appear 058 * between the startDTD and {@link #endDTD endDTD} events. 059 * Declarations are assumed to belong to the internal DTD subset 060 * unless they appear between {@link #startEntity startEntity} 061 * and {@link #endEntity endEntity} events. Comments and 062 * processing instructions from the DTD should also be reported 063 * between the startDTD and endDTD events.</p> 064 * 065 * <p>Note that the start/endDTD events will appear within 066 * the start/endDocument events from ContentHandler and 067 * before the first 068 * {@link org.xml.sax.ContentHandler#startElement startElement} 069 * event.</p> 070 * 071 * @param name The document type name. 072 * @param publicId The declared public identifier for the 073 * external DTD subset, or null if none was declared. 074 * @param systemId The declared system identifier for the 075 * external DTD subset, or null if none was declared. 076 * @exception SAXException The application may raise an 077 * exception. 078 * @see #endDTD 079 * @see #startEntity 080 */ 081 public abstract void startDTD (String name, String publicId, 082 String systemId) 083 throws SAXException; 084 085 086 /** 087 * Report the end of DTD declarations. 088 * 089 * <p>This method is intended to report the end of the 090 * DOCTYPE declaration; if the document has no DOCTYPE declaration, 091 * this method will not be invoked.</p> 092 * 093 * @exception SAXException The application may raise an exception. 094 * @see #startDTD 095 */ 096 public abstract void endDTD () 097 throws SAXException; 098 099 100 /** 101 * Report the beginning of some internal and external XML entities. 102 * 103 * <p>The reporting of parameter entities (including 104 * the external DTD subset) is optional, and SAX2 drivers that 105 * support LexicalHandler may not support it; you can use the 106 * <code 107 * >http://xml.org/sax/features/lexical-handler/parameter-entities</code> 108 * feature to query or control the reporting of parameter entities.</p> 109 * 110 * <p>General entities are reported with their regular names, 111 * parameter entities have '%' prepended to their names, and 112 * the external DTD subset has the pseudo-entity name "[dtd]".</p> 113 * 114 * <p>When a SAX2 driver is providing these events, all other 115 * events must be properly nested within start/end entity 116 * events. There is no additional requirement that events from 117 * {@link org.xml.sax.ext.DeclHandler DeclHandler} or 118 * {@link org.xml.sax.DTDHandler DTDHandler} be properly ordered.</p> 119 * 120 * <p>Note that skipped entities will be reported through the 121 * {@link org.xml.sax.ContentHandler#skippedEntity skippedEntity} 122 * event, which is part of the ContentHandler interface.</p> 123 * 124 * <p>Because of the streaming event model that SAX uses, some 125 * entity boundaries cannot be reported under any 126 * circumstances:</p> 127 * 128 * <ul> 129 * <li>general entities within attribute values</li> 130 * <li>parameter entities within declarations</li> 131 * </ul> 132 * 133 * <p>These will be silently expanded, with no indication of where 134 * the original entity boundaries were.</p> 135 * 136 * <p>Note also that the boundaries of character references (which 137 * are not really entities anyway) are not reported.</p> 138 * 139 * <p>All start/endEntity events must be properly nested. 140 * 141 * @param name The name of the entity. If it is a parameter 142 * entity, the name will begin with '%', and if it is the 143 * external DTD subset, it will be "[dtd]". 144 * @exception SAXException The application may raise an exception. 145 * @see #endEntity 146 * @see org.xml.sax.ext.DeclHandler#internalEntityDecl 147 * @see org.xml.sax.ext.DeclHandler#externalEntityDecl 148 */ 149 public abstract void startEntity (String name) 150 throws SAXException; 151 152 153 /** 154 * Report the end of an entity. 155 * 156 * @param name The name of the entity that is ending. 157 * @exception SAXException The application may raise an exception. 158 * @see #startEntity 159 */ 160 public abstract void endEntity (String name) 161 throws SAXException; 162 163 164 /** 165 * Report the start of a CDATA section. 166 * 167 * <p>The contents of the CDATA section will be reported through 168 * the regular {@link org.xml.sax.ContentHandler#characters 169 * characters} event; this event is intended only to report 170 * the boundary.</p> 171 * 172 * @exception SAXException The application may raise an exception. 173 * @see #endCDATA 174 */ 175 public abstract void startCDATA () 176 throws SAXException; 177 178 179 /** 180 * Report the end of a CDATA section. 181 * 182 * @exception SAXException The application may raise an exception. 183 * @see #startCDATA 184 */ 185 public abstract void endCDATA () 186 throws SAXException; 187 188 189 /** 190 * Report an XML comment anywhere in the document. 191 * 192 * <p>This callback will be used for comments inside or outside the 193 * document element, including comments in the external DTD 194 * subset (if read). Comments in the DTD must be properly 195 * nested inside start/endDTD and start/endEntity events (if 196 * used).</p> 197 * 198 * @param ch An array holding the characters in the comment. 199 * @param start The starting position in the array. 200 * @param length The number of characters to use from the array. 201 * @exception SAXException The application may raise an exception. 202 */ 203 public abstract void comment (char ch[], int start, int length) 204 throws SAXException; 205 206} 207 208// end of LexicalHandler.java