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