001 /*
002 * Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 // DeclHandler.java - Optional handler for DTD declaration events.
027 // http://www.saxproject.org
028 // Public Domain: no warranty.
029 // $Id: DeclHandler.java,v 1.2 2004/11/03 22:49:08 jsuttor Exp $
030 package org.xml.sax.ext;
031
032 import org.xml.sax.SAXException;
033
034 /**
035 * SAX2 extension handler for DTD declaration events.
036 *
037 * <blockquote>
038 * <em>This module, both source code and documentation, is in the
039 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
040 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
041 * for further information.
042 * </blockquote>
043 *
044 * <p>This is an optional extension handler for SAX2 to provide more
045 * complete information about DTD declarations in an XML document.
046 * XML readers are not required to recognize this handler, and it
047 * is not part of core-only SAX2 distributions.</p>
048 *
049 * <p>Note that data-related DTD declarations (unparsed entities and
050 * notations) are already reported through the {@link
051 * org.xml.sax.DTDHandler DTDHandler} interface.</p>
052 *
053 * <p>If you are using the declaration handler together with a lexical
054 * handler, all of the events will occur between the
055 * {@link org.xml.sax.ext.LexicalHandler#startDTD startDTD} and the
056 * {@link org.xml.sax.ext.LexicalHandler#endDTD endDTD} events.</p>
057 *
058 * <p>To set the DeclHandler for an XML reader, use the
059 * {@link org.xml.sax.XMLReader#setProperty setProperty} method
060 * with the property name
061 * <code>http://xml.org/sax/properties/declaration-handler</code>
062 * and an object implementing this interface (or null) as the value.
063 * If the reader does not report declaration events, it will throw a
064 * {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}
065 * when you attempt to register the handler.</p>
066 *
067 * @since SAX 2.0 (extensions 1.0)
068 * @author David Megginson
069 * @version 2.0.1 (sax2r2)
070 */
071 public interface DeclHandler {
072
073 /**
074 * Report an element type declaration.
075 *
076 * <p>The content model will consist of the string "EMPTY", the
077 * string "ANY", or a parenthesised group, optionally followed
078 * by an occurrence indicator. The model will be normalized so
079 * that all parameter entities are fully resolved and all whitespace
080 * is removed,and will include the enclosing parentheses. Other
081 * normalization (such as removing redundant parentheses or
082 * simplifying occurrence indicators) is at the discretion of the
083 * parser.</p>
084 *
085 * @param name The element type name.
086 * @param model The content model as a normalized string.
087 * @exception SAXException The application may raise an exception.
088 */
089 public abstract void elementDecl(String name, String model)
090 throws SAXException;
091
092 /**
093 * Report an attribute type declaration.
094 *
095 * <p>Only the effective (first) declaration for an attribute will
096 * be reported. The type will be one of the strings "CDATA",
097 * "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY",
098 * "ENTITIES", a parenthesized token group with
099 * the separator "|" and all whitespace removed, or the word
100 * "NOTATION" followed by a space followed by a parenthesized
101 * token group with all whitespace removed.</p>
102 *
103 * <p>The value will be the value as reported to applications,
104 * appropriately normalized and with entity and character
105 * references expanded. </p>
106 *
107 * @param eName The name of the associated element.
108 * @param aName The name of the attribute.
109 * @param type A string representing the attribute type.
110 * @param mode A string representing the attribute defaulting mode
111 * ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if
112 * none of these applies.
113 * @param value A string representing the attribute's default value,
114 * or null if there is none.
115 * @exception SAXException The application may raise an exception.
116 */
117 public abstract void attributeDecl(String eName, String aName,
118 String type, String mode, String value) throws SAXException;
119
120 /**
121 * Report an internal entity declaration.
122 *
123 * <p>Only the effective (first) declaration for each entity
124 * will be reported. All parameter entities in the value
125 * will be expanded, but general entities will not.</p>
126 *
127 * @param name The name of the entity. If it is a parameter
128 * entity, the name will begin with '%'.
129 * @param value The replacement text of the entity.
130 * @exception SAXException The application may raise an exception.
131 * @see #externalEntityDecl
132 * @see org.xml.sax.DTDHandler#unparsedEntityDecl
133 */
134 public abstract void internalEntityDecl(String name, String value)
135 throws SAXException;
136
137 /**
138 * Report a parsed external entity declaration.
139 *
140 * <p>Only the effective (first) declaration for each entity
141 * will be reported.</p>
142 *
143 * <p>If the system identifier is a URL, the parser must resolve it
144 * fully before passing it to the application.</p>
145 *
146 * @param name The name of the entity. If it is a parameter
147 * entity, the name will begin with '%'.
148 * @param publicId The entity's public identifier, or null if none
149 * was given.
150 * @param systemId The entity's system identifier.
151 * @exception SAXException The application may raise an exception.
152 * @see #internalEntityDecl
153 * @see org.xml.sax.DTDHandler#unparsedEntityDecl
154 */
155 public abstract void externalEntityDecl(String name,
156 String publicId, String systemId) throws SAXException;
157
158 }
159
160 // end of DeclHandler.java
|