1 // DeclHandler.java - Optional handler for DTD declaration events.
2 // http://www.saxproject.org
3 // Public Domain: no warranty.
4 // $Id: DeclHandler.java 226184 2005-04-08 10:53:24Z neeraj $
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