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