Source for org.xml.sax.InputSource

   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