libjava/org/xml/sax/InputSource.java

   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.5.2.4 2002/01/29 21:34:14 dbrownell 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 \f
 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