01: // SAX DTD handler.
02: // No warranty; no copyright -- use this as you will.
03: // $Id: DTDHandler.java,v 1.1 2004/12/05 04:06:21 csilva Exp $
04:
05: package org.xml.sax;
06:
07: /**
08: * Receive notification of basic DTD-related events.
09: *
10: * <p>If a SAX application needs information about notations and
11: * unparsed entities, then the application implements this
12: * interface and registers an instance with the SAX parser using
13: * the parser's setDTDHandler method. The parser uses the
14: * instance to report notation and unparsed entity declarations to
15: * the application.</p>
16: *
17: * <p>The SAX parser may report these events in any order, regardless
18: * of the order in which the notations and unparsed entities were
19: * declared; however, all DTD events must be reported after the
20: * document handler's startDocument event, and before the first
21: * startElement event.</p>
22: *
23: * <p>It is up to the application to store the information for
24: * future use (perhaps in a hash table or object tree).
25: * If the application encounters attributes of type "NOTATION",
26: * "ENTITY", or "ENTITIES", it can use the information that it
27: * obtained through this interface to find the entity and/or
28: * notation corresponding with the attribute value.</p>
29: *
30: * <p>The HandlerBase class provides a default implementation
31: * of this interface, which simply ignores the events.</p>
32: *
33: * @author David Megginson (ak117@freenet.carleton.ca)
34: * @version 1.0
35: * @see org.xml.sax.Parser#setDTDHandler
36: * @see org.xml.sax.HandlerBase
37: */
38: public interface DTDHandler {
39:
40: /**
41: * Receive notification of a notation declaration event.
42: *
43: * <p>It is up to the application to record the notation for later
44: * reference, if necessary.</p>
45: *
46: * <p>If a system identifier is present, and it is a URL, the SAX
47: * parser must resolve it fully before passing it to the
48: * application.</p>
49: *
50: * @param name The notation name.
51: * @param publicId The notation's public identifier, or null if
52: * none was given.
53: * @param systemId The notation's system identifier, or null if
54: * none was given.
55: * @exception org.xml.sax.SAXException Any SAX exception, possibly
56: * wrapping another exception.
57: * @see #unparsedEntityDecl
58: * @see org.xml.sax.AttributeList
59: */
60: public abstract void notationDecl(String name, String publicId,
61: String systemId) throws SAXException;
62:
63: /**
64: * Receive notification of an unparsed entity declaration event.
65: *
66: * <p>Note that the notation name corresponds to a notation
67: * reported by the notationDecl() event. It is up to the
68: * application to record the entity for later reference, if
69: * necessary.</p>
70: *
71: * <p>If the system identifier is a URL, the parser must resolve it
72: * fully before passing it to the application.</p>
73: *
74: * @exception org.xml.sax.SAXException Any SAX exception, possibly
75: * wrapping another exception.
76: * @param name The unparsed entity's name.
77: * @param publicId The entity's public identifier, or null if none
78: * was given.
79: * @param systemId The entity's system identifier (it must always
80: * have one).
81: * @param notation name The name of the associated notation.
82: * @see #notationDecl
83: * @see org.xml.sax.AttributeList
84: */
85: public abstract void unparsedEntityDecl(String name,
86: String publicId, String systemId, String notationName)
87: throws SAXException;
88:
89: }
|