ohair@286: /* mkos@397: * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved. ohair@286: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. ohair@286: * ohair@286: * This code is free software; you can redistribute it and/or modify it ohair@286: * under the terms of the GNU General Public License version 2 only, as ohair@286: * published by the Free Software Foundation. Oracle designates this ohair@286: * particular file as subject to the "Classpath" exception as provided ohair@286: * by Oracle in the LICENSE file that accompanied this code. ohair@286: * ohair@286: * This code is distributed in the hope that it will be useful, but WITHOUT ohair@286: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or ohair@286: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License ohair@286: * version 2 for more details (a copy is included in the LICENSE file that ohair@286: * accompanied this code). ohair@286: * ohair@286: * You should have received a copy of the GNU General Public License version ohair@286: * 2 along with this work; if not, write to the Free Software Foundation, ohair@286: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. ohair@286: * ohair@286: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ohair@286: * or visit www.oracle.com if you need additional information or have any ohair@286: * questions. ohair@286: */ ohair@286: ohair@286: package com.sun.xml.internal.dtdparser; ohair@286: ohair@286: import org.xml.sax.Locator; ohair@286: import org.xml.sax.SAXException; ohair@286: import org.xml.sax.SAXParseException; ohair@286: ohair@286: import java.util.EventListener; ohair@286: ohair@286: /** ohair@286: * All DTD parsing events are signaled through this interface. ohair@286: */ ohair@286: public interface DTDEventListener extends EventListener { ohair@286: ohair@286: public void setDocumentLocator(Locator loc); ohair@286: ohair@286: /** ohair@286: * Receive notification of a Processing Instruction. ohair@286: * Processing instructions contain information meaningful ohair@286: * to the application. ohair@286: * ohair@286: * @param target The target of the proceessing instruction ohair@286: * which should have meaning to the application. ohair@286: * @param data The instruction itself which should contain ohair@286: * valid XML characters. ohair@286: * @throws SAXException ohair@286: */ ohair@286: public void processingInstruction(String target, String data) ohair@286: throws SAXException; ohair@286: ohair@286: /** ohair@286: * Receive notification of a Notation Declaration. ohair@286: * Notation declarations are used by elements and entities ohair@286: * for identifying embedded non-XML data. ohair@286: * ohair@286: * @param name The notation name, referred to by entities and ohair@286: * elements. ohair@286: * @param publicId The public identifier ohair@286: * @param systemId The system identifier ohair@286: */ ohair@286: public void notationDecl(String name, String publicId, String systemId) ohair@286: throws SAXException; ohair@286: ohair@286: /** ohair@286: * Receive notification of an unparsed entity declaration. ohair@286: * Unparsed entities are non-XML data. ohair@286: * ohair@286: * @param name The name of the unparsed entity. ohair@286: * @param publicId The public identifier ohair@286: * @param systemId The system identifier ohair@286: * @param notationName The associated notation ohair@286: */ ohair@286: public void unparsedEntityDecl(String name, String publicId, ohair@286: String systemId, String notationName) ohair@286: throws SAXException; ohair@286: ohair@286: /** ohair@286: * Receive notification of a internal general entity declaration event. ohair@286: * ohair@286: * @param name The internal general entity name. ohair@286: * @param value The value of the entity, which may include unexpanded ohair@286: * entity references. Character references will have been ohair@286: * expanded. ohair@286: * @throws SAXException ohair@286: * @see #externalGeneralEntityDecl(String, String, String) ohair@286: */ ohair@286: public void internalGeneralEntityDecl(String name, String value) ohair@286: throws SAXException; ohair@286: ohair@286: /** ohair@286: * Receive notification of an external parsed general entity ohair@286: * declaration event. ohair@286: *

ohair@286: *

If a system identifier is present, and it is a relative URL, the ohair@286: * parser will have resolved it fully before passing it through this ohair@286: * method to a listener.

ohair@286: * ohair@286: * @param name The entity name. ohair@286: * @param publicId The entity's public identifier, or null if ohair@286: * none was given. ohair@286: * @param systemId The entity's system identifier. ohair@286: * @throws SAXException ohair@286: * @see #unparsedEntityDecl(String, String, String, String) ohair@286: */ ohair@286: public void externalGeneralEntityDecl(String name, String publicId, ohair@286: String systemId) ohair@286: throws SAXException; ohair@286: ohair@286: /** ohair@286: * Receive notification of a internal parameter entity declaration ohair@286: * event. ohair@286: * ohair@286: * @param name The internal parameter entity name. ohair@286: * @param value The value of the entity, which may include unexpanded ohair@286: * entity references. Character references will have been ohair@286: * expanded. ohair@286: * @throws SAXException ohair@286: * @see #externalParameterEntityDecl(String, String, String) ohair@286: */ ohair@286: public void internalParameterEntityDecl(String name, String value) ohair@286: throws SAXException; ohair@286: ohair@286: /** ohair@286: * Receive notification of an external parameter entity declaration ohair@286: * event. ohair@286: *

ohair@286: *

If a system identifier is present, and it is a relative URL, the ohair@286: * parser will have resolved it fully before passing it through this ohair@286: * method to a listener.

ohair@286: * ohair@286: * @param name The parameter entity name. ohair@286: * @param publicId The entity's public identifier, or null if ohair@286: * none was given. ohair@286: * @param systemId The entity's system identifier. ohair@286: * @throws SAXException ohair@286: * @see #unparsedEntityDecl(String, String, String, String) ohair@286: */ ohair@286: public void externalParameterEntityDecl(String name, String publicId, ohair@286: String systemId) ohair@286: throws SAXException; ohair@286: ohair@286: /** ohair@286: * Receive notification of the beginning of the DTD. ohair@286: * ohair@286: * @param in Current input entity. ohair@286: * @see #endDTD() ohair@286: */ ohair@286: public void startDTD(InputEntity in) ohair@286: throws SAXException; ohair@286: ohair@286: /** ohair@286: * Receive notification of the end of a DTD. The parser will invoke ohair@286: * this method only once. ohair@286: * ohair@286: * @throws SAXException ohair@286: * @see #startDTD(InputEntity) ohair@286: */ ohair@286: public void endDTD() ohair@286: throws SAXException; ohair@286: ohair@286: /** ohair@286: * Receive notification that a comment has been read. ohair@286: *

ohair@286: *

Note that processing instructions are the mechanism designed ohair@286: * to hold information for consumption by applications, not comments. ohair@286: * XML systems may rely on applications being able to access information ohair@286: * found in processing instructions; this is not true of comments, which ohair@286: * are typically discarded. ohair@286: * ohair@286: * @param text the text within the comment delimiters. ohair@286: * @throws SAXException ohair@286: */ ohair@286: public void comment(String text) ohair@286: throws SAXException; ohair@286: ohair@286: /** ohair@286: * Receive notification of character data. ohair@286: *

ohair@286: *

The Parser will call this method to report each chunk of ohair@286: * character data. SAX parsers may return all contiguous character ohair@286: * data in a single chunk, or they may split it into several ohair@286: * chunks; however, all of the characters in any single event ohair@286: * must come from the same external entity, so that the Locator ohair@286: * provides useful information.

ohair@286: *

ohair@286: *

The application must not attempt to read from the array ohair@286: * outside of the specified range.

ohair@286: *

ohair@286: *

Note that some parsers will report whitespace using the ohair@286: * ignorableWhitespace() method rather than this one (validating ohair@286: * parsers must do so).

ohair@286: * ohair@286: * @param ch The characters from the DTD. ohair@286: * @param start The start position in the array. ohair@286: * @param length The number of characters to read from the array. ohair@286: * @throws SAXException ohair@286: * @see #ignorableWhitespace(char[], int, int) ohair@286: */ ohair@286: public void characters(char ch[], int start, int length) ohair@286: throws SAXException; ohair@286: ohair@286: ohair@286: /** ohair@286: * Receive notification of ignorable whitespace in element content. ohair@286: *

ohair@286: *

Validating Parsers must use this method to report each chunk ohair@286: * of ignorable whitespace (see the W3C XML 1.0 recommendation, ohair@286: * section 2.10): non-validating parsers may also use this method ohair@286: * if they are capable of parsing and using content models.

ohair@286: *

ohair@286: *

SAX parsers may return all contiguous whitespace in a single ohair@286: * chunk, or they may split it into several chunks; however, all of ohair@286: * the characters in any single event must come from the same ohair@286: * external entity, so that the Locator provides useful ohair@286: * information.

ohair@286: *

ohair@286: *

The application must not attempt to read from the array ohair@286: * outside of the specified range.

ohair@286: * ohair@286: * @param ch The characters from the DTD. ohair@286: * @param start The start position in the array. ohair@286: * @param length The number of characters to read from the array. ohair@286: * @throws SAXException ohair@286: * @see #characters(char[], int, int) ohair@286: */ ohair@286: public void ignorableWhitespace(char ch[], int start, int length) ohair@286: throws SAXException; ohair@286: ohair@286: /** ohair@286: * Receive notification that a CDATA section is beginning. Data in a ohair@286: * CDATA section is is reported through the appropriate event, either ohair@286: * characters() or ignorableWhitespace. ohair@286: * ohair@286: * @throws SAXException ohair@286: * @see #endCDATA() ohair@286: */ ohair@286: public void startCDATA() throws SAXException; ohair@286: ohair@286: ohair@286: /** ohair@286: * Receive notification that the CDATA section finished. ohair@286: * ohair@286: * @throws SAXException ohair@286: * @see #startCDATA() ohair@286: */ ohair@286: public void endCDATA() throws SAXException; ohair@286: ohair@286: ohair@286: public void fatalError(SAXParseException e) ohair@286: throws SAXException; ohair@286: ohair@286: public void error(SAXParseException e) throws SAXException; ohair@286: ohair@286: public void warning(SAXParseException err) throws SAXException; ohair@286: ohair@286: public final short CONTENT_MODEL_EMPTY = 0; ohair@286: public final short CONTENT_MODEL_ANY = 1; ohair@286: public final short CONTENT_MODEL_MIXED = 2; ohair@286: public final short CONTENT_MODEL_CHILDREN = 3; ohair@286: ohair@286: /** ohair@286: * receives notification that parsing of content model is beginning. ohair@286: * ohair@286: * @param elementName name of the element whose content model is going to be defined. ohair@286: * @param contentModelType {@link #CONTENT_MODEL_EMPTY} ohair@286: * this element has EMPTY content model. This notification ohair@286: * will be immediately followed by the corresponding endContentModel. ohair@286: * {@link #CONTENT_MODEL_ANY} ohair@286: * this element has ANY content model. This notification ohair@286: * will be immediately followed by the corresponding endContentModel. ohair@286: * {@link #CONTENT_MODEL_MIXED} ohair@286: * this element has mixed content model. #PCDATA will not be reported. ohair@286: * each child element will be reported by mixedElement method. ohair@286: * {@link #CONTENT_MODEL_CHILDREN} ohair@286: * this elemen has child content model. The actual content model will ohair@286: * be reported by childElement, startModelGroup, endModelGroup, and ohair@286: * connector methods. Possible call sequences are: ohair@286: *

ohair@286: * START := MODEL_GROUP ohair@286: * MODEL_GROUP := startModelGroup TOKEN (connector TOKEN)* endModelGroup ohair@286: * TOKEN := childElement ohair@286: * | MODEL_GROUP ohair@286: */ ohair@286: public void startContentModel(String elementName, short contentModelType) throws SAXException; ohair@286: ohair@286: /** ohair@286: * receives notification that parsing of content model is finished. ohair@286: */ ohair@286: public void endContentModel(String elementName, short contentModelType) throws SAXException; ohair@286: ohair@286: public final short USE_NORMAL = 0; ohair@286: public final short USE_IMPLIED = 1; ohair@286: public final short USE_FIXED = 2; ohair@286: public final short USE_REQUIRED = 3; ohair@286: ohair@286: /** ohair@286: * For each entry in an ATTLIST declaration, ohair@286: * this event will be fired. ohair@286: *

ohair@286: *

ohair@286: * DTD allows the same attributes to be declared more than ohair@286: * once, and in that case the first one wins. I think ohair@286: * this method will be only fired for the first one, ohair@286: * but I need to check. ohair@286: */ ohair@286: public void attributeDecl(String elementName, String attributeName, String attributeType, ohair@286: String[] enumeration, short attributeUse, String defaultValue) throws SAXException; ohair@286: ohair@286: public void childElement(String elementName, short occurence) throws SAXException; ohair@286: ohair@286: /** ohair@286: * receives notification of child element of mixed content model. ohair@286: * this method is called for each child element. ohair@286: * ohair@286: * @see #startContentModel(String, short) ohair@286: */ ohair@286: public void mixedElement(String elementName) throws SAXException; ohair@286: ohair@286: public void startModelGroup() throws SAXException; ohair@286: ohair@286: public void endModelGroup(short occurence) throws SAXException; ohair@286: ohair@286: public final short CHOICE = 0; ohair@286: public final short SEQUENCE = 1; ohair@286: ohair@286: /** ohair@286: * Connectors in one model group is guaranteed to be the same. ohair@286: *

ohair@286: *

ohair@286: * IOW, you'll never see an event sequence like (a|b,c) ohair@286: * ohair@286: * @return {@link #CHOICE} or {@link #SEQUENCE}. ohair@286: */ ohair@286: public void connector(short connectorType) throws SAXException; ohair@286: ohair@286: public final short OCCURENCE_ZERO_OR_MORE = 0; ohair@286: public final short OCCURENCE_ONE_OR_MORE = 1; ohair@286: public final short OCCURENCE_ZERO_OR_ONE = 2; ohair@286: public final short OCCURENCE_ONCE = 3; ohair@286: }