1320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson/* 2320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Copyright (c) 2004 World Wide Web Consortium, 3320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 4320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * (Massachusetts Institute of Technology, European Research Consortium for 5320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Informatics and Mathematics, Keio University). All Rights Reserved. This 6320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * work is distributed under the W3C(r) Software License [1] in the hope that 7320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * it will be useful, but WITHOUT ANY WARRANTY; without even the implied 8320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 9320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 10320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231 11320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 12320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 13320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonpackage org.w3c.dom.ls; 14320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 15320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonimport org.w3c.dom.DOMConfiguration; 16320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonimport org.w3c.dom.DOMException; 177365de1056414750d0a7d1fdd26025fd247f0d04Jesse Wilsonimport org.w3c.dom.Document; 187365de1056414750d0a7d1fdd26025fd247f0d04Jesse Wilsonimport org.w3c.dom.Node; 19320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 20320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson/** 21f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * An interface to an object that is able to build, or augment, a DOM tree 22f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * from various input sources. 23f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p> <code>LSParser</code> provides an API for parsing XML and building the 24f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * corresponding DOM document structure. A <code>LSParser</code> instance 25f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * can be obtained by invoking the 26f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>DOMImplementationLS.createLSParser()</code> method. 27320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> As specified in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] 28f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * , when a document is first made available via the LSParser: 29320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <ul> 30f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <li> there will 31f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * never be two adjacent nodes of type NODE_TEXT, and there will never be 32f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * empty text nodes. 33320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 34f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <li> it is expected that the <code>value</code> and 35f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>nodeValue</code> attributes of an <code>Attr</code> node initially 36f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * return the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#AVNormalize'>XML 1.0 37320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * normalized value</a>. However, if the parameters "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate-if-schema'> 38320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * validate-if-schema</a>" and "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-datatype-normalization'> 39f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * datatype-normalization</a>" are set to <code>true</code>, depending on the attribute normalization 40f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * used, the attribute values may differ from the ones obtained by the XML 41320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 1.0 attribute normalization. If the parameters "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-datatype-normalization'> 42f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * datatype-normalization</a>" is set to <code>false</code>, the XML 1.0 attribute normalization is 43f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * guaranteed to occur, and if the attributes list does not contain 44f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * namespace declarations, the <code>attributes</code> attribute on 45320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>Element</code> node represents the property <b>[attributes]</b> defined in [<a href='http://www.w3.org/TR/2004/REC-xml-infoset-20040204/'>XML Information Set</a>] 46f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * . 47320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 48320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </ul> 49f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p> Asynchronous <code>LSParser</code> objects are expected to also 50f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * implement the <code>events::EventTarget</code> interface so that event 51f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * listeners can be registered on asynchronous <code>LSParser</code> 52f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * objects. 53f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p> Events supported by asynchronous <code>LSParser</code> objects are: 54320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dl> 55320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt>load</dt> 56320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd> 57f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * The <code>LSParser</code> finishes to load the document. See also the 58320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * definition of the <code>LSLoadEvent</code> interface. </dd> 59320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt>progress</dt> 60f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd> The 61f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>LSParser</code> signals progress as data is parsed. This 62f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * specification does not attempt to define exactly when progress events 63f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * should be dispatched. That is intentionally left as 64f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * implementation-dependent. Here is one example of how an application might 65f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * dispatch progress events: Once the parser starts receiving data, a 66f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * progress event is dispatched to indicate that the parsing starts. From 67f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * there on, a progress event is dispatched for every 4096 bytes of data 68f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * that is received and processed. This is only one example, though, and 69f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * implementations can choose to dispatch progress events at any time while 70f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * parsing, or not dispatch them at all. See also the definition of the 71320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>LSProgressEvent</code> interface. </dd> 72320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </dl> 73f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p ><b>Note:</b> All events defined in this specification use the 74f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * namespace URI <code>"http://www.w3.org/2002/DOMLS"</code>. 75f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p> While parsing an input source, errors are reported to the application 76320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * through the error handler (<code>LSParser.domConfig</code>'s "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> 77f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * error-handler</a>" parameter). This specification does in no way try to define all possible 78f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * errors that can occur while parsing XML, or any other markup, but some 79f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * common error cases are defined. The types (<code>DOMError.type</code>) of 80f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * errors and warnings defined by this specification are: 81320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dl> 82f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dt> 83320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>"check-character-normalization-failure" [error]</code> </dt> 84f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd> Raised if 85320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-check-character-normalization'> 86f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * check-character-normalization</a>" is set to true and a string is encountered that fails normalization 87320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * checking. </dd> 88320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>"doctype-not-allowed" [fatal]</code></dt> 89f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd> Raised if the 90f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * configuration parameter "disallow-doctype" is set to <code>true</code> 91320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * and a doctype is encountered. </dd> 92320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>"no-input-specified" [fatal]</code></dt> 93f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd> 94f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Raised when loading a document and no input is specified in the 95320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>LSInput</code> object. </dd> 96320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 97320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>"pi-base-uri-not-preserved" [warning]</code></dt> 98f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd> Raised if a processing 99f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * instruction is encountered in a location where the base URI of the 100f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * processing instruction can not be preserved. One example of a case where 101320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * this warning will be raised is if the configuration parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-entities'> 102f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * entities</a>" is set to <code>false</code> and the following XML file is parsed: 103320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <pre> 104f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <!DOCTYPE root [ <!ENTITY e SYSTEM 'subdir/myentity.ent' ]> 105320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <root> &e; </root></pre> 106f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * And <code>subdir/myentity.ent</code> 107f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * contains: 108f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <pre><one> <two/> </one> <?pi 3.14159?> 109320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <more/></pre> 110320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </dd> 111320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>"unbound-prefix-in-entity" [warning]</code></dt> 112f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd> An 113f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * implementation dependent warning that may be raised if the configuration 114320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-namespaces'> 115f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * namespaces</a>" is set to <code>true</code> and an unbound namespace prefix is 116f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * encountered in an entity's replacement text. Raising this warning is not 117f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * enforced since some existing parsers may not recognize unbound namespace 118320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * prefixes in the replacement text of entities. </dd> 119320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 120320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>"unknown-character-denormalization" [fatal]</code></dt> 121f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd> Raised if the 122f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * configuration parameter "ignore-unknown-character-denormalizations" is 123f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * set to <code>false</code> and a character is encountered for which the 124320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * processor cannot determine the normalization properties. </dd> 125320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 126320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>"unsupported-encoding" [fatal]</code></dt> 127f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd> Raised if an unsupported 128320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * encoding is encountered. </dd> 129320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>"unsupported-media-type" [fatal]</code></dt> 130f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd> 131f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Raised if the configuration parameter "supported-media-types-only" is set 132320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * to <code>true</code> and an unsupported media type is encountered. </dd> 133f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * </dl> 134f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p> In addition to raising the defined errors and warnings, implementations 135f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * are expected to raise implementation specific errors and warnings for any 136f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * other error and warning cases such as IO errors (file not found, 137f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * permission denied,...), XML well-formedness errors, and so on. 138320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <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 139320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonand Save Specification</a>. 140320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 141320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonpublic interface LSParser { 142320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 143f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * The <code>DOMConfiguration</code> object used when parsing an input 144f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * source. This <code>DOMConfiguration</code> is specific to the parse 145320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * operation. No parameter values from this <code>DOMConfiguration</code> 146f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * object are passed automatically to the <code>DOMConfiguration</code> 147f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * object on the <code>Document</code> that is created, or used, by the 148f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * parse operation. The DOM application is responsible for passing any 149f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * needed parameter values from this <code>DOMConfiguration</code> 150f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * object to the <code>DOMConfiguration</code> object referenced by the 151f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>Document</code> object. 152320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <br> In addition to the parameters recognized in on the <a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#DOMConfiguration'> 153320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * DOMConfiguration</a> interface defined in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] 154f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * , the <code>DOMConfiguration</code> objects for <code>LSParser</code> 155f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * add or modify the following parameters: 156320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dl> 157320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 158320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>"charset-overrides-xml-encoding"</code></dt> 159320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd> 160320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dl> 161320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>true</code></dt> 162f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd>[<em>optional</em>] (<em>default</em>) If a higher level protocol such as HTTP [<a href='http://www.ietf.org/rfc/rfc2616.txt'>IETF RFC 2616</a>] provides an 163f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * indication of the character encoding of the input stream being 164f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * processed, that will override any encoding specified in the XML 165f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * declaration or the Text declaration (see also section 4.3.3, 166f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * "Character Encoding in Entities", in [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>]). 167f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Explicitly setting an encoding in the <code>LSInput</code> overrides 168320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * any encoding from the protocol. </dd> 169320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>false</code></dt> 170f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd>[<em>required</em>] The parser ignores any character set encoding information from 171320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * higher-level protocols. </dd> 172320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </dl></dd> 173320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>"disallow-doctype"</code></dt> 174320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd> 175320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dl> 176320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 177320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>true</code></dt> 178f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd>[<em>optional</em>] Throw a fatal <b>"doctype-not-allowed"</b> error if a doctype node is found while parsing the document. This is 179f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * useful when dealing with things like SOAP envelopes where doctype 180320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * nodes are not allowed. </dd> 181320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>false</code></dt> 182320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd>[<em>required</em>] (<em>default</em>) Allow doctype nodes in the document. </dd> 183320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </dl></dd> 184320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 185320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>"ignore-unknown-character-denormalizations"</code></dt> 186320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd> 187320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dl> 188320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 189320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>true</code></dt> 190f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd>[<em>required</em>] (<em>default</em>) If, while verifying full normalization when [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>] is 191f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * supported, a processor encounters characters for which it cannot 192f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * determine the normalization properties, then the processor will 193f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * ignore any possible denormalizations caused by these characters. 194320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * This parameter is ignored for [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>]. </dd> 195320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 196320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>false</code></dt> 197f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd>[<em>optional</em>] Report an fatal <b>"unknown-character-denormalization"</b> error if a character is encountered for which the processor cannot 198320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * determine the normalization properties. </dd> 199320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </dl></dd> 200320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>"infoset"</code></dt> 201f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd> See 202f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the definition of <code>DOMConfiguration</code> for a description of 203320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * this parameter. Unlike in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] 204f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * , this parameter will default to <code>true</code> for 205320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>LSParser</code>. </dd> 206320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>"namespaces"</code></dt> 207320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd> 208320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dl> 209320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>true</code></dt> 210320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd>[<em>required</em>] (<em>default</em>) Perform the namespace processing as defined in [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>] 211320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * and [<a href='http://www.w3.org/TR/2004/REC-xml-names11-20040204/'>XML Namespaces 1.1</a>] 212320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * . </dd> 213320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>false</code></dt> 214320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd>[<em>optional</em>] Do not perform the namespace processing. </dd> 215320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </dl></dd> 216320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 217320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>"resource-resolver"</code></dt> 218f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd>[<em>required</em>] A reference to a <code>LSResourceResolver</code> object, or null. If 219f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the value of this parameter is not null when an external resource 220f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * (such as an external XML entity or an XML schema location) is 221f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * encountered, the implementation will request that the 222f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>LSResourceResolver</code> referenced in this parameter resolves 223320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the resource. </dd> 224320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>"supported-media-types-only"</code></dt> 225320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd> 226320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dl> 227320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 228320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>true</code></dt> 229f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd>[<em>optional</em>] Check that the media type of the parsed resource is a supported media 230f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * type. If an unsupported media type is encountered, a fatal error of 231f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * type <b>"unsupported-media-type"</b> will be raised. The media types defined in [<a href='http://www.ietf.org/rfc/rfc3023.txt'>IETF RFC 3023</a>] must always 232320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * be accepted. </dd> 233320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>false</code></dt> 234320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dd>[<em>required</em>] (<em>default</em>) Accept any media type. </dd> 235320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </dl></dd> 236320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt><code>"validate"</code></dt> 237f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd> See the definition of 238f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>DOMConfiguration</code> for a description of this parameter. 239320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Unlike in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] 240f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * , the processing of the internal subset is always accomplished, even 241320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * if this parameter is set to <code>false</code>. </dd> 242320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 243320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>"validate-if-schema"</code></dt> 244f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd> See the definition of 245f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>DOMConfiguration</code> for a description of this parameter. 246320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Unlike in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] 247f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * , the processing of the internal subset is always accomplished, even 248320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * if this parameter is set to <code>false</code>. </dd> 249320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <dt> 250320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>"well-formed"</code></dt> 251f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <dd> See the definition of 252f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>DOMConfiguration</code> for a description of this parameter. 253320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Unlike in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] 254320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * , this parameter cannot be set to <code>false</code>. </dd> 255320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </dl> 256320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 257320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public DOMConfiguration getDomConfig(); 258320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 259320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 260f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * When a filter is provided, the implementation will call out to the 261f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * filter as it is constructing the DOM tree structure. The filter can 262f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * choose to remove elements from the document being constructed, or to 263f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * terminate the parsing early. 264f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> The filter is invoked after the operations requested by the 265f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>DOMConfiguration</code> parameters have been applied. For 266320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * example, if "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate'> 267f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * validate</a>" is set to <code>true</code>, the validation is done before invoking the 268f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * filter. 269320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 270320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public LSParserFilter getFilter(); 271320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 272f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * When a filter is provided, the implementation will call out to the 273f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * filter as it is constructing the DOM tree structure. The filter can 274f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * choose to remove elements from the document being constructed, or to 275f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * terminate the parsing early. 276f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> The filter is invoked after the operations requested by the 277f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>DOMConfiguration</code> parameters have been applied. For 278320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * example, if "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate'> 279f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * validate</a>" is set to <code>true</code>, the validation is done before invoking the 280f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * filter. 281320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 282320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public void setFilter(LSParserFilter filter); 283320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 284320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 285f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>true</code> if the <code>LSParser</code> is asynchronous, 286f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>false</code> if it is synchronous. 287320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 288320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public boolean getAsync(); 289320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 290320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 291f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>true</code> if the <code>LSParser</code> is currently busy 292f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * loading a document, otherwise <code>false</code>. 293320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 294320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public boolean getBusy(); 295320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 296320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 297f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Parse an XML document from a resource identified by a 298320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>LSInput</code>. 299f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @param input The <code>LSInput</code> from which the source of the 300f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * document is to be read. 301f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @return If the <code>LSParser</code> is a synchronous 302f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>LSParser</code>, the newly created and populated 303f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>Document</code> is returned. If the <code>LSParser</code> is 304f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * asynchronous, <code>null</code> is returned since the document 305f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * object may not yet be constructed when this method returns. 306320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception DOMException 307f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * INVALID_STATE_ERR: Raised if the <code>LSParser</code>'s 308f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>LSParser.busy</code> attribute is <code>true</code>. 309320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception LSException 310f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * PARSE_ERR: Raised if the <code>LSParser</code> was unable to load 311f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the XML document. DOM applications should attach a 312320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> 313f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * error-handler</a>" if they wish to get details on the error. 314320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 315320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public Document parse(LSInput input) 316320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throws DOMException, LSException; 317320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 318320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 319f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Parse an XML document from a location identified by a URI reference [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]. If the URI 320f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * contains a fragment identifier (see section 4.1 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]), the 321f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * behavior is not defined by this specification, future versions of 322f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * this specification may define the behavior. 323320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param uri The location of the XML document to be read. 324f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @return If the <code>LSParser</code> is a synchronous 325f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>LSParser</code>, the newly created and populated 326f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>Document</code> is returned, or <code>null</code> if an error 327f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * occured. If the <code>LSParser</code> is asynchronous, 328f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>null</code> is returned since the document object may not yet 329f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * be constructed when this method returns. 330320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception DOMException 331f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * INVALID_STATE_ERR: Raised if the <code>LSParser.busy</code> 332f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * attribute is <code>true</code>. 333320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception LSException 334f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * PARSE_ERR: Raised if the <code>LSParser</code> was unable to load 335f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the XML document. DOM applications should attach a 336320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> 337f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * error-handler</a>" if they wish to get details on the error. 338320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 339320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public Document parseURI(String uri) 340320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throws DOMException, LSException; 341320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 342320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson // ACTION_TYPES 343320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 344f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Append the result of the parse operation as children of the context 345f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * node. For this action to work, the context node must be an 346f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>Element</code> or a <code>DocumentFragment</code>. 347320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 348320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public static final short ACTION_APPEND_AS_CHILDREN = 1; 349320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 350f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Replace all the children of the context node with the result of the 351f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * parse operation. For this action to work, the context node must be an 352f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>Element</code>, a <code>Document</code>, or a 353f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>DocumentFragment</code>. 354320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 355320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public static final short ACTION_REPLACE_CHILDREN = 2; 356320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 357f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Insert the result of the parse operation as the immediately preceding 358f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * sibling of the context node. For this action to work the context 359f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * node's parent must be an <code>Element</code> or a 360f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>DocumentFragment</code>. 361320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 362320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public static final short ACTION_INSERT_BEFORE = 3; 363320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 364f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Insert the result of the parse operation as the immediately following 365f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * sibling of the context node. For this action to work the context 366f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * node's parent must be an <code>Element</code> or a 367f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>DocumentFragment</code>. 368320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 369320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public static final short ACTION_INSERT_AFTER = 4; 370320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 371f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Replace the context node with the result of the parse operation. For 372f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * this action to work, the context node must have a parent, and the 373f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * parent must be an <code>Element</code> or a 374f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>DocumentFragment</code>. 375320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 376320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public static final short ACTION_REPLACE = 5; 377320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 378320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 379f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Parse an XML fragment from a resource identified by a 380f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>LSInput</code> and insert the content into an existing document 381f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * at the position specified with the <code>context</code> and 382f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>action</code> arguments. When parsing the input stream, the 383f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * context node (or its parent, depending on where the result will be 384f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * inserted) is used for resolving unbound namespace prefixes. The 385f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * context node's <code>ownerDocument</code> node (or the node itself if 386f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the node of type <code>DOCUMENT_NODE</code>) is used to resolve 387f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * default attributes and entity references. 388f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> As the new data is inserted into the document, at least one 389f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * mutation event is fired per new immediate child or sibling of the 390f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * context node. 391f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> If the context node is a <code>Document</code> node and the action 392f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * is <code>ACTION_REPLACE_CHILDREN</code>, then the document that is 393f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * passed as the context node will be changed such that its 394f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>xmlEncoding</code>, <code>documentURI</code>, 395f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>xmlVersion</code>, <code>inputEncoding</code>, 396f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>xmlStandalone</code>, and all other such attributes are set to 397f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * what they would be set to if the input source was parsed using 398f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>LSParser.parse()</code>. 399f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> This method is always synchronous, even if the 400f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>LSParser</code> is asynchronous (<code>LSParser.async</code> is 401f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>true</code>). 402f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> If an error occurs while parsing, the caller is notified through 403320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the <code>ErrorHandler</code> instance associated with the "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> 404f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * error-handler</a>" parameter of the <code>DOMConfiguration</code>. 405f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> When calling <code>parseWithContext</code>, the values of the 406f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * following configuration parameters will be ignored and their default 407320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * values will always be used instead: "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate'> 408320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * validate</a>", "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate-if-schema'> 409320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * validate-if-schema</a>", and "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-element-content-whitespace'> 410f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * element-content-whitespace</a>". Other parameters will be treated normally, and the parser is expected 411f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * to call the <code>LSParserFilter</code> just as if a whole document 412f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * was parsed. 413f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @param input The <code>LSInput</code> from which the source document 414f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * is to be read. The source document must be an XML fragment, i.e. 415f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * anything except a complete XML document (except in the case where 416f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the context node of type <code>DOCUMENT_NODE</code>, and the action 417f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * is <code>ACTION_REPLACE_CHILDREN</code>), a DOCTYPE (internal 418f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * subset), entity declaration(s), notation declaration(s), or XML or 419f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * text declaration(s). 420f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @param contextArg The node that is used as the context for the data 421f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * that is being parsed. This node must be a <code>Document</code> 422f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * node, a <code>DocumentFragment</code> node, or a node of a type 423f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * that is allowed as a child of an <code>Element</code> node, e.g. it 424f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * cannot be an <code>Attribute</code> node. 425f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @param action This parameter describes which action should be taken 426f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * between the new set of nodes being inserted and the existing 427f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * children of the context node. The set of possible actions is 428f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * defined in <code>ACTION_TYPES</code> above. 429f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @return Return the node that is the result of the parse operation. If 430f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the result is more than one top-level node, the first one is 431f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * returned. 432320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception DOMException 433f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * HIERARCHY_REQUEST_ERR: Raised if the content cannot replace, be 434f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * inserted before, after, or as a child of the context node (see also 435320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>Node.insertBefore</code> or <code>Node.replaceChild</code> in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>] 436320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * ). 437f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> NOT_SUPPORTED_ERR: Raised if the <code>LSParser</code> doesn't 438f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * support this method, or if the context node is of type 439f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>Document</code> and the DOM implementation doesn't support 440f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the replacement of the <code>DocumentType</code> child or 441f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <code>Element</code> child. 442f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is a 443f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * read only node and the content is being appended to its child list, 444f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * or if the parent node of the context node is read only node and the 445320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * content is being inserted in its child list. 446f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <br> INVALID_STATE_ERR: Raised if the <code>LSParser.busy</code> 447f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * attribute is <code>true</code>. 448320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @exception LSException 449f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * PARSE_ERR: Raised if the <code>LSParser</code> was unable to load 450f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the XML fragment. DOM applications should attach a 451320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'> 452f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * error-handler</a>" if they wish to get details on the error. 453320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 454f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes public Node parseWithContext(LSInput input, 455f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes Node contextArg, 456320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson short action) 457320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throws DOMException, LSException; 458320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 459320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 460f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * Abort the loading of the document that is currently being loaded by 461f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * the <code>LSParser</code>. If the <code>LSParser</code> is currently 462f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * not busy, a call to this method does nothing. 463320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 464320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public void abort(); 465320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 466320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson} 467