1
2
3
4
5
6 package org.xml.sax;
7
8 import java.io.InputStream;
9 import java.io.Reader;
10
11 /***
12 * A single input source for an XML entity.
13 *
14 * <blockquote>
15 * <em>This module, both source code and documentation, is in the
16 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
17 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
18 * for further information.
19 * </blockquote>
20 *
21 * <p>This class allows a SAX application to encapsulate information
22 * about an input source in a single object, which may include
23 * a public identifier, a system identifier, a byte stream (possibly
24 * with a specified encoding), and/or a character stream.</p>
25 *
26 * <p>There are two places that the application can deliver an
27 * input source to the parser: as the argument to the Parser.parse
28 * method, or as the return value of the EntityResolver.resolveEntity
29 * method.</p>
30 *
31 * <p>The SAX parser will use the InputSource object to determine how
32 * to read XML input. If there is a character stream available, the
33 * parser will read that stream directly, disregarding any text
34 * encoding declaration found in that stream.
35 * If there is no character stream, but there is
36 * a byte stream, the parser will use that byte stream, using the
37 * encoding specified in the InputSource or else (if no encoding is
38 * specified) autodetecting the character encoding using an algorithm
39 * such as the one in the XML specification. If neither a character
40 * stream nor a
41 * byte stream is available, the parser will attempt to open a URI
42 * connection to the resource identified by the system
43 * identifier.</p>
44 *
45 * <p>An InputSource object belongs to the application: the SAX parser
46 * shall never modify it in any way (it may modify a copy if
47 * necessary). However, standard processing of both byte and
48 * character streams is to close them on as part of end-of-parse cleanup,
49 * so applications should not attempt to re-use such streams after they
50 * have been handed to a parser. </p>
51 *
52 * @since SAX 1.0
53 * @author David Megginson
54 * @version 2.0.1 (sax2r2)
55 * @see org.xml.sax.XMLReader#parse(org.xml.sax.InputSource)
56 * @see org.xml.sax.EntityResolver#resolveEntity
57 * @see java.io.InputStream
58 * @see java.io.Reader
59 */
60 public class InputSource {
61
62 /***
63 * Zero-argument default constructor.
64 *
65 * @see #setPublicId
66 * @see #setSystemId
67 * @see #setByteStream
68 * @see #setCharacterStream
69 * @see #setEncoding
70 */
71 public InputSource ()
72 {
73 }
74
75
76 /***
77 * Create a new input source with a system identifier.
78 *
79 * <p>Applications may use setPublicId to include a
80 * public identifier as well, or setEncoding to specify
81 * the character encoding, if known.</p>
82 *
83 * <p>If the system identifier is a URL, it must be fully
84 * resolved (it may not be a relative URL).</p>
85 *
86 * @param systemId The system identifier (URI).
87 * @see #setPublicId
88 * @see #setSystemId
89 * @see #setByteStream
90 * @see #setEncoding
91 * @see #setCharacterStream
92 */
93 public InputSource (String systemId)
94 {
95 setSystemId(systemId);
96 }
97
98
99 /***
100 * Create a new input source with a byte stream.
101 *
102 * <p>Application writers should use setSystemId() to provide a base
103 * for resolving relative URIs, may use setPublicId to include a
104 * public identifier, and may use setEncoding to specify the object's
105 * character encoding.</p>
106 *
107 * @param byteStream The raw byte stream containing the document.
108 * @see #setPublicId
109 * @see #setSystemId
110 * @see #setEncoding
111 * @see #setByteStream
112 * @see #setCharacterStream
113 */
114 public InputSource (InputStream byteStream)
115 {
116 setByteStream(byteStream);
117 }
118
119
120 /***
121 * Create a new input source with a character stream.
122 *
123 * <p>Application writers should use setSystemId() to provide a base
124 * for resolving relative URIs, and may use setPublicId to include a
125 * public identifier.</p>
126 *
127 * <p>The character stream shall not include a byte order mark.</p>
128 *
129 * @see #setPublicId
130 * @see #setSystemId
131 * @see #setByteStream
132 * @see #setCharacterStream
133 */
134 public InputSource (Reader characterStream)
135 {
136 setCharacterStream(characterStream);
137 }
138
139
140 /***
141 * Set the public identifier for this input source.
142 *
143 * <p>The public identifier is always optional: if the application
144 * writer includes one, it will be provided as part of the
145 * location information.</p>
146 *
147 * @param publicId The public identifier as a string.
148 * @see #getPublicId
149 * @see org.xml.sax.Locator#getPublicId
150 * @see org.xml.sax.SAXParseException#getPublicId
151 */
152 public void setPublicId (String publicId)
153 {
154 this.publicId = publicId;
155 }
156
157
158 /***
159 * Get the public identifier for this input source.
160 *
161 * @return The public identifier, or null if none was supplied.
162 * @see #setPublicId
163 */
164 public String getPublicId ()
165 {
166 return publicId;
167 }
168
169
170 /***
171 * Set the system identifier for this input source.
172 *
173 * <p>The system identifier is optional if there is a byte stream
174 * or a character stream, but it is still useful to provide one,
175 * since the application can use it to resolve relative URIs
176 * and can include it in error messages and warnings (the parser
177 * will attempt to open a connection to the URI only if
178 * there is no byte stream or character stream specified).</p>
179 *
180 * <p>If the application knows the character encoding of the
181 * object pointed to by the system identifier, it can register
182 * the encoding using the setEncoding method.</p>
183 *
184 * <p>If the system identifier is a URL, it must be fully
185 * resolved (it may not be a relative URL).</p>
186 *
187 * @param systemId The system identifier as a string.
188 * @see #setEncoding
189 * @see #getSystemId
190 * @see org.xml.sax.Locator#getSystemId
191 * @see org.xml.sax.SAXParseException#getSystemId
192 */
193 public void setSystemId (String systemId)
194 {
195 this.systemId = systemId;
196 }
197
198
199 /***
200 * Get the system identifier for this input source.
201 *
202 * <p>The getEncoding method will return the character encoding
203 * of the object pointed to, or null if unknown.</p>
204 *
205 * <p>If the system ID is a URL, it will be fully resolved.</p>
206 *
207 * @return The system identifier, or null if none was supplied.
208 * @see #setSystemId
209 * @see #getEncoding
210 */
211 public String getSystemId ()
212 {
213 return systemId;
214 }
215
216
217 /***
218 * Set the byte stream for this input source.
219 *
220 * <p>The SAX parser will ignore this if there is also a character
221 * stream specified, but it will use a byte stream in preference
222 * to opening a URI connection itself.</p>
223 *
224 * <p>If the application knows the character encoding of the
225 * byte stream, it should set it with the setEncoding method.</p>
226 *
227 * @param byteStream A byte stream containing an XML document or
228 * other entity.
229 * @see #setEncoding
230 * @see #getByteStream
231 * @see #getEncoding
232 * @see java.io.InputStream
233 */
234 public void setByteStream (InputStream byteStream)
235 {
236 this.byteStream = byteStream;
237 }
238
239
240 /***
241 * Get the byte stream for this input source.
242 *
243 * <p>The getEncoding method will return the character
244 * encoding for this byte stream, or null if unknown.</p>
245 *
246 * @return The byte stream, or null if none was supplied.
247 * @see #getEncoding
248 * @see #setByteStream
249 */
250 public InputStream getByteStream ()
251 {
252 return byteStream;
253 }
254
255
256 /***
257 * Set the character encoding, if known.
258 *
259 * <p>The encoding must be a string acceptable for an
260 * XML encoding declaration (see section 4.3.3 of the XML 1.0
261 * recommendation).</p>
262 *
263 * <p>This method has no effect when the application provides a
264 * character stream.</p>
265 *
266 * @param encoding A string describing the character encoding.
267 * @see #setSystemId
268 * @see #setByteStream
269 * @see #getEncoding
270 */
271 public void setEncoding (String encoding)
272 {
273 this.encoding = encoding;
274 }
275
276
277 /***
278 * Get the character encoding for a byte stream or URI.
279 * This value will be ignored when the application provides a
280 * character stream.
281 *
282 * @return The encoding, or null if none was supplied.
283 * @see #setByteStream
284 * @see #getSystemId
285 * @see #getByteStream
286 */
287 public String getEncoding ()
288 {
289 return encoding;
290 }
291
292
293 /***
294 * Set the character stream for this input source.
295 *
296 * <p>If there is a character stream specified, the SAX parser
297 * will ignore any byte stream and will not attempt to open
298 * a URI connection to the system identifier.</p>
299 *
300 * @param characterStream The character stream containing the
301 * XML document or other entity.
302 * @see #getCharacterStream
303 * @see java.io.Reader
304 */
305 public void setCharacterStream (Reader characterStream)
306 {
307 this.characterStream = characterStream;
308 }
309
310
311 /***
312 * Get the character stream for this input source.
313 *
314 * @return The character stream, or null if none was supplied.
315 * @see #setCharacterStream
316 */
317 public Reader getCharacterStream ()
318 {
319 return characterStream;
320 }
321
322
323
324
325
326 private String publicId;
327 private String systemId;
328 private InputStream byteStream;
329 private String encoding;
330 private Reader characterStream;
331
332 }
333
334