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 
6 package org.xml.sax;
7 
8 import android.compat.annotation.UnsupportedAppUsage;
9 import java.io.InputStream;
10 import java.io.Reader;
11 
12 /**
13  * A single input source for an XML entity.
14  *
15  * <blockquote>
16  * <em>This module, both source code and documentation, is in the
17  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
18  * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
19  * for further information.
20  * </blockquote>
21  *
22  * <p>This class allows a SAX application to encapsulate information
23  * about an input source in a single object, which may include
24  * a public identifier, a system identifier, a byte stream (possibly
25  * with a specified encoding), and/or a character stream.</p>
26  *
27  * <p>There are two places that the application can deliver an
28  * input source to the parser: as the argument to the Parser.parse
29  * method, or as the return value of the EntityResolver.resolveEntity
30  * method.</p>
31  *
32  * <p>The SAX parser will use the InputSource object to determine how
33  * to read XML input.  If there is a character stream available, the
34  * parser will read that stream directly, disregarding any text
35  * encoding declaration found in that stream.
36  * If there is no character stream, but there is
37  * a byte stream, the parser will use that byte stream, using the
38  * encoding specified in the InputSource or else (if no encoding is
39  * specified) autodetecting the character encoding using an algorithm
40  * such as the one in the XML specification.  If neither a character
41  * stream nor a
42  * byte stream is available, the parser will attempt to open a URI
43  * connection to the resource identified by the system
44  * identifier.</p>
45  *
46  * <p>An InputSource object belongs to the application: the SAX parser
47  * shall never modify it in any way (it may modify a copy if
48  * necessary).  However, standard processing of both byte and
49  * character streams is to close them on as part of end-of-parse cleanup,
50  * so applications should not attempt to re-use such streams after they
51  * have been handed to a parser.  </p>
52  *
53  * @since SAX 1.0
54  * @author David Megginson
55  * @version 2.0.1 (sax2r2)
56  * @see org.xml.sax.XMLReader#parse(org.xml.sax.InputSource)
57  * @see org.xml.sax.EntityResolver#resolveEntity
58  * @see java.io.InputStream
59  * @see java.io.Reader
60  */
61 public class InputSource {
62 
63     /**
64      * Zero-argument default constructor.
65      *
66      * @see #setPublicId
67      * @see #setSystemId
68      * @see #setByteStream
69      * @see #setCharacterStream
70      * @see #setEncoding
71      */
InputSource()72     public InputSource ()
73     {
74     }
75 
76 
77     /**
78      * Create a new input source with a system identifier.
79      *
80      * <p>Applications may use setPublicId to include a
81      * public identifier as well, or setEncoding to specify
82      * the character encoding, if known.</p>
83      *
84      * <p>If the system identifier is a URL, it must be fully
85      * resolved (it may not be a relative URL).</p>
86      *
87      * @param systemId The system identifier (URI).
88      * @see #setPublicId
89      * @see #setSystemId
90      * @see #setByteStream
91      * @see #setEncoding
92      * @see #setCharacterStream
93      */
InputSource(String systemId)94     public InputSource (String systemId)
95     {
96     setSystemId(systemId);
97     }
98 
99 
100     /**
101      * Create a new input source with a byte stream.
102      *
103      * <p>Application writers should use setSystemId() to provide a base
104      * for resolving relative URIs, may use setPublicId to include a
105      * public identifier, and may use setEncoding to specify the object's
106      * character encoding.</p>
107      *
108      * @param byteStream The raw byte stream containing the document.
109      * @see #setPublicId
110      * @see #setSystemId
111      * @see #setEncoding
112      * @see #setByteStream
113      * @see #setCharacterStream
114      */
InputSource(InputStream byteStream)115     public InputSource (InputStream byteStream)
116     {
117     setByteStream(byteStream);
118     }
119 
120 
121     /**
122      * Create a new input source with a character stream.
123      *
124      * <p>Application writers should use setSystemId() to provide a base
125      * for resolving relative URIs, and may use setPublicId to include a
126      * public identifier.</p>
127      *
128      * <p>The character stream shall not include a byte order mark.</p>
129      *
130      * @param characterStream The raw character stream containing the document.
131      * @see #setPublicId
132      * @see #setSystemId
133      * @see #setByteStream
134      * @see #setCharacterStream
135      */
InputSource(Reader characterStream)136     public InputSource (Reader characterStream)
137     {
138     setCharacterStream(characterStream);
139     }
140 
141 
142     /**
143      * Set the public identifier for this input source.
144      *
145      * <p>The public identifier is always optional: if the application
146      * writer includes one, it will be provided as part of the
147      * location information.</p>
148      *
149      * @param publicId The public identifier as a string.
150      * @see #getPublicId
151      * @see org.xml.sax.Locator#getPublicId
152      * @see org.xml.sax.SAXParseException#getPublicId
153      */
setPublicId(String publicId)154     public void setPublicId (String publicId)
155     {
156     this.publicId = publicId;
157     }
158 
159 
160     /**
161      * Get the public identifier for this input source.
162      *
163      * @return The public identifier, or null if none was supplied.
164      * @see #setPublicId
165      */
getPublicId()166     public String getPublicId ()
167     {
168     return publicId;
169     }
170 
171 
172     /**
173      * Set the system identifier for this input source.
174      *
175      * <p>The system identifier is optional if there is a byte stream
176      * or a character stream, but it is still useful to provide one,
177      * since the application can use it to resolve relative URIs
178      * and can include it in error messages and warnings (the parser
179      * will attempt to open a connection to the URI only if
180      * there is no byte stream or character stream specified).</p>
181      *
182      * <p>If the application knows the character encoding of the
183      * object pointed to by the system identifier, it can register
184      * the encoding using the setEncoding method.</p>
185      *
186      * <p>If the system identifier is a URL, it must be fully
187      * resolved (it may not be a relative URL).</p>
188      *
189      * @param systemId The system identifier as a string.
190      * @see #setEncoding
191      * @see #getSystemId
192      * @see org.xml.sax.Locator#getSystemId
193      * @see org.xml.sax.SAXParseException#getSystemId
194      */
setSystemId(String systemId)195     public void setSystemId (String systemId)
196     {
197     this.systemId = systemId;
198     }
199 
200 
201     /**
202      * Get the system identifier for this input source.
203      *
204      * <p>The getEncoding method will return the character encoding
205      * of the object pointed to, or null if unknown.</p>
206      *
207      * <p>If the system ID is a URL, it will be fully resolved.</p>
208      *
209      * @return The system identifier, or null if none was supplied.
210      * @see #setSystemId
211      * @see #getEncoding
212      */
getSystemId()213     public String getSystemId ()
214     {
215     return systemId;
216     }
217 
218 
219     /**
220      * Set the byte stream for this input source.
221      *
222      * <p>The SAX parser will ignore this if there is also a character
223      * stream specified, but it will use a byte stream in preference
224      * to opening a URI connection itself.</p>
225      *
226      * <p>If the application knows the character encoding of the
227      * byte stream, it should set it with the setEncoding method.</p>
228      *
229      * @param byteStream A byte stream containing an XML document or
230      *        other entity.
231      * @see #setEncoding
232      * @see #getByteStream
233      * @see #getEncoding
234      * @see java.io.InputStream
235      */
setByteStream(InputStream byteStream)236     public void setByteStream (InputStream byteStream)
237     {
238     this.byteStream = byteStream;
239     }
240 
241 
242     /**
243      * Get the byte stream for this input source.
244      *
245      * <p>The getEncoding method will return the character
246      * encoding for this byte stream, or null if unknown.</p>
247      *
248      * @return The byte stream, or null if none was supplied.
249      * @see #getEncoding
250      * @see #setByteStream
251      */
getByteStream()252     public InputStream getByteStream ()
253     {
254     return byteStream;
255     }
256 
257 
258     /**
259      * Set the character encoding, if known.
260      *
261      * <p>The encoding must be a string acceptable for an
262      * XML encoding declaration (see section 4.3.3 of the XML 1.0
263      * recommendation).</p>
264      *
265      * <p>This method has no effect when the application provides a
266      * character stream.</p>
267      *
268      * @param encoding A string describing the character encoding.
269      * @see #setSystemId
270      * @see #setByteStream
271      * @see #getEncoding
272      */
setEncoding(String encoding)273     public void setEncoding (String encoding)
274     {
275     this.encoding = encoding;
276     }
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      */
getEncoding()289     public String getEncoding ()
290     {
291     return encoding;
292     }
293 
294 
295     /**
296      * Set the character stream for this input source.
297      *
298      * <p>If there is a character stream specified, the SAX parser
299      * will ignore any byte stream and will not attempt to open
300      * a URI connection to the system identifier.</p>
301      *
302      * @param characterStream The character stream containing the
303      *        XML document or other entity.
304      * @see #getCharacterStream
305      * @see java.io.Reader
306      */
setCharacterStream(Reader characterStream)307     public void setCharacterStream (Reader characterStream)
308     {
309     this.characterStream = characterStream;
310     }
311 
312 
313     /**
314      * Get the character stream for this input source.
315      *
316      * @return The character stream, or null if none was supplied.
317      * @see #setCharacterStream
318      */
getCharacterStream()319     public Reader getCharacterStream ()
320     {
321     return characterStream;
322     }
323 
324 
325 
326     ////////////////////////////////////////////////////////////////////
327     // Internal state.
328     ////////////////////////////////////////////////////////////////////
329 
330     @UnsupportedAppUsage
331     private String publicId;
332     @UnsupportedAppUsage
333     private String systemId;
334     @UnsupportedAppUsage
335     private InputStream byteStream;
336     @UnsupportedAppUsage
337     private String encoding;
338     @UnsupportedAppUsage
339     private Reader characterStream;
340 
341 }
342 
343 // end of InputSource.java
344