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