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