Source for org.w3c.dom.ls.LSInput

   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: }