1//
2// SAXException.h
3//
4// Library: XML
5// Package: SAX
6// Module: SAX
7//
8// SAX exception classes.
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_SAXException_INCLUDED
18#define SAX_SAXException_INCLUDED
19
20
21#include "Poco/XML/XML.h"
22#include "Poco/XML/XMLException.h"
23#include "Poco/XML/XMLString.h"
24
25
26namespace Poco {
27namespace XML {
28
29
30POCO_DECLARE_EXCEPTION(XML_API, SAXException, XMLException)
31 /// The base class for all SAX-related exceptions like SAXParseException,
32 /// SAXNotRecognizedException or SAXNotSupportedException.
33 ///
34 /// This class can contain basic error or warning information from either the XML parser
35 /// or the application: a parser writer or application writer can subclass it to provide
36 /// additional functionality. SAX handlers may throw this exception or any exception subclassed
37 /// from it.
38 ///
39 /// If the application needs to pass through other types of exceptions, it must wrap those exceptions
40 /// in a SAXException or an exception derived from a SAXException.
41 ///
42 /// If the parser or application needs to include information about a specific location in an XML
43 /// document, it should use the SAXParseException subclass.
44
45
46POCO_DECLARE_EXCEPTION(XML_API, SAXNotRecognizedException, SAXException)
47 /// Exception class for an unrecognized identifier.
48 ///
49 /// An XMLReader will throw this exception when it finds an unrecognized feature or property
50 /// identifier; SAX applications and extensions may use this class for other, similar purposes.
51
52
53POCO_DECLARE_EXCEPTION(XML_API, SAXNotSupportedException, SAXException)
54 /// Exception class for an unsupported operation.
55 ///
56 /// An XMLReader will throw this exception when it recognizes a feature or property identifier,
57 /// but cannot perform the requested operation (setting a state or value). Other SAX2 applications
58 /// and extensions may use this class for similar purposes.
59
60
61class Locator;
62
63
64class XML_API SAXParseException: public SAXException
65 /// Encapsulate an XML parse error or warning.
66 ///
67 /// This exception may include information for locating the error in the original XML document,
68 /// as if it came from a Locator object. Note that although the application will receive a
69 /// SAXParseException as the argument to the handlers in the ErrorHandler interface, the application
70 /// is not actually required to throw the exception; instead, it can simply read the information in it
71 /// and take a different action.
72 ///
73 /// Since this exception is a subclass of SAXException, it inherits the ability to wrap another exception.
74{
75public:
76 SAXParseException(const std::string& msg, const Locator& loc);
77 /// Create a new SAXParseException from a message and a Locator.
78
79 SAXParseException(const std::string& msg, const Locator& loc, const Poco::Exception& exc);
80 /// Wrap an existing exception in a SAXParseException.
81
82 SAXParseException(const std::string& msg, const XMLString& publicId, const XMLString& systemId, int lineNumber, int columnNumber);
83 /// Create a new SAXParseException with an embedded exception.
84 ///
85 /// This constructor is most useful for parser writers.
86 /// All parameters except the message are as if they were provided by a Locator.
87 /// For example, if the system identifier is a URL (including relative filename),
88 /// the caller must resolve it fully before creating the exception.
89
90 SAXParseException(const std::string& msg, const XMLString& publicId, const XMLString& systemId, int lineNumber, int columnNumber, const Poco::Exception& exc);
91 /// Create a new SAXParseException.
92 ///
93 /// This constructor is most useful for parser writers.
94 /// All parameters except the message are as if they were provided by a Locator.
95 /// For example, if the system identifier is a URL (including relative filename),
96 /// the caller must resolve it fully before creating the exception.
97
98 SAXParseException(const SAXParseException& exc);
99 /// Creates a new SAXParseException from another one.
100
101 ~SAXParseException() throw();
102 /// Destroy the exception.
103
104 SAXParseException& operator = (const SAXParseException& exc);
105 /// Assignment operator.
106
107 const char* name() const throw();
108 /// Returns a static string describing the exception.
109
110 const char* className() const throw();
111 /// Returns the name of the exception class.
112
113 Poco::Exception* clone() const;
114 /// Creates an exact copy of the exception.
115
116 void rethrow() const;
117 /// (Re)Throws the exception.
118
119 const XMLString& getPublicId() const;
120 /// Get the public identifier of the entity where the exception occurred.
121
122 const XMLString& getSystemId() const;
123 /// Get the system identifier of the entity where the exception occurred.
124
125 int getLineNumber() const;
126 /// The line number of the end of the text where the exception occurred.
127 /// The first line is line 1.
128
129 int getColumnNumber() const;
130 /// The column number of the end of the text where the exception occurred.
131 /// The first column in a line is position 1.
132
133protected:
134 static std::string buildMessage(const std::string& msg, const XMLString& publicId, const XMLString& systemId, int lineNumber, int columnNumber);
135
136private:
137 SAXParseException();
138
139 XMLString _publicId;
140 XMLString _systemId;
141 int _lineNumber;
142 int _columnNumber;
143};
144
145
146//
147// inlines
148//
149inline const XMLString& SAXParseException::getPublicId() const
150{
151 return _publicId;
152}
153
154
155inline const XMLString& SAXParseException::getSystemId() const
156{
157 return _systemId;
158}
159
160
161inline int SAXParseException::getLineNumber() const
162{
163 return _lineNumber;
164}
165
166
167inline int SAXParseException::getColumnNumber() const
168{
169 return _columnNumber;
170}
171
172
173} } // namespace Poco::XML
174
175
176#endif // SAX_SAXException_INCLUDED
177