Home » xml-commons-external-1.4.01-src » org.xml » sax » [javadoc | source]

    1   // SAX input source.
    2   // http://www.saxproject.org
    3   // No warranty; no copyright -- use this as you will.
    4   // $Id: InputSource.java 226184 2005-04-08 10:53:24Z neeraj $
    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

Home » xml-commons-external-1.4.01-src » org.xml » sax » [javadoc | source]