Home » xml-commons-external-1.4.01-src » org.xml » sax » [javadoc | source]

    1   // SAX DTD handler.
    2   // http://www.saxproject.org
    3   // No warranty; no copyright -- use this as you will.
    4   // $Id: DTDHandler.java 226184 2005-04-08 10:53:24Z neeraj $
    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

Home » xml-commons-external-1.4.01-src » org.xml » sax » [javadoc | source]