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 jdk.internal.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