001 /*
002 * Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 // SAX input source.
027 // http://www.saxproject.org
028 // No warranty; no copyright -- use this as you will.
029 // $Id: InputSource.java,v 1.2 2004/11/03 22:55:32 jsuttor Exp $
030 package org.xml.sax;
031
032 import java.io.Reader;
033 import java.io.InputStream;
034
035 /**
036 * A single input source for an XML entity.
037 *
038 * <blockquote>
039 * <em>This module, both source code and documentation, is in the
040 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
041 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
042 * for further information.
043 * </blockquote>
044 *
045 * <p>This class allows a SAX application to encapsulate information
046 * about an input source in a single object, which may include
047 * a public identifier, a system identifier, a byte stream (possibly
048 * with a specified encoding), and/or a character stream.</p>
049 *
050 * <p>There are two places that the application can deliver an
051 * input source to the parser: as the argument to the Parser.parse
052 * method, or as the return value of the EntityResolver.resolveEntity
053 * method.</p>
054 *
055 * <p>The SAX parser will use the InputSource object to determine how
056 * to read XML input. If there is a character stream available, the
057 * parser will read that stream directly, disregarding any text
058 * encoding declaration found in that stream.
059 * If there is no character stream, but there is
060 * a byte stream, the parser will use that byte stream, using the
061 * encoding specified in the InputSource or else (if no encoding is
062 * specified) autodetecting the character encoding using an algorithm
063 * such as the one in the XML specification. If neither a character
064 * stream nor a
065 * byte stream is available, the parser will attempt to open a URI
066 * connection to the resource identified by the system
067 * identifier.</p>
068 *
069 * <p>An InputSource object belongs to the application: the SAX parser
070 * shall never modify it in any way (it may modify a copy if
071 * necessary). However, standard processing of both byte and
072 * character streams is to close them on as part of end-of-parse cleanup,
073 * so applications should not attempt to re-use such streams after they
074 * have been handed to a parser. </p>
075 *
076 * @since SAX 1.0
077 * @author David Megginson
078 * @version 2.0.1 (sax2r2)
079 * @see org.xml.sax.XMLReader#parse(org.xml.sax.InputSource)
080 * @see org.xml.sax.EntityResolver#resolveEntity
081 * @see java.io.InputStream
082 * @see java.io.Reader
083 */
084 public class InputSource {
085
086 /**
087 * Zero-argument default constructor.
088 *
089 * @see #setPublicId
090 * @see #setSystemId
091 * @see #setByteStream
092 * @see #setCharacterStream
093 * @see #setEncoding
094 */
095 public InputSource() {
096 }
097
098 /**
099 * Create a new input source with a system identifier.
100 *
101 * <p>Applications may use setPublicId to include a
102 * public identifier as well, or setEncoding to specify
103 * the character encoding, if known.</p>
104 *
105 * <p>If the system identifier is a URL, it must be fully
106 * resolved (it may not be a relative URL).</p>
107 *
108 * @param systemId The system identifier (URI).
109 * @see #setPublicId
110 * @see #setSystemId
111 * @see #setByteStream
112 * @see #setEncoding
113 * @see #setCharacterStream
114 */
115 public InputSource(String systemId) {
116 setSystemId(systemId);
117 }
118
119 /**
120 * Create a new input source with a byte stream.
121 *
122 * <p>Application writers should use setSystemId() to provide a base
123 * for resolving relative URIs, may use setPublicId to include a
124 * public identifier, and may use setEncoding to specify the object's
125 * character encoding.</p>
126 *
127 * @param byteStream The raw byte stream containing the document.
128 * @see #setPublicId
129 * @see #setSystemId
130 * @see #setEncoding
131 * @see #setByteStream
132 * @see #setCharacterStream
133 */
134 public InputSource(InputStream byteStream) {
135 setByteStream(byteStream);
136 }
137
138 /**
139 * Create a new input source with a character stream.
140 *
141 * <p>Application writers should use setSystemId() to provide a base
142 * for resolving relative URIs, and may use setPublicId to include a
143 * public identifier.</p>
144 *
145 * <p>The character stream shall not include a byte order mark.</p>
146 *
147 * @see #setPublicId
148 * @see #setSystemId
149 * @see #setByteStream
150 * @see #setCharacterStream
151 */
152 public InputSource(Reader characterStream) {
153 setCharacterStream(characterStream);
154 }
155
156 /**
157 * Set the public identifier for this input source.
158 *
159 * <p>The public identifier is always optional: if the application
160 * writer includes one, it will be provided as part of the
161 * location information.</p>
162 *
163 * @param publicId The public identifier as a string.
164 * @see #getPublicId
165 * @see org.xml.sax.Locator#getPublicId
166 * @see org.xml.sax.SAXParseException#getPublicId
167 */
168 public void setPublicId(String publicId) {
169 this .publicId = publicId;
170 }
171
172 /**
173 * Get the public identifier for this input source.
174 *
175 * @return The public identifier, or null if none was supplied.
176 * @see #setPublicId
177 */
178 public String getPublicId() {
179 return publicId;
180 }
181
182 /**
183 * Set the system identifier for this input source.
184 *
185 * <p>The system identifier is optional if there is a byte stream
186 * or a character stream, but it is still useful to provide one,
187 * since the application can use it to resolve relative URIs
188 * and can include it in error messages and warnings (the parser
189 * will attempt to open a connection to the URI only if
190 * there is no byte stream or character stream specified).</p>
191 *
192 * <p>If the application knows the character encoding of the
193 * object pointed to by the system identifier, it can register
194 * the encoding using the setEncoding method.</p>
195 *
196 * <p>If the system identifier is a URL, it must be fully
197 * resolved (it may not be a relative URL).</p>
198 *
199 * @param systemId The system identifier as a string.
200 * @see #setEncoding
201 * @see #getSystemId
202 * @see org.xml.sax.Locator#getSystemId
203 * @see org.xml.sax.SAXParseException#getSystemId
204 */
205 public void setSystemId(String systemId) {
206 this .systemId = systemId;
207 }
208
209 /**
210 * Get the system identifier for this input source.
211 *
212 * <p>The getEncoding method will return the character encoding
213 * of the object pointed to, or null if unknown.</p>
214 *
215 * <p>If the system ID is a URL, it will be fully resolved.</p>
216 *
217 * @return The system identifier, or null if none was supplied.
218 * @see #setSystemId
219 * @see #getEncoding
220 */
221 public String getSystemId() {
222 return systemId;
223 }
224
225 /**
226 * Set the byte stream for this input source.
227 *
228 * <p>The SAX parser will ignore this if there is also a character
229 * stream specified, but it will use a byte stream in preference
230 * to opening a URI connection itself.</p>
231 *
232 * <p>If the application knows the character encoding of the
233 * byte stream, it should set it with the setEncoding method.</p>
234 *
235 * @param byteStream A byte stream containing an XML document or
236 * other entity.
237 * @see #setEncoding
238 * @see #getByteStream
239 * @see #getEncoding
240 * @see java.io.InputStream
241 */
242 public void setByteStream(InputStream byteStream) {
243 this .byteStream = byteStream;
244 }
245
246 /**
247 * Get the byte stream for this input source.
248 *
249 * <p>The getEncoding method will return the character
250 * encoding for this byte stream, or null if unknown.</p>
251 *
252 * @return The byte stream, or null if none was supplied.
253 * @see #getEncoding
254 * @see #setByteStream
255 */
256 public InputStream getByteStream() {
257 return byteStream;
258 }
259
260 /**
261 * Set the character encoding, if known.
262 *
263 * <p>The encoding must be a string acceptable for an
264 * XML encoding declaration (see section 4.3.3 of the XML 1.0
265 * recommendation).</p>
266 *
267 * <p>This method has no effect when the application provides a
268 * character stream.</p>
269 *
270 * @param encoding A string describing the character encoding.
271 * @see #setSystemId
272 * @see #setByteStream
273 * @see #getEncoding
274 */
275 public void setEncoding(String encoding) {
276 this .encoding = encoding;
277 }
278
279 /**
280 * Get the character encoding for a byte stream or URI.
281 * This value will be ignored when the application provides a
282 * character stream.
283 *
284 * @return The encoding, or null if none was supplied.
285 * @see #setByteStream
286 * @see #getSystemId
287 * @see #getByteStream
288 */
289 public String getEncoding() {
290 return encoding;
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 this .characterStream = characterStream;
307 }
308
309 /**
310 * Get the character stream for this input source.
311 *
312 * @return The character stream, or null if none was supplied.
313 * @see #setCharacterStream
314 */
315 public Reader getCharacterStream() {
316 return characterStream;
317 }
318
319 ////////////////////////////////////////////////////////////////////
320 // Internal state.
321 ////////////////////////////////////////////////////////////////////
322
323 private String publicId;
324 private String systemId;
325 private InputStream byteStream;
326 private String encoding;
327 private Reader characterStream;
328
329 }
330
331 // end of InputSource.java
|