001// SAX input source. 002// No warranty; no copyright -- use this as you will. 003// $Id: InputSource.java,v 1.1 2001/03/05 21:40:06 jstrachan Exp $ 004 005package org.xml.sax; 006 007import java.io.Reader; 008import java.io.InputStream; 009 010/** 011 * A single input source for an XML entity. 012 * 013 * <blockquote> 014 * <em>This module, both source code and documentation, is in the 015 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 016 * </blockquote> 017 * 018 * <p>This class allows a SAX application to encapsulate information 019 * about an input source in a single object, which may include 020 * a public identifier, a system identifier, a byte stream (possibly 021 * with a specified encoding), and/or a character stream.</p> 022 * 023 * <p>There are two places that the application will deliver this 024 * input source to the parser: as the argument to the Parser.parse 025 * method, or as the return value of the EntityResolver.resolveEntity 026 * method.</p> 027 * 028 * <p>The SAX parser will use the InputSource object to determine how 029 * to read XML input. If there is a character stream available, the 030 * parser will read that stream directly; if not, the parser will use 031 * a byte stream, if available; if neither a character stream nor a 032 * byte stream is available, the parser will attempt to open a URI 033 * connection to the resource identified by the system 034 * identifier.</p> 035 * 036 * <p>An InputSource object belongs to the application: the SAX parser 037 * shall never modify it in any way (it may modify a copy if 038 * necessary).</p> 039 * 040 * @since SAX 1.0 041 * @author David Megginson, 042 * <a href="mailto:sax@megginson.com">sax@megginson.com</a> 043 * @version 2.0 044 * @see org.xml.sax.Parser#parse 045 * @see org.xml.sax.EntityResolver#resolveEntity 046 * @see java.io.InputStream 047 * @see java.io.Reader 048 */ 049public class InputSource { 050 051 /** 052 * Zero-argument default constructor. 053 * 054 * @see #setPublicId 055 * @see #setSystemId 056 * @see #setByteStream 057 * @see #setCharacterStream 058 * @see #setEncoding 059 */ 060 public InputSource () 061 { 062 } 063 064 065 /** 066 * Create a new input source with a system identifier. 067 * 068 * <p>Applications may use setPublicId to include a 069 * public identifier as well, or setEncoding to specify 070 * the character encoding, if known.</p> 071 * 072 * <p>If the system identifier is a URL, it must be full resolved.</p> 073 * 074 * @param systemId The system identifier (URI). 075 * @see #setPublicId 076 * @see #setSystemId 077 * @see #setByteStream 078 * @see #setEncoding 079 * @see #setCharacterStream 080 */ 081 public InputSource (String systemId) 082 { 083 setSystemId(systemId); 084 } 085 086 087 /** 088 * Create a new input source with a byte stream. 089 * 090 * <p>Application writers may use setSystemId to provide a base 091 * for resolving relative URIs, setPublicId to include a 092 * public identifier, and/or setEncoding to specify the object's 093 * character encoding.</p> 094 * 095 * @param byteStream The raw byte stream containing the document. 096 * @see #setPublicId 097 * @see #setSystemId 098 * @see #setEncoding 099 * @see #setByteStream 100 * @see #setCharacterStream 101 */ 102 public InputSource (InputStream byteStream) 103 { 104 setByteStream(byteStream); 105 } 106 107 108 /** 109 * Create a new input source with a character stream. 110 * 111 * <p>Application writers may use setSystemId() to provide a base 112 * for resolving relative URIs, and setPublicId to include a 113 * public identifier.</p> 114 * 115 * <p>The character stream shall not include a byte order mark.</p> 116 * 117 * @see #setPublicId 118 * @see #setSystemId 119 * @see #setByteStream 120 * @see #setCharacterStream 121 */ 122 public InputSource (Reader characterStream) 123 { 124 setCharacterStream(characterStream); 125 } 126 127 128 /** 129 * Set the public identifier for this input source. 130 * 131 * <p>The public identifier is always optional: if the application 132 * writer includes one, it will be provided as part of the 133 * location information.</p> 134 * 135 * @param publicId The public identifier as a string. 136 * @see #getPublicId 137 * @see org.xml.sax.Locator#getPublicId 138 * @see org.xml.sax.SAXParseException#getPublicId 139 */ 140 public void setPublicId (String publicId) 141 { 142 this.publicId = publicId; 143 } 144 145 146 /** 147 * Get the public identifier for this input source. 148 * 149 * @return The public identifier, or null if none was supplied. 150 * @see #setPublicId 151 */ 152 public String getPublicId () 153 { 154 return publicId; 155 } 156 157 158 /** 159 * Set the system identifier for this input source. 160 * 161 * <p>The system identifier is optional if there is a byte stream 162 * or a character stream, but it is still useful to provide one, 163 * since the application can use it to resolve relative URIs 164 * and can include it in error messages and warnings (the parser 165 * will attempt to open a connection to the URI only if 166 * there is no byte stream or character stream specified).</p> 167 * 168 * <p>If the application knows the character encoding of the 169 * object pointed to by the system identifier, it can register 170 * the encoding using the setEncoding method.</p> 171 * 172 * <p>If the system ID is a URL, it must be fully resolved.</p> 173 * 174 * @param systemId The system identifier as a string. 175 * @see #setEncoding 176 * @see #getSystemId 177 * @see org.xml.sax.Locator#getSystemId 178 * @see org.xml.sax.SAXParseException#getSystemId 179 */ 180 public void setSystemId (String systemId) 181 { 182 this.systemId = systemId; 183 } 184 185 186 /** 187 * Get the system identifier for this input source. 188 * 189 * <p>The getEncoding method will return the character encoding 190 * of the object pointed to, or null if unknown.</p> 191 * 192 * <p>If the system ID is a URL, it will be fully resolved.</p> 193 * 194 * @return The system identifier. 195 * @see #setSystemId 196 * @see #getEncoding 197 */ 198 public String getSystemId () 199 { 200 return systemId; 201 } 202 203 204 /** 205 * Set the byte stream for this input source. 206 * 207 * <p>The SAX parser will ignore this if there is also a character 208 * stream specified, but it will use a byte stream in preference 209 * to opening a URI connection itself.</p> 210 * 211 * <p>If the application knows the character encoding of the 212 * byte stream, it should set it with the setEncoding method.</p> 213 * 214 * @param byteStream A byte stream containing an XML document or 215 * other entity. 216 * @see #setEncoding 217 * @see #getByteStream 218 * @see #getEncoding 219 * @see java.io.InputStream 220 */ 221 public void setByteStream (InputStream byteStream) 222 { 223 this.byteStream = byteStream; 224 } 225 226 227 /** 228 * Get the byte stream for this input source. 229 * 230 * <p>The getEncoding method will return the character 231 * encoding for this byte stream, or null if unknown.</p> 232 * 233 * @return The byte stream, or null if none was supplied. 234 * @see #getEncoding 235 * @see #setByteStream 236 */ 237 public InputStream getByteStream () 238 { 239 return byteStream; 240 } 241 242 243 /** 244 * Set the character encoding, if known. 245 * 246 * <p>The encoding must be a string acceptable for an 247 * XML encoding declaration (see section 4.3.3 of the XML 1.0 248 * recommendation).</p> 249 * 250 * <p>This method has no effect when the application provides a 251 * character stream.</p> 252 * 253 * @param encoding A string describing the character encoding. 254 * @see #setSystemId 255 * @see #setByteStream 256 * @see #getEncoding 257 */ 258 public void setEncoding (String encoding) 259 { 260 this.encoding = encoding; 261 } 262 263 264 /** 265 * Get the character encoding for a byte stream or URI. 266 * 267 * @return The encoding, or null if none was supplied. 268 * @see #setByteStream 269 * @see #getSystemId 270 * @see #getByteStream 271 */ 272 public String getEncoding () 273 { 274 return encoding; 275 } 276 277 278 /** 279 * Set the character stream for this input source. 280 * 281 * <p>If there is a character stream specified, the SAX parser 282 * will ignore any byte stream and will not attempt to open 283 * a URI connection to the system identifier.</p> 284 * 285 * @param characterStream The character stream containing the 286 * XML document or other entity. 287 * @see #getCharacterStream 288 * @see java.io.Reader 289 */ 290 public void setCharacterStream (Reader characterStream) 291 { 292 this.characterStream = characterStream; 293 } 294 295 296 /** 297 * Get the character stream for this input source. 298 * 299 * @return The character stream, or null if none was supplied. 300 * @see #setCharacterStream 301 */ 302 public Reader getCharacterStream () 303 { 304 return characterStream; 305 } 306 307 308 309 //////////////////////////////////////////////////////////////////// 310 // Internal state. 311 //////////////////////////////////////////////////////////////////// 312 313 private String publicId; 314 private String systemId; 315 private InputStream byteStream; 316 private String encoding; 317 private Reader characterStream; 318 319} 320 321// end of InputSource.java