1 /*
   2  * Copyright (c) 1998, 2015, 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 com.sun.xml.internal.dtdparser;
  27 
  28 import org.xml.sax.Locator;
  29 import org.xml.sax.SAXException;
  30 import org.xml.sax.SAXParseException;
  31 
  32 import java.util.EventListener;
  33 
  34 /**
  35  * All DTD parsing events are signaled through this interface.
  36  */
  37 public interface DTDEventListener extends EventListener {
  38 
  39     public void setDocumentLocator(Locator loc);
  40 
  41     /**
  42      * Receive notification of a Processing Instruction.
  43      * Processing instructions contain information meaningful
  44      * to the application.
  45      *
  46      * @param target The target of the proceessing instruction
  47      *               which should have meaning to the application.
  48      * @param data   The instruction itself which should contain
  49      *               valid XML characters.
  50      * @throws SAXException
  51      */
  52     public void processingInstruction(String target, String data)
  53             throws SAXException;
  54 
  55     /**
  56      * Receive notification of a Notation Declaration.
  57      * Notation declarations are used by elements and entities
  58      * for identifying embedded non-XML data.
  59      *
  60      * @param name     The notation name, referred to by entities and
  61      *                 elements.
  62      * @param publicId The public identifier
  63      * @param systemId The system identifier
  64      */
  65     public void notationDecl(String name, String publicId, String systemId)
  66             throws SAXException;
  67 
  68     /**
  69      * Receive notification of an unparsed entity declaration.
  70      * Unparsed entities are non-XML data.
  71      *
  72      * @param name         The name of the unparsed entity.
  73      * @param publicId     The public identifier
  74      * @param systemId     The system identifier
  75      * @param notationName The associated notation
  76      */
  77     public void unparsedEntityDecl(String name, String publicId,
  78                                    String systemId, String notationName)
  79             throws SAXException;
  80 
  81     /**
  82      * Receive notification of a internal general entity declaration event.
  83      *
  84      * @param name  The internal general entity name.
  85      * @param value The value of the entity, which may include unexpanded
  86      *              entity references.  Character references will have been
  87      *              expanded.
  88      * @throws SAXException
  89      * @see #externalGeneralEntityDecl(String, String, String)
  90      */
  91     public void internalGeneralEntityDecl(String name, String value)
  92             throws SAXException;
  93 
  94     /**
  95      * Receive notification of an external parsed general entity
  96      * declaration event.
  97      * <p>
  98      * <p>If a system identifier is present, and it is a relative URL, the
  99      * parser will have resolved it fully before passing it through this
 100      * method to a listener.</p>
 101      *
 102      * @param name     The entity name.
 103      * @param publicId The entity's public identifier, or null if
 104      *                 none was given.
 105      * @param systemId The entity's system identifier.
 106      * @throws SAXException
 107      * @see #unparsedEntityDecl(String, String, String, String)
 108      */
 109     public void externalGeneralEntityDecl(String name, String publicId,
 110                                           String systemId)
 111             throws SAXException;
 112 
 113     /**
 114      * Receive notification of a internal parameter entity declaration
 115      * event.
 116      *
 117      * @param name  The internal parameter entity name.
 118      * @param value The value of the entity, which may include unexpanded
 119      *              entity references.  Character references will have been
 120      *              expanded.
 121      * @throws SAXException
 122      * @see #externalParameterEntityDecl(String, String, String)
 123      */
 124     public void internalParameterEntityDecl(String name, String value)
 125             throws SAXException;
 126 
 127     /**
 128      * Receive notification of an external parameter entity declaration
 129      * event.
 130      * <p>
 131      * <p>If a system identifier is present, and it is a relative URL, the
 132      * parser will have resolved it fully before passing it through this
 133      * method to a listener.</p>
 134      *
 135      * @param name     The parameter entity name.
 136      * @param publicId The entity's public identifier, or null if
 137      *                 none was given.
 138      * @param systemId The entity's system identifier.
 139      * @throws SAXException
 140      * @see #unparsedEntityDecl(String, String, String, String)
 141      */
 142     public void externalParameterEntityDecl(String name, String publicId,
 143                                             String systemId)
 144             throws SAXException;
 145 
 146     /**
 147      * Receive notification of the beginning of the DTD.
 148      *
 149      * @param in Current input entity.
 150      * @see #endDTD()
 151      */
 152     public void startDTD(InputEntity in)
 153             throws SAXException;
 154 
 155     /**
 156      * Receive notification of the end of a DTD.  The parser will invoke
 157      * this method only once.
 158      *
 159      * @throws SAXException
 160      * @see #startDTD(InputEntity)
 161      */
 162     public void endDTD()
 163             throws SAXException;
 164 
 165     /**
 166      * Receive notification that a comment has been read.
 167      * <p>
 168      * <P> Note that processing instructions are the mechanism designed
 169      * to hold information for consumption by applications, not comments.
 170      * XML systems may rely on applications being able to access information
 171      * found in processing instructions; this is not true of comments, which
 172      * are typically discarded.
 173      *
 174      * @param text the text within the comment delimiters.
 175      * @throws SAXException
 176      */
 177     public void comment(String text)
 178             throws SAXException;
 179 
 180     /**
 181      * Receive notification of character data.
 182      * <p>
 183      * <p>The Parser will call this method to report each chunk of
 184      * character data.  SAX parsers may return all contiguous character
 185      * data in a single chunk, or they may split it into several
 186      * chunks; however, all of the characters in any single event
 187      * must come from the same external entity, so that the Locator
 188      * provides useful information.</p>
 189      * <p>
 190      * <p>The application must not attempt to read from the array
 191      * outside of the specified range.</p>
 192      * <p>
 193      * <p>Note that some parsers will report whitespace using the
 194      * ignorableWhitespace() method rather than this one (validating
 195      * parsers must do so).</p>
 196      *
 197      * @param ch     The characters from the DTD.
 198      * @param start  The start position in the array.
 199      * @param length The number of characters to read from the array.
 200      * @throws SAXException
 201      * @see #ignorableWhitespace(char[], int, int)
 202      */
 203     public void characters(char ch[], int start, int length)
 204             throws SAXException;
 205 
 206 
 207     /**
 208      * Receive notification of ignorable whitespace in element content.
 209      * <p>
 210      * <p>Validating Parsers must use this method to report each chunk
 211      * of ignorable whitespace (see the W3C XML 1.0 recommendation,
 212      * section 2.10): non-validating parsers may also use this method
 213      * if they are capable of parsing and using content models.</p>
 214      * <p>
 215      * <p>SAX parsers may return all contiguous whitespace in a single
 216      * chunk, or they may split it into several chunks; however, all of
 217      * the characters in any single event must come from the same
 218      * external entity, so that the Locator provides useful
 219      * information.</p>
 220      * <p>
 221      * <p>The application must not attempt to read from the array
 222      * outside of the specified range.</p>
 223      *
 224      * @param ch     The characters from the DTD.
 225      * @param start  The start position in the array.
 226      * @param length The number of characters to read from the array.
 227      * @throws SAXException
 228      * @see #characters(char[], int, int)
 229      */
 230     public void ignorableWhitespace(char ch[], int start, int length)
 231             throws SAXException;
 232 
 233     /**
 234      * Receive notification that a CDATA section is beginning.  Data in a
 235      * CDATA section is is reported through the appropriate event, either
 236      * <em>characters()</em> or <em>ignorableWhitespace</em>.
 237      *
 238      * @throws SAXException
 239      * @see #endCDATA()
 240      */
 241     public void startCDATA() throws SAXException;
 242 
 243 
 244     /**
 245      * Receive notification that the CDATA section finished.
 246      *
 247      * @throws SAXException
 248      * @see #startCDATA()
 249      */
 250     public void endCDATA() throws SAXException;
 251 
 252 
 253     public void fatalError(SAXParseException e)
 254             throws SAXException;
 255 
 256     public void error(SAXParseException e) throws SAXException;
 257 
 258     public void warning(SAXParseException err) throws SAXException;
 259 
 260     public final short CONTENT_MODEL_EMPTY = 0;
 261     public final short CONTENT_MODEL_ANY = 1;
 262     public final short CONTENT_MODEL_MIXED = 2;
 263     public final short CONTENT_MODEL_CHILDREN = 3;
 264 
 265     /**
 266      * receives notification that parsing of content model is beginning.
 267      *
 268      * @param elementName      name of the element whose content model is going to be defined.
 269      * @param contentModelType {@link #CONTENT_MODEL_EMPTY}
 270      *                         this element has EMPTY content model. This notification
 271      *                         will be immediately followed by the corresponding endContentModel.
 272      *                         {@link #CONTENT_MODEL_ANY}
 273      *                         this element has ANY content model. This notification
 274      *                         will be immediately followed by the corresponding endContentModel.
 275      *                         {@link #CONTENT_MODEL_MIXED}
 276      *                         this element has mixed content model. #PCDATA will not be reported.
 277      *                         each child element will be reported by mixedElement method.
 278      *                         {@link #CONTENT_MODEL_CHILDREN}
 279      *                         this elemen has child content model. The actual content model will
 280      *                         be reported by childElement, startModelGroup, endModelGroup, and
 281      *                         connector methods. Possible call sequences are:
 282      *                         <p>
 283      *                         START := MODEL_GROUP
 284      *                         MODEL_GROUP := startModelGroup TOKEN (connector TOKEN)* endModelGroup
 285      *                         TOKEN := childElement
 286      *                         | MODEL_GROUP
 287      */
 288     public void startContentModel(String elementName, short contentModelType) throws SAXException;
 289 
 290     /**
 291      * receives notification that parsing of content model is finished.
 292      */
 293     public void endContentModel(String elementName, short contentModelType) throws SAXException;
 294 
 295     public final short USE_NORMAL = 0;
 296     public final short USE_IMPLIED = 1;
 297     public final short USE_FIXED = 2;
 298     public final short USE_REQUIRED = 3;
 299 
 300     /**
 301      * For each entry in an ATTLIST declaration,
 302      * this event will be fired.
 303      * <p>
 304      * <p>
 305      * DTD allows the same attributes to be declared more than
 306      * once, and in that case the first one wins. I think
 307      * this method will be only fired for the first one,
 308      * but I need to check.
 309      */
 310     public void attributeDecl(String elementName, String attributeName, String attributeType,
 311                               String[] enumeration, short attributeUse, String defaultValue) throws SAXException;
 312 
 313     public void childElement(String elementName, short occurence) throws SAXException;
 314 
 315     /**
 316      * receives notification of child element of mixed content model.
 317      * this method is called for each child element.
 318      *
 319      * @see #startContentModel(String, short)
 320      */
 321     public void mixedElement(String elementName) throws SAXException;
 322 
 323     public void startModelGroup() throws SAXException;
 324 
 325     public void endModelGroup(short occurence) throws SAXException;
 326 
 327     public final short CHOICE = 0;
 328     public final short SEQUENCE = 1;
 329 
 330     /**
 331      * Connectors in one model group is guaranteed to be the same.
 332      * <p>
 333      * <p>
 334      * IOW, you'll never see an event sequence like (a|b,c)


 335      */
 336     public void connector(short connectorType) throws SAXException;
 337 
 338     public final short OCCURENCE_ZERO_OR_MORE = 0;
 339     public final short OCCURENCE_ONE_OR_MORE = 1;
 340     public final short OCCURENCE_ZERO_OR_ONE = 2;
 341     public final short OCCURENCE_ONCE = 3;
 342 }
--- EOF ---