| Frames | No Frames |
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.1 2004/12/23 22:38:42 mark Exp $ 5: 6: package org.xml.sax; 7: 8: import java.io.Reader; 9: import java.io.InputStream; 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: */ 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: */ 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: */ 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