removes unnecessary org.xml.sax; these are in SwingJS
[jalview.git] / unused / xml / sax / ext / DeclHandler.java
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.6 2004/04/22 13:28:49 dmegginson 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      * <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