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