View Javadoc
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 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