libjava/org/xml/sax/DTDHandler.java

   1 // SAX DTD handler.
   2 // http://www.saxproject.org
   3 // No warranty; no copyright -- use this as you will.
   4 // $Id: DTDHandler.java,v 1.5.2.4 2002/01/29 21:34:14 dbrownell Exp $
   5
   6 package org.xml.sax;
   7
   8 /**
   9  * Receive notification of basic DTD-related events.
  10  *
  11  * <blockquote>
  12  * <em>This module, both source code and documentation, is in the
  13  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
  14  * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
  15  * for further information.
  16  * </blockquote>
  17  *
  18  * <p>If a SAX application needs information about notations and
  19  * unparsed entities, then the application implements this
  20  * interface and registers an instance with the SAX parser using
  21  * the parser's setDTDHandler method.  The parser uses the
  22  * instance to report notation and unparsed entity declarations to
  23  * the application.</p>
  24  *
  25  * <p>Note that this interface includes only those DTD events that
  26  * the XML recommendation <em>requires</em> processors to report:
  27  * notation and unparsed entity declarations.</p>
  28  *
  29  * <p>The SAX parser may report these events in any order, regardless
  30  * of the order in which the notations and unparsed entities were
  31  * declared; however, all DTD events must be reported after the
  32  * document handler's startDocument event, and before the first
  33  * startElement event.
  34  * (If the {@link org.xml.sax.ext.LexicalHandler LexicalHandler} is
  35  * used, these events must also be reported before the endDTD event.)
  36  * </p>
  37  *
  38  * <p>It is up to the application to store the information for
  39  * future use (perhaps in a hash table or object tree).
  40  * If the application encounters attributes of type "NOTATION",
  41  * "ENTITY", or "ENTITIES", it can use the information that it
  42  * obtained through this interface to find the entity and/or
  43  * notation corresponding with the attribute value.</p>
  44  *
  45  * @since SAX 1.0
  46  * @author David Megginson
  47  * @version 2.0.1 (sax2r2)
  48  * @see org.xml.sax.XMLReader#setDTDHandler
  49  */
  50 public interface DTDHandler {
  51
  52
  53     /**
  54      * Receive notification of a notation declaration event.
  55      *
  56      * <p>It is up to the application to record the notation for later
  57      * reference, if necessary;
  58      * notations may appear as attribute values and in unparsed entity
  59      * declarations, and are sometime used with processing instruction
  60      * target names.</p>
  61      *
  62      * <p>At least one of publicId and systemId must be non-null.
  63      * If a system identifier is present, and it is a URL, the SAX
  64      * parser must resolve it fully before passing it to the
  65      * application through this event.</p>
  66      *
  67      * <p>There is no guarantee that the notation declaration will be
  68      * reported before any unparsed entities that use it.</p>
  69      *
  70      * @param name The notation name.
  71      * @param publicId The notation's public identifier, or null if
  72      *        none was given.
  73      * @param systemId The notation's system identifier, or null if
  74      *        none was given.
  75      * @exception org.xml.sax.SAXException Any SAX exception, possibly
  76      *            wrapping another exception.
  77      * @see #unparsedEntityDecl
  78      * @see org.xml.sax.Attributes
  79      */
  80     public abstract void notationDecl (String name,
  81                                        String publicId,
  82                                        String systemId)
  83         throws SAXException;
  84
  85
  86     /**
  87      * Receive notification of an unparsed entity declaration event.
  88      *
  89      * <p>Note that the notation name corresponds to a notation
  90      * reported by the {@link #notationDecl notationDecl} event.
  91      * It is up to the application to record the entity for later
  92      * reference, if necessary;
  93      * unparsed entities may appear as attribute values.
  94      * </p>
  95      *
  96      * <p>If the system identifier is a URL, the parser must resolve it
  97      * fully before passing it to the application.</p>
  98      *
  99      * @exception org.xml.sax.SAXException Any SAX exception, possibly
 100      *            wrapping another exception.
 101      * @param name The unparsed entity's name.
 102      * @param publicId The entity's public identifier, or null if none
 103      *        was given.
 104      * @param systemId The entity's system identifier.
 105      * @param notationName The name of the associated notation.
 106      * @see #notationDecl
 107      * @see org.xml.sax.Attributes
 108      */
 109     public abstract void unparsedEntityDecl (String name,
 110                                              String publicId,
 111                                              String systemId,
 112                                              String notationName)
 113         throws SAXException;
 114
 115 }
 116
 117 // end of DTDHandler.java