2 // http://www.saxproject.org
3 // No warranty; no copyright -- use this as you will.
4 // $Id: InputSource.java,v 1.9 2002/01/30 21:13:45 dbrownell Exp $
9 import java.io.InputStream;
12 * A single input source for an XML entity.
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.
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>
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
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
41 * byte stream is available, the parser will attempt to open a URI
42 * connection to the resource identified by the system
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>
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
60 public class InputSource {
63 * Zero-argument default constructor.
68 * @see #setCharacterStream
77 * Create a new input source with a system identifier.
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>
83 * <p>If the system identifier is a URL, it must be fully
84 * resolved (it may not be a relative URL).</p>
86 * @param systemId The system identifier (URI).
91 * @see #setCharacterStream
93 public InputSource (String systemId)
95 setSystemId(systemId);
100 * Create a new input source with a byte stream.
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>
107 * @param byteStream The raw byte stream containing the document.
111 * @see #setByteStream
112 * @see #setCharacterStream
114 public InputSource (InputStream byteStream)
116 setByteStream(byteStream);
121 * Create a new input source with a character stream.
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>
127 * <p>The character stream shall not include a byte order mark.</p>
131 * @see #setByteStream
132 * @see #setCharacterStream
134 public InputSource (Reader characterStream)
136 setCharacterStream(characterStream);
141 * Set the public identifier for this input source.
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>
147 * @param publicId The public identifier as a string.
149 * @see org.xml.sax.Locator#getPublicId
150 * @see org.xml.sax.SAXParseException#getPublicId
152 public void setPublicId (String publicId)
154 this.publicId = publicId;
159 * Get the public identifier for this input source.
161 * @return The public identifier, or null if none was supplied.
164 public String getPublicId ()
171 * Set the system identifier for this input source.
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>
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>
184 * <p>If the system identifier is a URL, it must be fully
185 * resolved (it may not be a relative URL).</p>
187 * @param systemId The system identifier as a string.
190 * @see org.xml.sax.Locator#getSystemId
191 * @see org.xml.sax.SAXParseException#getSystemId
193 public void setSystemId (String systemId)
195 this.systemId = systemId;
200 * Get the system identifier for this input source.
202 * <p>The getEncoding method will return the character encoding
203 * of the object pointed to, or null if unknown.</p>
205 * <p>If the system ID is a URL, it will be fully resolved.</p>
207 * @return The system identifier, or null if none was supplied.
211 public String getSystemId ()
218 * Set the byte stream for this input source.
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>
224 * <p>If the application knows the character encoding of the
225 * byte stream, it should set it with the setEncoding method.</p>
227 * @param byteStream A byte stream containing an XML document or
230 * @see #getByteStream
232 * @see java.io.InputStream
234 public void setByteStream (InputStream byteStream)
236 this.byteStream = byteStream;
241 * Get the byte stream for this input source.
243 * <p>The getEncoding method will return the character
244 * encoding for this byte stream, or null if unknown.</p>
246 * @return The byte stream, or null if none was supplied.
248 * @see #setByteStream
250 public InputStream getByteStream ()
257 * Set the character encoding, if known.
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>
263 * <p>This method has no effect when the application provides a
264 * character stream.</p>
266 * @param encoding A string describing the character encoding.
268 * @see #setByteStream
271 public void setEncoding (String encoding)
273 this.encoding = encoding;
278 * Get the character encoding for a byte stream or URI.
279 * This value will be ignored when the application provides a
282 * @return The encoding, or null if none was supplied.
283 * @see #setByteStream
285 * @see #getByteStream
287 public String getEncoding ()
294 * Set the character stream for this input source.
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>
300 * @param characterStream The character stream containing the
301 * XML document or other entity.
302 * @see #getCharacterStream
303 * @see java.io.Reader
305 public void setCharacterStream (Reader characterStream)
307 this.characterStream = characterStream;
312 * Get the character stream for this input source.
314 * @return The character stream, or null if none was supplied.
315 * @see #setCharacterStream
317 public Reader getCharacterStream ()
319 return characterStream;
324 ////////////////////////////////////////////////////////////////////
326 ////////////////////////////////////////////////////////////////////
328 private String publicId;
329 private String systemId;
330 private InputStream byteStream;
331 private String encoding;
332 private Reader characterStream;
336 // end of InputSource.java