1// SAX input source.
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 $
5
6package org.xml.sax;
7
8import java.io.Reader;
9import java.io.InputStream;
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 */
60public 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     * @param characterStream The raw character stream containing the document.
130     * @see #setPublicId
131     * @see #setSystemId
132     * @see #setByteStream
133     * @see #setCharacterStream
134     */
135    public InputSource (Reader characterStream)
136    {
137    setCharacterStream(characterStream);
138    }
139
140
141    /**
142     * Set the public identifier for this input source.
143     *
144     * <p>The public identifier is always optional: if the application
145     * writer includes one, it will be provided as part of the
146     * location information.</p>
147     *
148     * @param publicId The public identifier as a string.
149     * @see #getPublicId
150     * @see org.xml.sax.Locator#getPublicId
151     * @see org.xml.sax.SAXParseException#getPublicId
152     */
153    public void setPublicId (String publicId)
154    {
155    this.publicId = publicId;
156    }
157
158
159    /**
160     * Get the public identifier for this input source.
161     *
162     * @return The public identifier, or null if none was supplied.
163     * @see #setPublicId
164     */
165    public String getPublicId ()
166    {
167    return publicId;
168    }
169
170
171    /**
172     * Set the system identifier for this input source.
173     *
174     * <p>The system identifier is optional if there is a byte stream
175     * or a character stream, but it is still useful to provide one,
176     * since the application can use it to resolve relative URIs
177     * and can include it in error messages and warnings (the parser
178     * will attempt to open a connection to the URI only if
179     * there is no byte stream or character stream specified).</p>
180     *
181     * <p>If the application knows the character encoding of the
182     * object pointed to by the system identifier, it can register
183     * the encoding using the setEncoding method.</p>
184     *
185     * <p>If the system identifier is a URL, it must be fully
186     * resolved (it may not be a relative URL).</p>
187     *
188     * @param systemId The system identifier as a string.
189     * @see #setEncoding
190     * @see #getSystemId
191     * @see org.xml.sax.Locator#getSystemId
192     * @see org.xml.sax.SAXParseException#getSystemId
193     */
194    public void setSystemId (String systemId)
195    {
196    this.systemId = systemId;
197    }
198
199
200    /**
201     * Get the system identifier for this input source.
202     *
203     * <p>The getEncoding method will return the character encoding
204     * of the object pointed to, or null if unknown.</p>
205     *
206     * <p>If the system ID is a URL, it will be fully resolved.</p>
207     *
208     * @return The system identifier, or null if none was supplied.
209     * @see #setSystemId
210     * @see #getEncoding
211     */
212    public String getSystemId ()
213    {
214    return systemId;
215    }
216
217
218    /**
219     * Set the byte stream for this input source.
220     *
221     * <p>The SAX parser will ignore this if there is also a character
222     * stream specified, but it will use a byte stream in preference
223     * to opening a URI connection itself.</p>
224     *
225     * <p>If the application knows the character encoding of the
226     * byte stream, it should set it with the setEncoding method.</p>
227     *
228     * @param byteStream A byte stream containing an XML document or
229     *        other entity.
230     * @see #setEncoding
231     * @see #getByteStream
232     * @see #getEncoding
233     * @see java.io.InputStream
234     */
235    public void setByteStream (InputStream byteStream)
236    {
237    this.byteStream = byteStream;
238    }
239
240
241    /**
242     * Get the byte stream for this input source.
243     *
244     * <p>The getEncoding method will return the character
245     * encoding for this byte stream, or null if unknown.</p>
246     *
247     * @return The byte stream, or null if none was supplied.
248     * @see #getEncoding
249     * @see #setByteStream
250     */
251    public InputStream getByteStream ()
252    {
253    return byteStream;
254    }
255
256
257    /**
258     * Set the character encoding, if known.
259     *
260     * <p>The encoding must be a string acceptable for an
261     * XML encoding declaration (see section 4.3.3 of the XML 1.0
262     * recommendation).</p>
263     *
264     * <p>This method has no effect when the application provides a
265     * character stream.</p>
266     *
267     * @param encoding A string describing the character encoding.
268     * @see #setSystemId
269     * @see #setByteStream
270     * @see #getEncoding
271     */
272    public void setEncoding (String encoding)
273    {
274    this.encoding = encoding;
275    }
276
277
278    /**
279     * Get the character encoding for a byte stream or URI.
280     * This value will be ignored when the application provides a
281     * character stream.
282     *
283     * @return The encoding, or null if none was supplied.
284     * @see #setByteStream
285     * @see #getSystemId
286     * @see #getByteStream
287     */
288    public String getEncoding ()
289    {
290    return encoding;
291    }
292
293
294    /**
295     * Set the character stream for this input source.
296     *
297     * <p>If there is a character stream specified, the SAX parser
298     * will ignore any byte stream and will not attempt to open
299     * a URI connection to the system identifier.</p>
300     *
301     * @param characterStream The character stream containing the
302     *        XML document or other entity.
303     * @see #getCharacterStream
304     * @see java.io.Reader
305     */
306    public void setCharacterStream (Reader characterStream)
307    {
308    this.characterStream = characterStream;
309    }
310
311
312    /**
313     * Get the character stream for this input source.
314     *
315     * @return The character stream, or null if none was supplied.
316     * @see #setCharacterStream
317     */
318    public Reader getCharacterStream ()
319    {
320    return characterStream;
321    }
322
323
324
325    ////////////////////////////////////////////////////////////////////
326    // Internal state.
327    ////////////////////////////////////////////////////////////////////
328
329    private String publicId;
330    private String systemId;
331    private InputStream byteStream;
332    private String encoding;
333    private Reader characterStream;
334
335}
336
337// end of InputSource.java
338