KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > xml > sax > InputSource


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.1.24.1 2004/05/01 08:34:39 jsuttor Exp $
5

6 package org.xml.sax;
7
8 import java.io.Reader JavaDoc;
9 import java.io.InputStream JavaDoc;
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  */

60 public 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getCharacterStream ()
318     {
319     return characterStream;
320     }
321     
322     
323
324     ////////////////////////////////////////////////////////////////////
325
// Internal state.
326
////////////////////////////////////////////////////////////////////
327

328     private String JavaDoc publicId;
329     private String JavaDoc systemId;
330     private InputStream JavaDoc byteStream;
331     private String JavaDoc encoding;
332     private Reader JavaDoc characterStream;
333     
334 }
335
336 // end of InputSource.java
337
Popular Tags