Source for org.xml.sax.DTDHandler

   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.1 2004/12/23 22:38:42 mark 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