1. /*

  2.  * Copyright (c) 2004 World Wide Web Consortium,

  3.  *

  4.  * (Massachusetts Institute of Technology, European Research Consortium for

  5.  * Informatics and Mathematics, Keio University). All Rights Reserved. This

  6.  * work is distributed under the W3C(r) Software License [1] in the hope that

  7.  * it will be useful, but WITHOUT ANY WARRANTY; without even the implied

  8.  * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

  9.  *

  10.  * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231

  11.  */

  12. 

  13. package org.w3c.dom.ls;

  14. 

  15. /**

  16.  *  This interface represents an input source for data. 

  17.  * <p> This interface allows an application to encapsulate information about 

  18.  * an input source in a single object, which may include a public 

  19.  * identifier, a system identifier, a byte stream (possibly with a specified 

  20.  * encoding), a base URI, and/or a character stream. 

  21.  * <p> The exact definitions of a byte stream and a character stream are 

  22.  * binding dependent. 

  23.  * <p> The application is expected to provide objects that implement this 

  24.  * interface whenever such objects are needed. The application can either 

  25.  * provide its own objects that implement this interface, or it can use the 

  26.  * generic factory method <code>DOMImplementationLS.createLSInput()</code> 

  27.  * to create objects that implement this interface. 

  28.  * <p> The <code>LSParser</code> will use the <code>LSInput</code> object to 

  29.  * determine how to read data. The <code>LSParser</code> will look at the 

  30.  * different inputs specified in the <code>LSInput</code> in the following 

  31.  * order to know which one to read from, the first one that is not null and 

  32.  * not an empty string will be used: 

  33.  * <ol>

  34.  * <li> <code>LSInput.characterStream</code> 

  35.  * </li>

  36.  * <li> 

  37.  * <code>LSInput.byteStream</code> 

  38.  * </li>

  39.  * <li> <code>LSInput.stringData</code> 

  40.  * </li>

  41.  * <li> 

  42.  * <code>LSInput.systemId</code> 

  43.  * </li>

  44.  * <li> <code>LSInput.publicId</code> 

  45.  * </li>

  46.  * </ol> 

  47.  * <p> If all inputs are null, the <code>LSParser</code> will report a 

  48.  * <code>DOMError</code> with its <code>DOMError.type</code> set to 

  49.  * <code>"no-input-specified"</code> and its <code>DOMError.severity</code> 

  50.  * set to <code>DOMError.SEVERITY_FATAL_ERROR</code>. 

  51.  * <p> <code>LSInput</code> objects belong to the application. The DOM 

  52.  * implementation will never modify them (though it may make copies and 

  53.  * modify the copies, if necessary). 

  54.  * <p>See also the <a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407'>Document Object Model (DOM) Level 3 Load

  55. and Save Specification</a>.

  56.  */

  57. public interface LSInput {

  58.     /**

  59.      *  An attribute of a language and binding dependent type that represents 

  60.      * a stream of 16-bit units. The application must encode the stream 

  61.      * using UTF-16 (defined in [Unicode] and in [ISO/IEC 10646]). It is not a requirement to have an XML declaration when 

  62.      * using character streams. If an XML declaration is present, the value 

  63.      * of the encoding attribute will be ignored. 

  64.      */

  65.     public java.io.Reader getCharacterStream();

  66.     /**

  67.      *  An attribute of a language and binding dependent type that represents 

  68.      * a stream of 16-bit units. The application must encode the stream 

  69.      * using UTF-16 (defined in [Unicode] and in [ISO/IEC 10646]). It is not a requirement to have an XML declaration when 

  70.      * using character streams. If an XML declaration is present, the value 

  71.      * of the encoding attribute will be ignored. 

  72.      */

  73.     public void setCharacterStream(java.io.Reader characterStream);

  74. 

  75.     /**

  76.      *  An attribute of a language and binding dependent type that represents 

  77.      * a stream of bytes. 

  78.      * <br> If the application knows the character encoding of the byte 

  79.      * stream, it should set the encoding attribute. Setting the encoding in 

  80.      * this way will override any encoding specified in an XML declaration 

  81.      * in the data. 

  82.      */

  83.     public java.io.InputStream getByteStream();

  84.     /**

  85.      *  An attribute of a language and binding dependent type that represents 

  86.      * a stream of bytes. 

  87.      * <br> If the application knows the character encoding of the byte 

  88.      * stream, it should set the encoding attribute. Setting the encoding in 

  89.      * this way will override any encoding specified in an XML declaration 

  90.      * in the data. 

  91.      */

  92.     public void setByteStream(java.io.InputStream byteStream);

  93. 

  94.     /**

  95.      *  String data to parse. If provided, this will always be treated as a 

  96.      * sequence of 16-bit units (UTF-16 encoded characters). It is not a 

  97.      * requirement to have an XML declaration when using 

  98.      * <code>stringData</code>. If an XML declaration is present, the value 

  99.      * of the encoding attribute will be ignored. 

  100.      */

  101.     public String getStringData();

  102.     /**

  103.      *  String data to parse. If provided, this will always be treated as a 

  104.      * sequence of 16-bit units (UTF-16 encoded characters). It is not a 

  105.      * requirement to have an XML declaration when using 

  106.      * <code>stringData</code>. If an XML declaration is present, the value 

  107.      * of the encoding attribute will be ignored. 

  108.      */

  109.     public void setStringData(String stringData);

  110. 

  111.     /**

  112.      *  The system identifier, a URI reference [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>], for this 

  113.      * input source. The system identifier is optional if there is a byte 

  114.      * stream, a character stream, or string data. It is still useful to 

  115.      * provide one, since the application will use it to resolve any 

  116.      * relative URIs and can include it in error messages and warnings. (The 

  117.      * LSParser will only attempt to fetch the resource identified by the 

  118.      * URI reference if there is no other input available in the input 

  119.      * source.) 

  120.      * <br> If the application knows the character encoding of the object 

  121.      * pointed to by the system identifier, it can set the encoding using 

  122.      * the <code>encoding</code> attribute. 

  123.      * <br> If the specified system ID is a relative URI reference (see 

  124.      * section 5 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]), the DOM 

  125.      * implementation will attempt to resolve the relative URI with the 

  126.      * <code>baseURI</code> as the base, if that fails, the behavior is 

  127.      * implementation dependent. 

  128.      */

  129.     public String getSystemId();

  130.     /**

  131.      *  The system identifier, a URI reference [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>], for this 

  132.      * input source. The system identifier is optional if there is a byte 

  133.      * stream, a character stream, or string data. It is still useful to 

  134.      * provide one, since the application will use it to resolve any 

  135.      * relative URIs and can include it in error messages and warnings. (The 

  136.      * LSParser will only attempt to fetch the resource identified by the 

  137.      * URI reference if there is no other input available in the input 

  138.      * source.) 

  139.      * <br> If the application knows the character encoding of the object 

  140.      * pointed to by the system identifier, it can set the encoding using 

  141.      * the <code>encoding</code> attribute. 

  142.      * <br> If the specified system ID is a relative URI reference (see 

  143.      * section 5 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]), the DOM 

  144.      * implementation will attempt to resolve the relative URI with the 

  145.      * <code>baseURI</code> as the base, if that fails, the behavior is 

  146.      * implementation dependent. 

  147.      */

  148.     public void setSystemId(String systemId);

  149. 

  150.     /**

  151.      *  The public identifier for this input source. This may be mapped to an 

  152.      * input source using an implementation dependent mechanism (such as 

  153.      * catalogues or other mappings). The public identifier, if specified, 

  154.      * may also be reported as part of the location information when errors 

  155.      * are reported. 

  156.      */

  157.     public String getPublicId();

  158.     /**

  159.      *  The public identifier for this input source. This may be mapped to an 

  160.      * input source using an implementation dependent mechanism (such as 

  161.      * catalogues or other mappings). The public identifier, if specified, 

  162.      * may also be reported as part of the location information when errors 

  163.      * are reported. 

  164.      */

  165.     public void setPublicId(String publicId);

  166. 

  167.     /**

  168.      *  The base URI to be used (see section 5.1.4 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]) for 

  169.      * resolving a relative <code>systemId</code> to an absolute URI. 

  170.      * <br> If, when used, the base URI is itself a relative URI, an empty 

  171.      * string, or null, the behavior is implementation dependent. 

  172.      */

  173.     public String getBaseURI();

  174.     /**

  175.      *  The base URI to be used (see section 5.1.4 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]) for 

  176.      * resolving a relative <code>systemId</code> to an absolute URI. 

  177.      * <br> If, when used, the base URI is itself a relative URI, an empty 

  178.      * string, or null, the behavior is implementation dependent. 

  179.      */

  180.     public void setBaseURI(String baseURI);

  181. 

  182.     /**

  183.      *  The character encoding, if known. The encoding must be a string 

  184.      * acceptable for an XML encoding declaration ([<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>] section 

  185.      * 4.3.3 "Character Encoding in Entities"). 

  186.      * <br> This attribute has no effect when the application provides a 

  187.      * character stream or string data. For other sources of input, an 

  188.      * encoding specified by means of this attribute will override any 

  189.      * encoding specified in the XML declaration or the Text declaration, or 

  190.      * an encoding obtained from a higher level protocol, such as HTTP [<a href='http://www.ietf.org/rfc/rfc2616.txt'>IETF RFC 2616</a>]. 

  191.      */

  192.     public String getEncoding();

  193.     /**

  194.      *  The character encoding, if known. The encoding must be a string 

  195.      * acceptable for an XML encoding declaration ([<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>] section 

  196.      * 4.3.3 "Character Encoding in Entities"). 

  197.      * <br> This attribute has no effect when the application provides a 

  198.      * character stream or string data. For other sources of input, an 

  199.      * encoding specified by means of this attribute will override any 

  200.      * encoding specified in the XML declaration or the Text declaration, or 

  201.      * an encoding obtained from a higher level protocol, such as HTTP [<a href='http://www.ietf.org/rfc/rfc2616.txt'>IETF RFC 2616</a>]. 

  202.      */

  203.     public void setEncoding(String encoding);

  204. 

  205.     /**

  206.      *  If set to true, assume that the input is certified (see section 2.13 

  207.      * in [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]) when 

  208.      * parsing [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]. 

  209.      */

  210.     public boolean getCertifiedText();

  211.     /**

  212.      *  If set to true, assume that the input is certified (see section 2.13 

  213.      * in [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]) when 

  214.      * parsing [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]. 

  215.      */

  216.     public void setCertifiedText(boolean certifiedText);

  217. 

  218. }