Source for org.xml.sax.ext.DeclHandler

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