libjava/org/xml/sax/ext/DeclHandler.java

   1 // DeclHandler.java - Optional handler for DTD declaration events.\r
   2 // Public Domain: no warranty.\r
   3 // $Id: DeclHandler.java,v 1.1 2000/10/02 02:43:19 sboag Exp $\r
   4 \r
   5 package org.xml.sax.ext;\r
   6 \r
   7 import org.xml.sax.SAXException;\r
   8 \r
   9 \r
  10 /**\r
  11  * SAX2 extension handler for DTD declaration events.\r
  12  *\r
  13  * <blockquote>\r
  14  * <em>This module, both source code and documentation, is in the\r
  15  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>\r
  16  * </blockquote>\r
  17  *\r
  18  * <p>This is an optional extension handler for SAX2 to provide\r
  19  * information about DTD declarations in an XML document.  XML\r
  20  * readers are not required to support this handler.</p>\r
  21  *\r
  22  * <p>Note that data-related DTD declarations (unparsed entities and\r
  23  * notations) are already reported through the {@link\r
  24  * org.xml.sax.DTDHandler DTDHandler} interface.</p>\r
  25  *\r
  26  * <p>If you are using the declaration handler together with a lexical\r
  27  * handler, all of the events will occur between the\r
  28  * {@link org.xml.sax.ext.LexicalHandler#startDTD startDTD} and the\r
  29  * {@link org.xml.sax.ext.LexicalHandler#endDTD endDTD} events.</p>\r
  30  *\r
  31  * <p>To set the DeclHandler for an XML reader, use the\r
  32  * {@link org.xml.sax.XMLReader#setProperty setProperty} method\r
  33  * with the propertyId "http://xml.org/sax/handlers/DeclHandler".\r
  34  * If the reader does not support declaration events, it will throw a\r
  35  * {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}\r
  36  * or a\r
  37  * {@link org.xml.sax.SAXNotSupportedException SAXNotSupportedException}\r
  38  * when you attempt to register the handler.</p>\r
  39  *\r
  40  * @since SAX 2.0\r
  41  * @author David Megginson, \r
  42  *         <a href="mailto:sax@megginson.com">sax@megginson.com</a>\r
  43  * @version 2.0beta\r
  44  * @see org.xml.sax.XMLReader\r
  45  */\r
  46 public interface DeclHandler\r
  47 {\r
  48 \r
  49     /**\r
  50      * Report an element type declaration.\r
  51      *\r
  52      * <p>The content model will consist of the string "EMPTY", the\r
  53      * string "ANY", or a parenthesised group, optionally followed\r
  54      * by an occurrence indicator.  The model will be normalized so\r
  55      * that all whitespace is removed,and will include the enclosing\r
  56      * parentheses.</p>\r
  57      *\r
  58      * @param name The element type name.\r
  59      * @param model The content model as a normalized string.\r
  60      * @exception SAXException The application may raise an exception.\r
  61      */\r
  62     public abstract void elementDecl (String name, String model)\r
  63         throws SAXException;\r
  64 \r
  65 \r
  66     /**\r
  67      * Report an attribute type declaration.\r
  68      *\r
  69      * <p>Only the effective (first) declaration for an attribute will\r
  70      * be reported.  The type will be one of the strings "CDATA",\r
  71      * "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY",\r
  72      * "ENTITIES", or "NOTATION", or a parenthesized token group with \r
  73      * the separator "|" and all whitespace removed.</p>\r
  74      *\r
  75      * @param eName The name of the associated element.\r
  76      * @param aName The name of the attribute.\r
  77      * @param type A string representing the attribute type.\r
  78      * @param valueDefault A string representing the attribute default\r
  79      *        ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if\r
  80      *        none of these applies.\r
  81      * @param value A string representing the attribute's default value,\r
  82      *        or null if there is none.\r
  83      * @exception SAXException The application may raise an exception.\r
  84      */\r
  85     public abstract void attributeDecl (String eName,\r
  86                                         String aName,\r
  87                                         String type,\r
  88                                         String valueDefault,\r
  89                                         String value)\r
  90         throws SAXException;\r
  91 \r
  92 \r
  93     /**\r
  94      * Report an internal entity declaration.\r
  95      *\r
  96      * <p>Only the effective (first) declaration for each entity\r
  97      * will be reported.</p>\r
  98      *\r
  99      * @param name The name of the entity.  If it is a parameter\r
 100      *        entity, the name will begin with '%'.\r
 101      * @param value The replacement text of the entity.\r
 102      * @exception SAXException The application may raise an exception.\r
 103      * @see #externalEntityDecl\r
 104      * @see org.xml.sax.DTDHandler#unparsedEntityDecl\r
 105      */\r
 106     public abstract void internalEntityDecl (String name, String value)\r
 107         throws SAXException;\r
 108 \r
 109 \r
 110     /**\r
 111      * Report a parsed external entity declaration.\r
 112      *\r
 113      * <p>Only the effective (first) declaration for each entity\r
 114      * will be reported.</p>\r
 115      *\r
 116      * @param name The name of the entity.  If it is a parameter\r
 117      *        entity, the name will begin with '%'.\r
 118      * @param publicId The declared public identifier of the entity, or\r
 119      *        null if none was declared.\r
 120      * @param systemId The declared system identifier of the entity.\r
 121      * @exception SAXException The application may raise an exception.\r
 122      * @see #internalEntityDecl\r
 123      * @see org.xml.sax.DTDHandler#unparsedEntityDecl\r
 124      */\r
 125     public abstract void externalEntityDecl (String name, String publicId,\r
 126                                              String systemId)\r
 127         throws SAXException;\r
 128 \r
 129 }\r
 130 \r
 131 // end of DeclHandler.java\r