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

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