001 // SAX input source. 002 // http://www.saxproject.org 003 // No warranty; no copyright -- use this as you will. 004 // $Id: InputSource.java,v 1.1 2004/12/23 22:38:42 mark Exp $ 005 006 package org.xml.sax; 007 008 import java.io.Reader; 009 import java.io.InputStream; 010 011 /** 012 * A single input source for an XML entity. 013 * 014 * <blockquote> 015 * <em>This module, both source code and documentation, is in the 016 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 017 * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a> 018 * for further information. 019 * </blockquote> 020 * 021 * <p>This class allows a SAX application to encapsulate information 022 * about an input source in a single object, which may include 023 * a public identifier, a system identifier, a byte stream (possibly 024 * with a specified encoding), and/or a character stream.</p> 025 * 026 * <p>There are two places that the application can deliver an 027 * input source to the parser: as the argument to the Parser.parse 028 * method, or as the return value of the EntityResolver.resolveEntity 029 * method.</p> 030 * 031 * <p>The SAX parser will use the InputSource object to determine how 032 * to read XML input. If there is a character stream available, the 033 * parser will read that stream directly, disregarding any text 034 * encoding declaration found in that stream. 035 * If there is no character stream, but there is 036 * a byte stream, the parser will use that byte stream, using the 037 * encoding specified in the InputSource or else (if no encoding is 038 * specified) autodetecting the character encoding using an algorithm 039 * such as the one in the XML specification. If neither a character 040 * stream nor a 041 * byte stream is available, the parser will attempt to open a URI 042 * connection to the resource identified by the system 043 * identifier.</p> 044 * 045 * <p>An InputSource object belongs to the application: the SAX parser 046 * shall never modify it in any way (it may modify a copy if 047 * necessary). However, standard processing of both byte and 048 * character streams is to close them on as part of end-of-parse cleanup, 049 * so applications should not attempt to re-use such streams after they 050 * have been handed to a parser. </p> 051 * 052 * @since SAX 1.0 053 * @author David Megginson 054 * @version 2.0.1 (sax2r2) 055 * @see org.xml.sax.XMLReader#parse(org.xml.sax.InputSource) 056 * @see org.xml.sax.EntityResolver#resolveEntity 057 * @see java.io.InputStream 058 * @see java.io.Reader 059 */ 060 public class InputSource { 061 062 /** 063 * Zero-argument default constructor. 064 * 065 * @see #setPublicId 066 * @see #setSystemId 067 * @see #setByteStream 068 * @see #setCharacterStream 069 * @see #setEncoding 070 */ 071 public InputSource () 072 { 073 } 074 075 076 /** 077 * Create a new input source with a system identifier. 078 * 079 * <p>Applications may use setPublicId to include a 080 * public identifier as well, or setEncoding to specify 081 * the character encoding, if known.</p> 082 * 083 * <p>If the system identifier is a URL, it must be fully 084 * resolved (it may not be a relative URL).</p> 085 * 086 * @param systemId The system identifier (URI). 087 * @see #setPublicId 088 * @see #setSystemId 089 * @see #setByteStream 090 * @see #setEncoding 091 * @see #setCharacterStream 092 */ 093 public InputSource (String systemId) 094 { 095 setSystemId(systemId); 096 } 097 098 099 /** 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