View Javadoc

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.5 2004/03/19 20:17:54 maartenc 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      * @param name The name of the entity.  If it is a parameter
129      *        entity, the name will begin with '%'.
130      * @param publicId The declared public identifier of the entity, or
131      *        null if none was declared.
132      * @param systemId The declared system identifier of the entity.
133      * @exception SAXException The application may raise an exception.
134      * @see #internalEntityDecl
135      * @see org.xml.sax.DTDHandler#unparsedEntityDecl
136      */
137     public abstract void externalEntityDecl (String name, String publicId,
138 					     String systemId)
139 	throws SAXException;
140 
141 }
142 
143 // end of DeclHandler.java