1 /*
2 * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 // DeclHandler.java - Optional handler for DTD declaration events.
27 // http://www.saxproject.org
28 // Public Domain: no warranty.
29 // $Id: DeclHandler.java,v 1.2 2004/11/03 22:49:08 jsuttor Exp $
30
31 package org.xml.sax.ext;
32
33 import org.xml.sax.SAXException;
34
35
36 /**
37 * SAX2 extension handler for DTD declaration events.
38 *
39 * <blockquote>
40 * <em>This module, both source code and documentation, is in the
41 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
42 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
43 * for further information.
44 * </blockquote>
45 *
46 * <p>This is an optional extension handler for SAX2 to provide more
47 * complete information about DTD declarations in an XML document.
48 * XML readers are not required to recognize this handler, and it
49 * is not part of core-only SAX2 distributions.</p>
50 *
51 * <p>Note that data-related DTD declarations (unparsed entities and
52 * notations) are already reported through the {@link
53 * org.xml.sax.DTDHandler DTDHandler} interface.</p>
54 *
55 * <p>If you are using the declaration handler together with a lexical
56 * handler, all of the events will occur between the
57 * {@link org.xml.sax.ext.LexicalHandler#startDTD startDTD} and the
58 * {@link org.xml.sax.ext.LexicalHandler#endDTD endDTD} events.</p>
59 *
60 * <p>To set the DeclHandler for an XML reader, use the
61 * {@link org.xml.sax.XMLReader#setProperty setProperty} method
62 * with the property name
63 * <code>http://xml.org/sax/properties/declaration-handler</code>
64 * and an object implementing this interface (or null) as the value.
65 * If the reader does not report declaration events, it will throw a
66 * {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}
67 * when you attempt to register the handler.</p>
68 *
69 * @since 1.4, SAX 2.0 (extensions 1.0)
70 * @author David Megginson
71 */
72 public interface DeclHandler
73 {
74
75 /**
76 * Report an element type declaration.
77 *
78 * <p>The content model will consist of the string "EMPTY", the
79 * string "ANY", or a parenthesised group, optionally followed
80 * by an occurrence indicator. The model will be normalized so
81 * that all parameter entities are fully resolved and all whitespace
82 * is removed,and will include the enclosing parentheses. Other
83 * normalization (such as removing redundant parentheses or
84 * simplifying occurrence indicators) is at the discretion of the
85 * parser.</p>
86 *
87 * @param name The element type name.
88 * @param model The content model as a normalized string.
89 * @exception SAXException The application may raise an exception.
90 */
91 public abstract void elementDecl (String name, String model)
92 throws SAXException;
93
94
95 /**
96 * Report an attribute type declaration.
97 *
98 * <p>Only the effective (first) declaration for an attribute will
99 * be reported. The type will be one of the strings "CDATA",
100 * "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY",
101 * "ENTITIES", a parenthesized token group with
102 * the separator "|" and all whitespace removed, or the word
103 * "NOTATION" followed by a space followed by a parenthesized
104 * token group with all whitespace removed.</p>
105 *
106 * <p>The value will be the value as reported to applications,
107 * appropriately normalized and with entity and character
108 * references expanded. </p>
109 *
110 * @param eName The name of the associated element.
111 * @param aName The name of the attribute.
112 * @param type A string representing the attribute type.
113 * @param mode A string representing the attribute defaulting mode
114 * ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if
115 * none of these applies.
116 * @param value A string representing the attribute's default value,
117 * or null if there is none.
118 * @exception SAXException The application may raise an exception.
119 */
120 public abstract void attributeDecl (String eName,
121 String aName,
122 String type,
123 String mode,
124 String value)
125 throws SAXException;
126
127
128 /**
129 * Report an internal entity declaration.
130 *
131 * <p>Only the effective (first) declaration for each entity
132 * will be reported. All parameter entities in the value
133 * will be expanded, but general entities will not.</p>
134 *
135 * @param name The name of the entity. If it is a parameter
136 * entity, the name will begin with '%'.
137 * @param value The replacement text of the entity.
138 * @exception SAXException The application may raise an exception.
139 * @see #externalEntityDecl
140 * @see org.xml.sax.DTDHandler#unparsedEntityDecl
141 */
142 public abstract void internalEntityDecl (String name, String value)
143 throws SAXException;
144
145
146 /**
147 * Report a parsed external entity declaration.
148 *
149 * <p>Only the effective (first) declaration for each entity
150 * will be reported.</p>
151 *
152 * <p>If the system identifier is a URL, the parser must resolve it
153 * fully before passing it to the application.</p>
154 *
155 * @param name The name of the entity. If it is a parameter
156 * entity, the name will begin with '%'.
157 * @param publicId The entity's public identifier, or null if none
158 * was given.
159 * @param systemId The entity's system identifier.
160 * @exception SAXException The application may raise an exception.
161 * @see #internalEntityDecl
162 * @see org.xml.sax.DTDHandler#unparsedEntityDecl
163 */
164 public abstract void externalEntityDecl (String name, String publicId,
165 String systemId)
166 throws SAXException;
167
168 }
169
170 // end of DeclHandler.java