Upgrading to sax 2.0.1 (sax2r2) from http://sourceforge.net/projects/sax/ as per Edwin Goei.

git-svn-id: https://svn.apache.org/repos/asf/xml/commons/trunk@225961 13f79535-47bb-0310-9956-ffa450edef68

java/external/src/org/xml/sax/InputSource.java

@@ -1,4 +1,5 @@
 // SAX input source.
+// http://www.saxproject.org
 // No warranty; no copyright -- use this as you will.
 // $Id$
 
@@ -13,6 +14,8 @@ import java.io.InputStream;
  * <blockquote>
  * <em>This module, both source code and documentation, is in the
  * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
  * </blockquote>
  *
  * <p>This class allows a SAX application to encapsulate information
@@ -20,28 +23,36 @@ import java.io.InputStream;
  * a public identifier, a system identifier, a byte stream (possibly
  * with a specified encoding), and/or a character stream.</p>
  *
- * <p>There are two places that the application will deliver this
+ * <p>There are two places that the application can deliver an
  * input source to the parser: as the argument to the Parser.parse
  * method, or as the return value of the EntityResolver.resolveEntity
  * method.</p>
  *
  * <p>The SAX parser will use the InputSource object to determine how
  * to read XML input.  If there is a character stream available, the
- * parser will read that stream directly; if not, the parser will use
- * a byte stream, if available; if neither a character stream nor a
+ * parser will read that stream directly, disregarding any text
+ * encoding declaration found in that stream.
+ * If there is no character stream, but there is
+ * a byte stream, the parser will use that byte stream, using the
+ * encoding specified in the InputSource or else (if no encoding is
+ * specified) autodetecting the character encoding using an algorithm
+ * such as the one in the XML specification.  If neither a character
+ * stream nor a
  * byte stream is available, the parser will attempt to open a URI
  * connection to the resource identified by the system
  * identifier.</p>
  *
  * <p>An InputSource object belongs to the application: the SAX parser
  * shall never modify it in any way (it may modify a copy if 
- * necessary).</p>
+ * necessary).  However, standard processing of both byte and
+ * character streams is to close them on as part of end-of-parse cleanup,
+ * so applications should not attempt to re-use such streams after they
+ * have been handed to a parser.  </p>
  *
  * @since SAX 1.0
- * @author David Megginson, 
- *         <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
- * @see org.xml.sax.Parser#parse
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
+ * @see org.xml.sax.XMLReader#parse(org.xml.sax.InputSource)
  * @see org.xml.sax.EntityResolver#resolveEntity
  * @see java.io.InputStream
  * @see java.io.Reader
@@ -69,7 +80,8 @@ public class InputSource {
      * public identifier as well, or setEncoding to specify
      * the character encoding, if known.</p>
      *
-     * <p>If the system identifier is a URL, it must be full resolved.</p>
+     * <p>If the system identifier is a URL, it must be fully
+     * resolved (it may not be a relative URL).</p>
      *
      * @param systemId The system identifier (URI).
      * @see #setPublicId
@@ -87,9 +99,9 @@ public class InputSource {
     /**
      * Create a new input source with a byte stream.
      *
-     * <p>Application writers may use setSystemId to provide a base 
-     * for resolving relative URIs, setPublicId to include a 
-     * public identifier, and/or setEncoding to specify the object's
+     * <p>Application writers should use setSystemId() to provide a base 
+     * for resolving relative URIs, may use setPublicId to include a 
+     * public identifier, and may use setEncoding to specify the object's
      * character encoding.</p>
      *
      * @param byteStream The raw byte stream containing the document.
@@ -108,8 +120,8 @@ public class InputSource {
     /**
      * Create a new input source with a character stream.
      *
-     * <p>Application writers may use setSystemId() to provide a base 
-     * for resolving relative URIs, and setPublicId to include a 
+     * <p>Application writers should use setSystemId() to provide a base 
+     * for resolving relative URIs, and may use setPublicId to include a 
      * public identifier.</p>
      *
      * <p>The character stream shall not include a byte order mark.</p>
@@ -169,7 +181,8 @@ public class InputSource {
      * object pointed to by the system identifier, it can register
      * the encoding using the setEncoding method.</p>
      *
-     * <p>If the system ID is a URL, it must be fully resolved.</p>
+     * <p>If the system identifier is a URL, it must be fully
+     * resolved (it may not be a relative URL).</p>
      *
      * @param systemId The system identifier as a string.
      * @see #setEncoding
@@ -263,6 +276,8 @@ public class InputSource {
     
     /**
      * Get the character encoding for a byte stream or URI.
+     * This value will be ignored when the application provides a
+     * character stream.
      *
      * @return The encoding, or null if none was supplied.
      * @see #setByteStream