001// SAX input source.
002// http://www.saxproject.org
003// No warranty; no copyright -- use this as you will.
004// $Id: InputSource.java,v 1.1 2004/12/23 22:38:42 mark Exp $
005
006package org.xml.sax;
007
008import java.io.Reader;
009import java.io.InputStream;
010
011/**
012 * A single input source for an XML entity.
013 *
014 * <blockquote>
015 * <em>This module, both source code and documentation, is in the
016 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
017 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
018 * for further information.
019 * </blockquote>
020 *
021 * <p>This class allows a SAX application to encapsulate information
022 * about an input source in a single object, which may include
023 * a public identifier, a system identifier, a byte stream (possibly
024 * with a specified encoding), and/or a character stream.</p>
025 *
026 * <p>There are two places that the application can deliver an
027 * input source to the parser: as the argument to the Parser.parse
028 * method, or as the return value of the EntityResolver.resolveEntity
029 * method.</p>
030 *
031 * <p>The SAX parser will use the InputSource object to determine how
032 * to read XML input.  If there is a character stream available, the
033 * parser will read that stream directly, disregarding any text
034 * encoding declaration found in that stream.
035 * If there is no character stream, but there is
036 * a byte stream, the parser will use that byte stream, using the
037 * encoding specified in the InputSource or else (if no encoding is
038 * specified) autodetecting the character encoding using an algorithm
039 * such as the one in the XML specification.  If neither a character
040 * stream nor a
041 * byte stream is available, the parser will attempt to open a URI
042 * connection to the resource identified by the system
043 * identifier.</p>
044 *
045 * <p>An InputSource object belongs to the application: the SAX parser
046 * shall never modify it in any way (it may modify a copy if 
047 * necessary).  However, standard processing of both byte and
048 * character streams is to close them on as part of end-of-parse cleanup,
049 * so applications should not attempt to re-use such streams after they
050 * have been handed to a parser.  </p>
051 *
052 * @since SAX 1.0
053 * @author David Megginson
054 * @version 2.0.1 (sax2r2)
055 * @see org.xml.sax.XMLReader#parse(org.xml.sax.InputSource)
056 * @see org.xml.sax.EntityResolver#resolveEntity
057 * @see java.io.InputStream
058 * @see java.io.Reader
059 */
060public class InputSource {
061    
062    /**
063     * Zero-argument default constructor.
064     *
065     * @see #setPublicId
066     * @see #setSystemId
067     * @see #setByteStream
068     * @see #setCharacterStream
069     * @see #setEncoding
070     */
071    public InputSource ()
072    {
073    }
074    
075    
076    /**
077     * Create a new input source with a system identifier.
078     *
079     * <p>Applications may use setPublicId to include a 
080     * public identifier as well, or setEncoding to specify
081     * the character encoding, if known.</p>
082     *
083     * <p>If the system identifier is a URL, it must be fully
084     * resolved (it may not be a relative URL).</p>
085     *
086     * @param systemId The system identifier (URI).
087     * @see #setPublicId
088     * @see #setSystemId
089     * @see #setByteStream
090     * @see #setEncoding
091     * @see #setCharacterStream
092     */
093    public InputSource (String systemId)
094    {
095        setSystemId(systemId);
096    }
097    
098    
099    /**
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     * @see #setPublicId
130     * @see #setSystemId
131     * @see #setByteStream
132     * @see #setCharacterStream
133     */
134    public InputSource (Reader characterStream)
135    {
136        setCharacterStream(characterStream);
137    }
138    
139    
140    /**
141     * Set the public identifier for this input source.
142     *
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>
146     *
147     * @param publicId The public identifier as a string.
148     * @see #getPublicId
149     * @see org.xml.sax.Locator#getPublicId
150     * @see org.xml.sax.SAXParseException#getPublicId
151     */
152    public void setPublicId (String publicId)
153    {
154        this.publicId = publicId;
155    }
156    
157    
158    /**
159     * Get the public identifier for this input source.
160     *
161     * @return The public identifier, or null if none was supplied.
162     * @see #setPublicId
163     */
164    public String getPublicId ()
165    {
166        return publicId;
167    }
168    
169    
170    /**
171     * Set the system identifier for this input source.
172     *
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>
179     *
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>
183     *
184     * <p>If the system identifier is a URL, it must be fully
185     * resolved (it may not be a relative URL).</p>
186     *
187     * @param systemId The system identifier as a string.
188     * @see #setEncoding
189     * @see #getSystemId
190     * @see org.xml.sax.Locator#getSystemId
191     * @see org.xml.sax.SAXParseException#getSystemId
192     */
193    public void setSystemId (String systemId)
194    {
195        this.systemId = systemId;
196    }
197    
198    
199    /**
200     * Get the system identifier for this input source.
201     *
202     * <p>The getEncoding method will return the character encoding
203     * of the object pointed to, or null if unknown.</p>
204     *
205     * <p>If the system ID is a URL, it will be fully resolved.</p>
206     *
207     * @return The system identifier, or null if none was supplied.
208     * @see #setSystemId
209     * @see #getEncoding
210     */
211    public String getSystemId ()
212    {
213        return systemId;
214    }
215    
216    
217    /**
218     * Set the byte stream for this input source.
219     *
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>
223     *
224     * <p>If the application knows the character encoding of the
225     * byte stream, it should set it with the setEncoding method.</p>
226     *
227     * @param byteStream A byte stream containing an XML document or
228     *        other entity.
229     * @see #setEncoding
230     * @see #getByteStream
231     * @see #getEncoding
232     * @see java.io.InputStream
233     */
234    public void setByteStream (InputStream byteStream)
235    {
236        this.byteStream = byteStream;
237    }
238    
239    
240    /**
241     * Get the byte stream for this input source.
242     *
243     * <p>The getEncoding method will return the character
244     * encoding for this byte stream, or null if unknown.</p>
245     *
246     * @return The byte stream, or null if none was supplied.
247     * @see #getEncoding
248     * @see #setByteStream
249     */
250    public InputStream getByteStream ()
251    {
252        return byteStream;
253    }
254    
255    
256    /** 
257     * Set the character encoding, if known.
258     *
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>
262     *
263     * <p>This method has no effect when the application provides a
264     * character stream.</p>
265     *
266     * @param encoding A string describing the character encoding.
267     * @see #setSystemId
268     * @see #setByteStream
269     * @see #getEncoding
270     */
271    public void setEncoding (String encoding)
272    {
273        this.encoding = encoding;
274    }
275    
276    
277    /**
278     * Get the character encoding for a byte stream or URI.
279     * This value will be ignored when the application provides a
280     * character stream.
281     *
282     * @return The encoding, or null if none was supplied.
283     * @see #setByteStream
284     * @see #getSystemId
285     * @see #getByteStream
286     */
287    public String getEncoding ()
288    {
289        return encoding;
290    }
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    {
307        this.characterStream = characterStream;
308    }
309    
310    
311    /**
312     * Get the character stream for this input source.
313     *
314     * @return The character stream, or null if none was supplied.
315     * @see #setCharacterStream
316     */
317    public Reader getCharacterStream ()
318    {
319        return characterStream;
320    }
321    
322    
323
324    ////////////////////////////////////////////////////////////////////
325    // Internal state.
326    ////////////////////////////////////////////////////////////////////
327    
328    private String publicId;
329    private String systemId;
330    private InputStream byteStream;
331    private String encoding;
332    private Reader characterStream;
333    
334}
335
336// end of InputSource.java