1 | // |
2 | // XMLReader.h |
3 | // |
4 | // Library: XML |
5 | // Package: SAX |
6 | // Module: SAX |
7 | // |
8 | // SAX2 XMLReader Interface. |
9 | // |
10 | // Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH. |
11 | // and Contributors. |
12 | // |
13 | // SPDX-License-Identifier: BSL-1.0 |
14 | // |
15 | |
16 | |
17 | #ifndef SAX_XMLReader_INCLUDED |
18 | #define SAX_XMLReader_INCLUDED |
19 | |
20 | |
21 | #include "Poco/XML/XML.h" |
22 | #include "Poco/XML/XMLString.h" |
23 | |
24 | |
25 | namespace Poco { |
26 | namespace XML { |
27 | |
28 | |
29 | class EntityResolver; |
30 | class DTDHandler; |
31 | class ContentHandler; |
32 | class ErrorHandler; |
33 | class InputSource; |
34 | class LexicalHandler; |
35 | class NamespaceHandler; |
36 | |
37 | |
38 | class XML_API XMLReader |
39 | /// Interface for reading an XML document using callbacks. |
40 | /// XMLReader is the interface that an XML parser's SAX2 driver must |
41 | /// implement. This interface allows an application to set and |
42 | /// query features and properties in the parser, to register event handlers |
43 | /// for document processing, and to initiate a document parse. |
44 | /// All SAX interfaces are assumed to be synchronous: the parse methods must not |
45 | /// return until parsing is complete, and readers |
46 | /// must wait for an event-handler callback to return before reporting the next event. |
47 | { |
48 | public: |
49 | virtual void setEntityResolver(EntityResolver* pResolver) = 0; |
50 | /// Allow an application to register an entity resolver. |
51 | /// |
52 | /// If the application does not register an entity resolver, the |
53 | /// XMLReader will perform its own default resolution. |
54 | /// |
55 | /// Applications may register a new or different resolver in the middle of a |
56 | /// parse, and the SAX parser must begin using the new resolver immediately. |
57 | |
58 | virtual EntityResolver* getEntityResolver() const = 0; |
59 | /// Return the current entity resolver. |
60 | |
61 | virtual void setDTDHandler(DTDHandler* pDTDHandler) = 0; |
62 | /// Allow an application to register a DTD event handler. |
63 | /// |
64 | /// If the application does not register a DTD handler, all DTD events reported by |
65 | /// the SAX parser will be silently ignored. |
66 | /// |
67 | /// Applications may register a new or different handler in the middle of a parse, |
68 | /// and the SAX parser must begin using the new handler immediately. |
69 | |
70 | virtual DTDHandler* getDTDHandler() const = 0; |
71 | /// Return the current DTD handler. |
72 | |
73 | virtual void setContentHandler(ContentHandler* pContentHandler) = 0; |
74 | /// Allow an application to register a content event handler. |
75 | /// |
76 | /// If the application does not register a content handler, all content events |
77 | /// reported by the SAX parser will be silently ignored. |
78 | /// |
79 | /// Applications may register a new or different handler in the middle of a parse, |
80 | /// and the SAX parser must begin using the new handler immediately. |
81 | |
82 | virtual ContentHandler* getContentHandler() const = 0; |
83 | /// Return the current content handler. |
84 | |
85 | virtual void setErrorHandler(ErrorHandler* pErrorHandler) = 0; |
86 | /// Allow an application to register an error event handler. |
87 | /// |
88 | /// If the application does not register an error handler, all error events reported by |
89 | /// the SAX parser will be silently ignored; however, normal processing may not continue. |
90 | /// It is highly recommended that all SAX applications implement an error handler to avoid |
91 | /// unexpected bugs. |
92 | /// |
93 | /// Applications may register a new or different handler in the middle of a parse, and the |
94 | /// SAX parser must begin using the new handler immediately. |
95 | |
96 | virtual ErrorHandler* getErrorHandler() const = 0; |
97 | /// Return the current error handler. |
98 | |
99 | virtual void setFeature(const XMLString& featureId, bool state) = 0; |
100 | /// Set the state of a feature. |
101 | /// |
102 | /// The feature name is any fully-qualified URI. It is possible for an XMLReader to |
103 | /// expose a feature value but to be unable to change the current value. Some feature |
104 | /// values may be immutable or mutable only in specific contexts, such as before, during, |
105 | /// or after a parse. |
106 | /// |
107 | /// All XMLReaders are required to support setting http://xml.org/sax/features/namespaces |
108 | /// to true and http://xml.org/sax/features/namespace-prefixes to false. |
109 | |
110 | virtual bool getFeature(const XMLString& featureId) const = 0; |
111 | /// Look up the value of a feature. |
112 | /// |
113 | /// The feature name is any fully-qualified URI. It is possible for an XMLReader |
114 | /// to recognize a feature name but temporarily be unable to return its value. |
115 | /// Some feature values may be available only in specific contexts, such as before, |
116 | /// during, or after a parse. Also, some feature values may not be programmatically |
117 | /// accessible. (In the case of an adapter for SAX1 Parser, there is no |
118 | /// implementation-independent way to expose whether the underlying parser is performing |
119 | /// validation, expanding external entities, and so forth.) |
120 | /// |
121 | /// All XMLReaders are required to recognize the |
122 | /// http://xml.org/sax/features/namespaces and the |
123 | /// http://xml.org/sax/features/namespace-prefixes feature names. |
124 | /// Implementors are free (and encouraged) to invent their own features, |
125 | /// using names built on their own URIs. |
126 | |
127 | virtual void setProperty(const XMLString& propertyId, const XMLString& value) = 0; |
128 | /// Set the value of a property. |
129 | /// |
130 | /// The property name is any fully-qualified URI. It is possible for an XMLReader |
131 | /// to recognize a property name but to be unable to change the current value. |
132 | /// Some property values may be immutable or mutable only in specific contexts, |
133 | /// such as before, during, or after a parse. |
134 | /// |
135 | /// XMLReaders are not required to recognize setting any specific property names, though a |
136 | /// core set is defined by SAX2. |
137 | /// |
138 | /// This method is also the standard mechanism for setting extended handlers. |
139 | |
140 | virtual void setProperty(const XMLString& propertyId, void* value) = 0; |
141 | /// Set the value of a property. |
142 | /// See also setProperty(const XMLString&, const XMLString&). |
143 | |
144 | virtual void* getProperty(const XMLString& propertyId) const = 0; |
145 | /// Look up the value of a property. |
146 | /// String values are returned as XMLChar* |
147 | /// The property name is any fully-qualified URI. It is possible for an XMLReader to |
148 | /// recognize a property name but temporarily be unable to return its value. Some property |
149 | /// values may be available only in specific contexts, such as before, during, or after a parse. |
150 | /// |
151 | /// XMLReaders are not required to recognize any specific property names, though an initial |
152 | /// core set is documented for SAX2. |
153 | /// |
154 | /// Implementors are free (and encouraged) to invent their own properties, using names |
155 | /// built on their own URIs. |
156 | |
157 | virtual void parse(InputSource* pSource) = 0; |
158 | /// Parse an XML document. |
159 | /// |
160 | /// The application can use this method to instruct the XML reader to begin parsing an |
161 | /// XML document from any valid input source (a character stream, a byte stream, or a URI). |
162 | /// |
163 | /// Applications may not invoke this method while a parse is in progress (they should create |
164 | /// a new XMLReader instead for each nested XML document). Once a parse is complete, an |
165 | /// application may reuse the same XMLReader object, possibly with a different input source. |
166 | /// Configuration of the XMLReader object (such as handler bindings and values established for |
167 | /// feature flags and properties) is unchanged by completion of a parse, unless the definition of that |
168 | /// aspect of the configuration explicitly specifies other behavior. (For example, feature flags or |
169 | /// properties exposing characteristics of the document being parsed.) |
170 | /// |
171 | /// During the parse, the XMLReader will provide information about the XML document through the registered |
172 | /// event handlers. |
173 | /// |
174 | /// This method is synchronous: it will not return until parsing has ended. If a client application |
175 | /// wants to terminate parsing early, it should throw an exception. |
176 | |
177 | virtual void parse(const XMLString& systemId) = 0; |
178 | /// Parse an XML document from a system identifier. |
179 | /// See also parse(InputSource*). |
180 | |
181 | virtual void parseMemoryNP(const char* xml, std::size_t size) = 0; |
182 | /// Parse an XML document from memory. |
183 | /// See also parse(InputSource*). |
184 | |
185 | // SAX Features |
186 | static const XMLString FEATURE_VALIDATION; |
187 | static const XMLString FEATURE_NAMESPACES; |
188 | static const XMLString FEATURE_NAMESPACE_PREFIXES; |
189 | static const XMLString FEATURE_EXTERNAL_GENERAL_ENTITIES; |
190 | static const XMLString FEATURE_EXTERNAL_PARAMETER_ENTITIES; |
191 | static const XMLString FEATURE_STRING_INTERNING; |
192 | |
193 | // SAX Properties |
194 | static const XMLString PROPERTY_DECLARATION_HANDLER; |
195 | static const XMLString PROPERTY_LEXICAL_HANDLER; |
196 | |
197 | protected: |
198 | virtual ~XMLReader(); |
199 | }; |
200 | |
201 | |
202 | } } // namespace Poco::XML |
203 | |
204 | |
205 | #endif // SAX_XMLReader_INCLUDED |
206 | |