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 java.io.InputStream; 9 import java.io.Reader; 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 */ InputSource()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 */ InputSource(String systemId)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 */ InputSource(InputStream byteStream)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 * @param characterStream The raw character stream containing the document. 130 * @see #setPublicId 131 * @see #setSystemId 132 * @see #setByteStream 133 * @see #setCharacterStream 134 */ InputSource(Reader characterStream)135 public InputSource (Reader characterStream) 136 { 137 setCharacterStream(characterStream); 138 } 139 140 141 /** 142 * Set the public identifier for this input source. 143 * 144 * <p>The public identifier is always optional: if the application 145 * writer includes one, it will be provided as part of the 146 * location information.</p> 147 * 148 * @param publicId The public identifier as a string. 149 * @see #getPublicId 150 * @see org.xml.sax.Locator#getPublicId 151 * @see org.xml.sax.SAXParseException#getPublicId 152 */ setPublicId(String publicId)153 public void setPublicId (String publicId) 154 { 155 this.publicId = publicId; 156 } 157 158 159 /** 160 * Get the public identifier for this input source. 161 * 162 * @return The public identifier, or null if none was supplied. 163 * @see #setPublicId 164 */ getPublicId()165 public String getPublicId () 166 { 167 return publicId; 168 } 169 170 171 /** 172 * Set the system identifier for this input source. 173 * 174 * <p>The system identifier is optional if there is a byte stream 175 * or a character stream, but it is still useful to provide one, 176 * since the application can use it to resolve relative URIs 177 * and can include it in error messages and warnings (the parser 178 * will attempt to open a connection to the URI only if 179 * there is no byte stream or character stream specified).</p> 180 * 181 * <p>If the application knows the character encoding of the 182 * object pointed to by the system identifier, it can register 183 * the encoding using the setEncoding method.</p> 184 * 185 * <p>If the system identifier is a URL, it must be fully 186 * resolved (it may not be a relative URL).</p> 187 * 188 * @param systemId The system identifier as a string. 189 * @see #setEncoding 190 * @see #getSystemId 191 * @see org.xml.sax.Locator#getSystemId 192 * @see org.xml.sax.SAXParseException#getSystemId 193 */ setSystemId(String systemId)194 public void setSystemId (String systemId) 195 { 196 this.systemId = systemId; 197 } 198 199 200 /** 201 * Get the system identifier for this input source. 202 * 203 * <p>The getEncoding method will return the character encoding 204 * of the object pointed to, or null if unknown.</p> 205 * 206 * <p>If the system ID is a URL, it will be fully resolved.</p> 207 * 208 * @return The system identifier, or null if none was supplied. 209 * @see #setSystemId 210 * @see #getEncoding 211 */ getSystemId()212 public String getSystemId () 213 { 214 return systemId; 215 } 216 217 218 /** 219 * Set the byte stream for this input source. 220 * 221 * <p>The SAX parser will ignore this if there is also a character 222 * stream specified, but it will use a byte stream in preference 223 * to opening a URI connection itself.</p> 224 * 225 * <p>If the application knows the character encoding of the 226 * byte stream, it should set it with the setEncoding method.</p> 227 * 228 * @param byteStream A byte stream containing an XML document or 229 * other entity. 230 * @see #setEncoding 231 * @see #getByteStream 232 * @see #getEncoding 233 * @see java.io.InputStream 234 */ setByteStream(InputStream byteStream)235 public void setByteStream (InputStream byteStream) 236 { 237 this.byteStream = byteStream; 238 } 239 240 241 /** 242 * Get the byte stream for this input source. 243 * 244 * <p>The getEncoding method will return the character 245 * encoding for this byte stream, or null if unknown.</p> 246 * 247 * @return The byte stream, or null if none was supplied. 248 * @see #getEncoding 249 * @see #setByteStream 250 */ getByteStream()251 public InputStream getByteStream () 252 { 253 return byteStream; 254 } 255 256 257 /** 258 * Set the character encoding, if known. 259 * 260 * <p>The encoding must be a string acceptable for an 261 * XML encoding declaration (see section 4.3.3 of the XML 1.0 262 * recommendation).</p> 263 * 264 * <p>This method has no effect when the application provides a 265 * character stream.</p> 266 * 267 * @param encoding A string describing the character encoding. 268 * @see #setSystemId 269 * @see #setByteStream 270 * @see #getEncoding 271 */ setEncoding(String encoding)272 public void setEncoding (String encoding) 273 { 274 this.encoding = encoding; 275 } 276 277 278 /** 279 * Get the character encoding for a byte stream or URI. 280 * This value will be ignored when the application provides a 281 * character stream. 282 * 283 * @return The encoding, or null if none was supplied. 284 * @see #setByteStream 285 * @see #getSystemId 286 * @see #getByteStream 287 */ getEncoding()288 public String getEncoding () 289 { 290 return encoding; 291 } 292 293 294 /** 295 * Set the character stream for this input source. 296 * 297 * <p>If there is a character stream specified, the SAX parser 298 * will ignore any byte stream and will not attempt to open 299 * a URI connection to the system identifier.</p> 300 * 301 * @param characterStream The character stream containing the 302 * XML document or other entity. 303 * @see #getCharacterStream 304 * @see java.io.Reader 305 */ setCharacterStream(Reader characterStream)306 public void setCharacterStream (Reader characterStream) 307 { 308 this.characterStream = characterStream; 309 } 310 311 312 /** 313 * Get the character stream for this input source. 314 * 315 * @return The character stream, or null if none was supplied. 316 * @see #setCharacterStream 317 */ getCharacterStream()318 public Reader getCharacterStream () 319 { 320 return characterStream; 321 } 322 323 324 325 //////////////////////////////////////////////////////////////////// 326 // Internal state. 327 //////////////////////////////////////////////////////////////////// 328 329 private String publicId; 330 private String systemId; 331 private InputStream byteStream; 332 private String encoding; 333 private Reader characterStream; 334 335 } 336 337 // end of InputSource.java 338