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  ;
9   import 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   */
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   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      * @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
337
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags