| Frames | No Frames |
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