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
26namespace Poco {
27namespace XML {
28
29
30class 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{
54public:
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
124private:
125 XMLString _publicId;
126 XMLString _systemId;
127 XMLString _encoding;
128 XMLByteInputStream* _bistr;
129 XMLCharInputStream* _cistr;
130};
131
132
133//
134// inlines
135//
136inline const XMLString& InputSource::getPublicId() const
137{
138 return _publicId;
139}
140
141
142inline const XMLString& InputSource::getSystemId() const
143{
144 return _systemId;
145}
146
147
148inline const XMLString& InputSource::getEncoding() const
149{
150 return _encoding;
151}
152
153
154inline XMLByteInputStream* InputSource::getByteStream() const
155{
156 return _bistr;
157}
158
159
160inline XMLCharInputStream* InputSource::getCharacterStream() const
161{
162 return _cistr;
163}
164
165
166} } // namespace Poco::XML
167
168
169#endif // SAX_InputSource_INCLUDED
170