1 | // |
2 | // InputSource.h |
3 | // |
4 | // Library: XML |
5 | // Package: SAX |
6 | // Module: SAX |
7 | // |
8 | // SAX InputSource - A single input source for an XML entity. |
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_InputSource_INCLUDED |
18 | #define SAX_InputSource_INCLUDED |
19 | |
20 | |
21 | #include "Poco/XML/XML.h" |
22 | #include "Poco/XML/XMLString.h" |
23 | #include "Poco/XML/XMLStream.h" |
24 | |
25 | |
26 | namespace Poco { |
27 | namespace XML { |
28 | |
29 | |
30 | class XML_API InputSource |
31 | /// This class allows a SAX application to encapsulate information about an input |
32 | /// source in a single object, which may include a public identifier, a system |
33 | /// identifier, a byte stream (possibly with a specified encoding), and/or a character |
34 | /// stream. |
35 | /// |
36 | /// There are two places that the application can deliver an input source to the |
37 | /// parser: as the argument to the Parser.parse method, or as the return value of the |
38 | /// EntityResolver::resolveEntity() method. |
39 | /// |
40 | /// The SAX parser will use the InputSource object to determine how to read XML input. |
41 | /// If there is a character stream available, the parser will read that stream directly, |
42 | /// disregarding any text encoding declaration found in that stream. If there is no character |
43 | /// stream, but there is a byte stream, the parser will use that byte stream, using the |
44 | /// encoding specified in the InputSource or else (if no encoding is specified) autodetecting |
45 | /// the character encoding using an algorithm such as the one in the XML specification. |
46 | /// If neither a character stream nor a byte stream is available, the parser will attempt |
47 | /// to open a URI connection to the resource identified by the system identifier. |
48 | /// |
49 | /// An InputSource object belongs to the application: the SAX parser shall never modify it in |
50 | /// any way (it may modify a copy if necessary). However, standard processing of both byte and |
51 | /// character streams is to close them on as part of end-of-parse cleanup, so applications should |
52 | /// not attempt to re-use such streams after they have been handed to a parser. |
53 | { |
54 | public: |
55 | InputSource(); |
56 | /// Zero-argument default constructor. |
57 | |
58 | InputSource(const XMLString& systemId); |
59 | /// Creates a new input source with a system identifier. |
60 | /// Applications may use setPublicId to include a public identifier as well, |
61 | /// or setEncoding to specify the character encoding, if known. |
62 | /// |
63 | /// If the system identifier is a URL, it must be fully resolved (it may not |
64 | /// be a relative URL). |
65 | |
66 | InputSource(XMLByteInputStream& istr); |
67 | /// Creates a new input source with a byte stream. |
68 | /// |
69 | /// Application writers should use setSystemId() to provide a base for resolving |
70 | /// relative URIs, may use setPublicId to include a public identifier, and may use |
71 | /// setEncoding to specify the object's character encoding. |
72 | |
73 | ~InputSource(); |
74 | /// Destroys the InputSource. |
75 | |
76 | void setPublicId(const XMLString& publicId); |
77 | /// Set the public identifier for this input source. |
78 | /// |
79 | /// The public identifier is always optional: if the application writer includes one, |
80 | /// it will be provided as part of the location information. |
81 | |
82 | void setSystemId(const XMLString& systemId); |
83 | /// Set the system identifier for this input source. |
84 | /// |
85 | /// The system identifier is optional if there is a byte stream or a character stream, |
86 | /// but it is still useful to provide one, since the application can use it to resolve |
87 | /// relative URIs and can include it in error messages and warnings (the parser will |
88 | /// attempt to open a connection to the URI only if there is no byte stream or character |
89 | /// stream specified). |
90 | /// |
91 | /// If the application knows the character encoding of the object pointed to by the system |
92 | /// identifier, it can register the encoding using the setEncoding method. |
93 | /// |
94 | /// If the system identifier is a URL, it must be fully resolved (it may not be a relative URL). |
95 | |
96 | const XMLString& getPublicId() const; |
97 | /// Get the public identifier for this input source. |
98 | |
99 | const XMLString& getSystemId() const; |
100 | /// Get the system identifier for this input source. |
101 | |
102 | void setByteStream(XMLByteInputStream& istr); |
103 | /// Set the byte stream for this input source. |
104 | /// The SAX parser will ignore this if there is also a character stream specified, but it |
105 | /// will use a byte stream in preference to opening a URI connection itself. |
106 | |
107 | XMLByteInputStream* getByteStream() const; |
108 | /// Get the byte stream for this input source. |
109 | |
110 | void setCharacterStream(XMLCharInputStream& istr); |
111 | /// Set the character stream for this input source. |
112 | |
113 | XMLCharInputStream* getCharacterStream() const; |
114 | /// Get the character stream for this input source. |
115 | |
116 | void setEncoding(const XMLString& encoding); |
117 | /// Set the character encoding, if known. |
118 | /// The encoding must be a string acceptable for an XML encoding declaration |
119 | /// (see section 4.3.3 of the XML 1.0 recommendation). |
120 | |
121 | const XMLString& getEncoding() const; |
122 | /// Get the character encoding for a byte stream or URI. |
123 | |
124 | private: |
125 | XMLString _publicId; |
126 | XMLString _systemId; |
127 | XMLString _encoding; |
128 | XMLByteInputStream* _bistr; |
129 | XMLCharInputStream* _cistr; |
130 | }; |
131 | |
132 | |
133 | // |
134 | // inlines |
135 | // |
136 | inline const XMLString& InputSource::getPublicId() const |
137 | { |
138 | return _publicId; |
139 | } |
140 | |
141 | |
142 | inline const XMLString& InputSource::getSystemId() const |
143 | { |
144 | return _systemId; |
145 | } |
146 | |
147 | |
148 | inline const XMLString& InputSource::getEncoding() const |
149 | { |
150 | return _encoding; |
151 | } |
152 | |
153 | |
154 | inline XMLByteInputStream* InputSource::getByteStream() const |
155 | { |
156 | return _bistr; |
157 | } |
158 | |
159 | |
160 | inline XMLCharInputStream* InputSource::getCharacterStream() const |
161 | { |
162 | return _cistr; |
163 | } |
164 | |
165 | |
166 | } } // namespace Poco::XML |
167 | |
168 | |
169 | #endif // SAX_InputSource_INCLUDED |
170 | |