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    
006    package org.xml.sax;
007    
008    import java.io.Reader;
009    import 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     */
060    public 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