286N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 286N/A * This code is free software; you can redistribute it and/or modify it 286N/A * under the terms of the GNU General Public License version 2 only, as 286N/A * published by the Free Software Foundation. Oracle designates this 286N/A * particular file as subject to the "Classpath" exception as provided 286N/A * by Oracle in the LICENSE file that accompanied this code. 286N/A * This code is distributed in the hope that it will be useful, but WITHOUT 286N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 286N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 286N/A * version 2 for more details (a copy is included in the LICENSE file that 286N/A * accompanied this code). 286N/A * You should have received a copy of the GNU General Public License version 286N/A * 2 along with this work; if not, write to the Free Software Foundation, 286N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 286N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 286N/A * or visit www.oracle.com if you need additional information or have any 286N/A * This file is available under and governed by the GNU General Public 286N/A * License version 2 only, as published by the Free Software Foundation. 286N/A * However, the following notice accompanied the original version of this 286N/A * file and, per its terms, should not be removed: 286N/A * Copyright (c) 2004 World Wide Web Consortium, 286N/A * (Massachusetts Institute of Technology, European Research Consortium for 286N/A * Informatics and Mathematics, Keio University). All Rights Reserved. This 286N/A * work is distributed under the W3C(r) Software License [1] in the hope that 286N/A * it will be useful, but WITHOUT ANY WARRANTY; without even the implied 286N/A * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 286N/A * An interface to an object that is able to build, or augment, a DOM tree 286N/A * from various input sources. 286N/A * <p> <code>LSParser</code> provides an API for parsing XML and building the 286N/A * corresponding DOM document structure. A <code>LSParser</code> instance 286N/A * can be obtained by invoking the 286N/A * <code>DOMImplementationLS.createLSParser()</code> method. 286N/A * , when a document is first made available via the LSParser: 286N/A * never be two adjacent nodes of type NODE_TEXT, and there will never be 286N/A * <li> it is expected that the <code>value</code> and 286N/A * <code>nodeValue</code> attributes of an <code>Attr</code> node initially 286N/A * datatype-normalization</a>" are set to <code>true</code>, depending on the attribute normalization 286N/A * used, the attribute values may differ from the ones obtained by the XML 286N/A * datatype-normalization</a>" is set to <code>false</code>, the XML 1.0 attribute normalization is 286N/A * guaranteed to occur, and if the attributes list does not contain 286N/A * namespace declarations, the <code>attributes</code> attribute on 286N/A * <p> Asynchronous <code>LSParser</code> objects are expected to also 286N/A * implement the <code>events::EventTarget</code> interface so that event 286N/A * listeners can be registered on asynchronous <code>LSParser</code> 286N/A * <p> Events supported by asynchronous <code>LSParser</code> objects are: 286N/A * The <code>LSParser</code> finishes to load the document. See also the 286N/A * definition of the <code>LSLoadEvent</code> interface. </dd> 286N/A * <code>LSParser</code> signals progress as data is parsed. This 286N/A * specification does not attempt to define exactly when progress events 286N/A * should be dispatched. That is intentionally left as 286N/A * implementation-dependent. Here is one example of how an application might 286N/A * dispatch progress events: Once the parser starts receiving data, a 286N/A * progress event is dispatched to indicate that the parsing starts. From 286N/A * there on, a progress event is dispatched for every 4096 bytes of data 286N/A * that is received and processed. This is only one example, though, and 286N/A * implementations can choose to dispatch progress events at any time while 286N/A * parsing, or not dispatch them at all. See also the definition of the 286N/A * <code>LSProgressEvent</code> interface. </dd> 286N/A * <p ><b>Note:</b> All events defined in this specification use the 286N/A * <p> While parsing an input source, errors are reported to the application 286N/A * error-handler</a>" parameter). This specification does in no way try to define all possible 286N/A * errors that can occur while parsing XML, or any other markup, but some 286N/A * common error cases are defined. The types (<code>DOMError.type</code>) of 286N/A * errors and warnings defined by this specification are: 286N/A * <code>"check-character-normalization-failure" [error]</code> </dt> 286N/A * check-character-normalization</a>" is set to true and a string is encountered that fails normalization 286N/A * <dt><code>"doctype-not-allowed" [fatal]</code></dt> 286N/A * configuration parameter "disallow-doctype" is set to <code>true</code> 286N/A * and a doctype is encountered. </dd> 286N/A * <dt><code>"no-input-specified" [fatal]</code></dt> 286N/A * Raised when loading a document and no input is specified in the 286N/A * <code>LSInput</code> object. </dd> 286N/A * <code>"pi-base-uri-not-preserved" [warning]</code></dt> 286N/A * <dd> Raised if a processing 286N/A * instruction is encountered in a location where the base URI of the 286N/A * processing instruction can not be preserved. One example of a case where 286N/A * entities</a>" is set to <code>false</code> and the following XML file is parsed: 286N/A * <root> &e; </root></pre> 286N/A * <pre><one> <two/> </one> <?pi 3.14159?> 286N/A * <dt><code>"unbound-prefix-in-entity" [warning]</code></dt> 286N/A * implementation dependent warning that may be raised if the configuration 286N/A * namespaces</a>" is set to <code>true</code> and an unbound namespace prefix is 286N/A * encountered in an entity's replacement text. Raising this warning is not 286N/A * enforced since some existing parsers may not recognize unbound namespace 286N/A * prefixes in the replacement text of entities. </dd> 286N/A * <code>"unknown-character-denormalization" [fatal]</code></dt> 286N/A * configuration parameter "ignore-unknown-character-denormalizations" is 286N/A * set to <code>false</code> and a character is encountered for which the 286N/A * processor cannot determine the normalization properties. </dd> 286N/A * <code>"unsupported-encoding" [fatal]</code></dt> 286N/A * <dd> Raised if an unsupported 286N/A * encoding is encountered. </dd> 286N/A * <dt><code>"unsupported-media-type" [fatal]</code></dt> 286N/A * Raised if the configuration parameter "supported-media-types-only" is set 286N/A * to <code>true</code> and an unsupported media type is encountered. </dd> 286N/A * <p> In addition to raising the defined errors and warnings, implementations 286N/A * are expected to raise implementation specific errors and warnings for any 286N/A * other error and warning cases such as IO errors (file not found, 286N/A * permission denied,...), XML well-formedness errors, and so on. 286N/Aand Save Specification</a>. 286N/A * The <code>DOMConfiguration</code> object used when parsing an input 286N/A * source. This <code>DOMConfiguration</code> is specific to the parse 286N/A * operation. No parameter values from this <code>DOMConfiguration</code> 286N/A * object are passed automatically to the <code>DOMConfiguration</code> 286N/A * object on the <code>Document</code> that is created, or used, by the 286N/A * parse operation. The DOM application is responsible for passing any 286N/A * needed parameter values from this <code>DOMConfiguration</code> 286N/A * object to the <code>DOMConfiguration</code> object referenced by the 286N/A * <code>Document</code> object. 286N/A * , the <code>DOMConfiguration</code> objects for <code>LSParser</code> 286N/A * add or modify the following parameters: 286N/A * <code>"charset-overrides-xml-encoding"</code></dt> 286N/A * <dt><code>true</code></dt> 286N/A * indication of the character encoding of the input stream being 286N/A * processed, that will override any encoding specified in the XML 286N/A * declaration or the Text declaration (see also section 4.3.3, 286N/A * Explicitly setting an encoding in the <code>LSInput</code> overrides 286N/A * any encoding from the protocol. </dd> 286N/A * <dt><code>false</code></dt> 286N/A * <dd>[<em>required</em>] The parser ignores any character set encoding information from 286N/A * higher-level protocols. </dd> 286N/A * <dt><code>"disallow-doctype"</code></dt> 286N/A * <code>true</code></dt> 286N/A * <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 286N/A * useful when dealing with things like SOAP envelopes where doctype 286N/A * nodes are not allowed. </dd> 286N/A * <dt><code>false</code></dt> 286N/A * <dd>[<em>required</em>] (<em>default</em>) Allow doctype nodes in the document. </dd> 286N/A * <code>"ignore-unknown-character-denormalizations"</code></dt> 286N/A * <code>true</code></dt> 286N/A * supported, a processor encounters characters for which it cannot 286N/A * determine the normalization properties, then the processor will 286N/A * ignore any possible denormalizations caused by these characters. 286N/A * <code>false</code></dt> 286N/A * <dd>[<em>optional</em>] Report an fatal <b>"unknown-character-denormalization"</b> error if a character is encountered for which the processor cannot 286N/A * determine the normalization properties. </dd> 286N/A * <dt><code>"infoset"</code></dt> 286N/A * the definition of <code>DOMConfiguration</code> for a description of 286N/A * , this parameter will default to <code>true</code> for 286N/A * <code>LSParser</code>. </dd> 286N/A * <dt><code>"namespaces"</code></dt> 286N/A * <dt><code>true</code></dt> 286N/A * <dt><code>false</code></dt> 286N/A * <dd>[<em>optional</em>] Do not perform the namespace processing. </dd> 286N/A * <code>"resource-resolver"</code></dt> 286N/A * <dd>[<em>required</em>] A reference to a <code>LSResourceResolver</code> object, or null. If 286N/A * the value of this parameter is not null when an external resource 286N/A * (such as an external XML entity or an XML schema location) is 286N/A * encountered, the implementation will request that the 286N/A * <code>LSResourceResolver</code> referenced in this parameter resolves 286N/A * <dt><code>"supported-media-types-only"</code></dt> 286N/A * <code>true</code></dt> 286N/A * <dd>[<em>optional</em>] Check that the media type of the parsed resource is a supported media 286N/A * type. If an unsupported media type is encountered, a fatal error of 286N/A * <dt><code>false</code></dt> 286N/A * <dd>[<em>required</em>] (<em>default</em>) Accept any media type. </dd> 286N/A * <dt><code>"validate"</code></dt> 286N/A * <dd> See the definition of 286N/A * <code>DOMConfiguration</code> for a description of this parameter. 286N/A * , the processing of the internal subset is always accomplished, even 286N/A * if this parameter is set to <code>false</code>. </dd> 286N/A * <code>"validate-if-schema"</code></dt> 286N/A * <dd> See the definition of 286N/A * <code>DOMConfiguration</code> for a description of this parameter. 286N/A * , the processing of the internal subset is always accomplished, even 286N/A * if this parameter is set to <code>false</code>. </dd> 286N/A * <code>"well-formed"</code></dt> 286N/A * <dd> See the definition of 286N/A * <code>DOMConfiguration</code> for a description of this parameter. 286N/A * , this parameter cannot be set to <code>false</code>. </dd> 286N/A * When a filter is provided, the implementation will call out to the 286N/A * filter as it is constructing the DOM tree structure. The filter can 286N/A * choose to remove elements from the document being constructed, or to 286N/A * terminate the parsing early. 286N/A * <br> The filter is invoked after the operations requested by the 286N/A * <code>DOMConfiguration</code> parameters have been applied. For 286N/A * validate</a>" is set to <code>true</code>, the validation is done before invoking the 286N/A * When a filter is provided, the implementation will call out to the 286N/A * filter as it is constructing the DOM tree structure. The filter can 286N/A * choose to remove elements from the document being constructed, or to 286N/A * terminate the parsing early. 286N/A * <br> The filter is invoked after the operations requested by the 286N/A * <code>DOMConfiguration</code> parameters have been applied. For 286N/A * validate</a>" is set to <code>true</code>, the validation is done before invoking the 286N/A * <code>true</code> if the <code>LSParser</code> is asynchronous, 286N/A * <code>false</code> if it is synchronous. 286N/A * <code>true</code> if the <code>LSParser</code> is currently busy 286N/A * loading a document, otherwise <code>false</code>. 286N/A * Parse an XML document from a resource identified by a 286N/A * <code>LSInput</code>. 286N/A * @param input The <code>LSInput</code> from which the source of the 286N/A * document is to be read. 286N/A * @return If the <code>LSParser</code> is a synchronous 286N/A * <code>LSParser</code>, the newly created and populated 286N/A * <code>Document</code> is returned. If the <code>LSParser</code> is 286N/A * asynchronous, <code>null</code> is returned since the document 286N/A * object may not yet be constructed when this method returns. 286N/A * @exception DOMException 286N/A * INVALID_STATE_ERR: Raised if the <code>LSParser</code>'s 286N/A * <code>LSParser.busy</code> attribute is <code>true</code>. 286N/A * @exception LSException 286N/A * PARSE_ERR: Raised if the <code>LSParser</code> was unable to load 286N/A * the XML document. DOM applications should attach a 286N/A * error-handler</a>" if they wish to get details on the error. 286N/A * behavior is not defined by this specification, future versions of 286N/A * this specification may define the behavior. 286N/A * @param uri The location of the XML document to be read. 286N/A * @return If the <code>LSParser</code> is a synchronous 286N/A * <code>LSParser</code>, the newly created and populated 286N/A * <code>Document</code> is returned, or <code>null</code> if an error 286N/A * occured. If the <code>LSParser</code> is asynchronous, 286N/A * <code>null</code> is returned since the document object may not yet 286N/A * be constructed when this method returns. 286N/A * @exception DOMException 286N/A * INVALID_STATE_ERR: Raised if the <code>LSParser.busy</code> 286N/A * attribute is <code>true</code>. 286N/A * @exception LSException 286N/A * PARSE_ERR: Raised if the <code>LSParser</code> was unable to load 286N/A * the XML document. DOM applications should attach a 286N/A * error-handler</a>" if they wish to get details on the error. 286N/A * Append the result of the parse operation as children of the context 286N/A * node. For this action to work, the context node must be an 286N/A * <code>Element</code> or a <code>DocumentFragment</code>. 286N/A * Replace all the children of the context node with the result of the 286N/A * parse operation. For this action to work, the context node must be an 286N/A * <code>Element</code>, a <code>Document</code>, or a 286N/A * <code>DocumentFragment</code>. 286N/A * Insert the result of the parse operation as the immediately preceding 286N/A * sibling of the context node. For this action to work the context 286N/A * node's parent must be an <code>Element</code> or a 286N/A * <code>DocumentFragment</code>. 286N/A * Insert the result of the parse operation as the immediately following 286N/A * sibling of the context node. For this action to work the context 286N/A * node's parent must be an <code>Element</code> or a 286N/A * <code>DocumentFragment</code>. 286N/A * Replace the context node with the result of the parse operation. For 286N/A * this action to work, the context node must have a parent, and the 286N/A * parent must be an <code>Element</code> or a 286N/A * <code>DocumentFragment</code>. 286N/A * Parse an XML fragment from a resource identified by a 286N/A * <code>LSInput</code> and insert the content into an existing document 286N/A * at the position specified with the <code>context</code> and 286N/A * <code>action</code> arguments. When parsing the input stream, the 286N/A * context node (or its parent, depending on where the result will be 286N/A * inserted) is used for resolving unbound namespace prefixes. The 286N/A * context node's <code>ownerDocument</code> node (or the node itself if 286N/A * the node of type <code>DOCUMENT_NODE</code>) is used to resolve 286N/A * default attributes and entity references. 286N/A * <br> As the new data is inserted into the document, at least one 286N/A * mutation event is fired per new immediate child or sibling of the 286N/A * <br> If the context node is a <code>Document</code> node and the action 286N/A * is <code>ACTION_REPLACE_CHILDREN</code>, then the document that is 286N/A * passed as the context node will be changed such that its 286N/A * <code>xmlEncoding</code>, <code>documentURI</code>, 286N/A * <code>xmlVersion</code>, <code>inputEncoding</code>, 286N/A * <code>xmlStandalone</code>, and all other such attributes are set to 286N/A * what they would be set to if the input source was parsed using 286N/A * <code>LSParser.parse()</code>. 286N/A * <br> This method is always synchronous, even if the 286N/A * <code>LSParser</code> is asynchronous (<code>LSParser.async</code> is 286N/A * <br> If an error occurs while parsing, the caller is notified through 286N/A * error-handler</a>" parameter of the <code>DOMConfiguration</code>. 286N/A * <br> When calling <code>parseWithContext</code>, the values of the 286N/A * following configuration parameters will be ignored and their default 286N/A * element-content-whitespace</a>". Other parameters will be treated normally, and the parser is expected 286N/A * to call the <code>LSParserFilter</code> just as if a whole document 286N/A * @param input The <code>LSInput</code> from which the source document 286N/A * is to be read. The source document must be an XML fragment, i.e. 286N/A * anything except a complete XML document (except in the case where 286N/A * the context node of type <code>DOCUMENT_NODE</code>, and the action 286N/A * is <code>ACTION_REPLACE_CHILDREN</code>), a DOCTYPE (internal 286N/A * subset), entity declaration(s), notation declaration(s), or XML or 286N/A * @param contextArg The node that is used as the context for the data 286N/A * that is being parsed. This node must be a <code>Document</code> 286N/A * node, a <code>DocumentFragment</code> node, or a node of a type 286N/A * that is allowed as a child of an <code>Element</code> node, e.g. it 286N/A * cannot be an <code>Attribute</code> node. 286N/A * @param action This parameter describes which action should be taken 286N/A * between the new set of nodes being inserted and the existing 286N/A * children of the context node. The set of possible actions is 286N/A * defined in <code>ACTION_TYPES</code> above. 286N/A * @return Return the node that is the result of the parse operation. If 286N/A * the result is more than one top-level node, the first one is 286N/A * @exception DOMException 286N/A * HIERARCHY_REQUEST_ERR: Raised if the content cannot replace, be 286N/A * inserted before, after, or as a child of the context node (see also 286N/A * <br> NOT_SUPPORTED_ERR: Raised if the <code>LSParser</code> doesn't 286N/A * support this method, or if the context node is of type 286N/A * <code>Document</code> and the DOM implementation doesn't support 286N/A * the replacement of the <code>DocumentType</code> child or 286N/A * <code>Element</code> child. 286N/A * <br> NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is a 286N/A * read only node and the content is being appended to its child list, 286N/A * or if the parent node of the context node is read only node and the 286N/A * content is being inserted in its child list. 286N/A * <br> INVALID_STATE_ERR: Raised if the <code>LSParser.busy</code> 286N/A * attribute is <code>true</code>. 286N/A * @exception LSException 286N/A * PARSE_ERR: Raised if the <code>LSParser</code> was unable to load 286N/A * the XML fragment. DOM applications should attach a 286N/A * error-handler</a>" if they wish to get details on the error. 286N/A * Abort the loading of the document that is currently being loaded by 286N/A * the <code>LSParser</code>. If the <code>LSParser</code> is currently 286N/A * not busy, a call to this method does nothing.