1 /*
2 * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package org.xml.sax;
27
28 import java.io.IOException;
29 import java.io.Reader;
30 import java.io.InputStream;
31
32 /**
33 * A single input source for an XML entity.
34 *
35 * <p>This class allows a SAX application to encapsulate information
36 * about an input source in a single object, which may include
37 * a public identifier, a system identifier, a byte stream (possibly
38 * with a specified encoding), and/or a character stream.</p>
39 *
40 * <p>There are two places that the application can deliver an
41 * input source to the parser: as the argument to the Parser.parse
42 * method, or as the return value of the EntityResolver.resolveEntity
43 * method.</p>
44 *
45 * <p>The SAX parser will use the InputSource object to determine how
46 * to read XML input. If there is a character stream available, the
47 * parser will read that stream directly, disregarding any text
48 * encoding declaration found in that stream.
49 * If there is no character stream, but there is
50 * a byte stream, the parser will use that byte stream, using the
51 * encoding specified in the InputSource or else (if no encoding is
52 * specified) autodetecting the character encoding using an algorithm
53 * such as the one in the XML specification. If neither a character
54 * stream nor a
55 * byte stream is available, the parser will attempt to open a URI
56 * connection to the resource identified by the system
57 * identifier.</p>
58 *
59 * <p>An InputSource object belongs to the application: the SAX parser
60 * shall never modify it in any way (it may modify a copy if
61 * necessary). However, standard processing of both byte and
62 * character streams is to close them on as part of end-of-parse cleanup,
63 * so applications should not attempt to re-use such streams after they
64 * have been handed to a parser. </p>
65 *
66 * @since 1.4, SAX 1.0
67 * @author David Megginson
68 * @see org.xml.sax.XMLReader#parse(org.xml.sax.InputSource)
69 * @see org.xml.sax.EntityResolver#resolveEntity
70 * @see java.io.InputStream
71 * @see java.io.Reader
72 */
73 public class InputSource {
74
75 /**
76 * Zero-argument default constructor.
77 *
78 * @see #setPublicId
79 * @see #setSystemId
80 * @see #setByteStream
81 * @see #setCharacterStream
82 * @see #setEncoding
83 */
84 public InputSource ()
85 {
86 }
87
88
89 /**
90 * Create a new input source with a system identifier.
91 *
92 * <p>Applications may use setPublicId to include a
93 * public identifier as well, or setEncoding to specify
94 * the character encoding, if known.</p>
95 *
96 * <p>If the system identifier is a URL, it must be fully
97 * resolved (it may not be a relative URL).</p>
98 *
99 * @param systemId The system identifier (URI).
100 * @see #setPublicId
101 * @see #setSystemId
102 * @see #setByteStream
103 * @see #setEncoding
104 * @see #setCharacterStream
105 */
106 public InputSource (String systemId)
107 {
108 setSystemId(systemId);
109 }
110
111
112 /**
113 * Create a new input source with a byte stream.
114 *
115 * <p>Application writers should use setSystemId() to provide a base
116 * for resolving relative URIs, may use setPublicId to include a
117 * public identifier, and may use setEncoding to specify the object's
118 * character encoding.</p>
119 *
120 * @param byteStream The raw byte stream containing the document.
121 * @see #setPublicId
122 * @see #setSystemId
123 * @see #setEncoding
124 * @see #setByteStream
125 * @see #setCharacterStream
126 */
127 public InputSource (InputStream byteStream)
128 {
129 setByteStream(byteStream);
130 }
131
132
133 /**
134 * Create a new input source with a character stream.
135 *
136 * <p>Application writers should use setSystemId() to provide a base
137 * for resolving relative URIs, and may use setPublicId to include a
138 * public identifier.</p>
139 *
140 * <p>The character stream shall not include a byte order mark.</p>
141 *
142 * @see #setPublicId
143 * @see #setSystemId
144 * @see #setByteStream
145 * @see #setCharacterStream
146 */
147 public InputSource (Reader characterStream)
148 {
149 setCharacterStream(characterStream);
150 }
151
152
153 /**
154 * Set the public identifier for this input source.
155 *
156 * <p>The public identifier is always optional: if the application
157 * writer includes one, it will be provided as part of the
158 * location information.</p>
159 *
160 * @param publicId The public identifier as a string.
161 * @see #getPublicId
162 * @see org.xml.sax.Locator#getPublicId
163 * @see org.xml.sax.SAXParseException#getPublicId
164 */
165 public void setPublicId (String publicId)
166 {
167 this.publicId = publicId;
168 }
169
170
171 /**
172 * Get the public identifier for this input source.
173 *
174 * @return The public identifier, or null if none was supplied.
175 * @see #setPublicId
176 */
177 public String getPublicId ()
178 {
179 return publicId;
180 }
181
182
183 /**
184 * Set the system identifier for this input source.
185 *
186 * <p>The system identifier is optional if there is a byte stream
187 * or a character stream, but it is still useful to provide one,
188 * since the application can use it to resolve relative URIs
189 * and can include it in error messages and warnings (the parser
190 * will attempt to open a connection to the URI only if
191 * there is no byte stream or character stream specified).</p>
192 *
193 * <p>If the application knows the character encoding of the
194 * object pointed to by the system identifier, it can register
195 * the encoding using the setEncoding method.</p>
196 *
197 * <p>If the system identifier is a URL, it must be fully
198 * resolved (it may not be a relative URL).</p>
199 *
200 * @param systemId The system identifier as a string.
201 * @see #setEncoding
202 * @see #getSystemId
203 * @see org.xml.sax.Locator#getSystemId
204 * @see org.xml.sax.SAXParseException#getSystemId
205 */
206 public void setSystemId (String systemId)
207 {
208 this.systemId = systemId;
209 }
210
211
212 /**
213 * Get the system identifier for this input source.
214 *
215 * <p>The getEncoding method will return the character encoding
216 * of the object pointed to, or null if unknown.</p>
217 *
218 * <p>If the system ID is a URL, it will be fully resolved.</p>
219 *
220 * @return The system identifier, or null if none was supplied.
221 * @see #setSystemId
222 * @see #getEncoding
223 */
224 public String getSystemId ()
225 {
226 return systemId;
227 }
228
229
230 /**
231 * Set the byte stream for this input source.
232 *
233 * <p>The SAX parser will ignore this if there is also a character
234 * stream specified, but it will use a byte stream in preference
235 * to opening a URI connection itself.</p>
236 *
237 * <p>If the application knows the character encoding of the
238 * byte stream, it should set it with the setEncoding method.</p>
239 *
240 * @param byteStream A byte stream containing an XML document or
241 * other entity.
242 * @see #setEncoding
243 * @see #getByteStream
244 * @see #getEncoding
245 * @see java.io.InputStream
246 */
247 public void setByteStream (InputStream byteStream)
248 {
249 this.byteStream = byteStream;
250 }
251
252
253 /**
254 * Get the byte stream for this input source.
255 *
256 * <p>The getEncoding method will return the character
257 * encoding for this byte stream, or null if unknown.</p>
258 *
259 * @return The byte stream, or null if none was supplied.
260 * @see #getEncoding
261 * @see #setByteStream
262 */
263 public InputStream getByteStream ()
264 {
265 return byteStream;
266 }
267
268
269 /**
270 * Set the character encoding, if known.
271 *
272 * <p>The encoding must be a string acceptable for an
273 * XML encoding declaration (see section 4.3.3 of the XML 1.0
274 * recommendation).</p>
275 *
276 * <p>This method has no effect when the application provides a
277 * character stream.</p>
278 *
279 * @param encoding A string describing the character encoding.
280 * @see #setSystemId
281 * @see #setByteStream
282 * @see #getEncoding
283 */
284 public void setEncoding (String encoding)
285 {
286 this.encoding = encoding;
287 }
288
289
290 /**
291 * Get the character encoding for a byte stream or URI.
292 * This value will be ignored when the application provides a
293 * character stream.
294 *
295 * @return The encoding, or null if none was supplied.
296 * @see #setByteStream
297 * @see #getSystemId
298 * @see #getByteStream
299 */
300 public String getEncoding ()
301 {
302 return encoding;
303 }
304
305
306 /**
307 * Set the character stream for this input source.
308 *
309 * <p>If there is a character stream specified, the SAX parser
310 * will ignore any byte stream and will not attempt to open
311 * a URI connection to the system identifier.</p>
312 *
313 * @param characterStream The character stream containing the
314 * XML document or other entity.
315 * @see #getCharacterStream
316 * @see java.io.Reader
317 */
318 public void setCharacterStream (Reader characterStream)
319 {
320 this.characterStream = characterStream;
321 }
322
323
324 /**
325 * Get the character stream for this input source.
326 *
327 * @return The character stream, or null if none was supplied.
328 * @see #setCharacterStream
329 */
330 public Reader getCharacterStream ()
331 {
332 return characterStream;
333 }
334
335 /**
336 * Indicates whether the {@code InputSource} object is empty. Empty is
337 * defined as follows:
338 * <ul>
339 * <li>All of the input sources, including the public identifier, system
340 * identifier, byte stream, and character stream, are {@code null}.
341 * </li>
342 * <li>The public identifier and system identifier are {@code null}, and
343 * byte and character stream are either {@code null} or contain no byte
344 * or character.
345 * <p>
346 * Note that this method will reset the byte stream if it is provided, or
347 * the character stream if the byte stream is not provided.
348 * </li>
349 * </ul>
350 * <p>
351 * In case of error while checking the byte or character stream, the method
352 * will return false to allow the XML processor to handle the error.
353 *
354 * @return true if the {@code InputSource} object is empty, false otherwise
355 */
356 public boolean isEmpty() {
357 return (publicId == null && systemId == null && isStreamEmpty());
358 }
359
360 private boolean isStreamEmpty() {
361 boolean empty = true;
362 try {
363 if (byteStream != null) {
364 byteStream.reset();
365 int bytesRead = byteStream.available();
366 if (bytesRead > 0) {
367 return false;
368 }
369 }
370
371 if (characterStream != null) {
372 characterStream.reset();
373 int c = characterStream.read();
374 characterStream.reset();
375 if (c != -1) {
376 return false;
377 }
378 }
379 } catch (IOException ex) {
380 //in case of error, return false
381 return false;
382 }
383
384 return empty;
385 }
386 ////////////////////////////////////////////////////////////////////
387 // Internal state.
388 ////////////////////////////////////////////////////////////////////
389
390 private String publicId;
391 private String systemId;
392 private InputStream byteStream;
393 private String encoding;
394 private Reader characterStream;
395
396 }
397
398 // end of InputSource.java