001    /*
002     * Copyright (c) 2004 World Wide Web Consortium,
003     *
004     * (Massachusetts Institute of Technology, European Research Consortium for
005     * Informatics and Mathematics, Keio University). All Rights Reserved. This
006     * work is distributed under the W3C(r) Software License [1] in the hope that
007     * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
008     * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
009     *
010     * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
011     */
012    
013    package org.w3c.dom.ls;
014    
015    import org.w3c.dom.Document;
016    import org.w3c.dom.DOMConfiguration;
017    import org.w3c.dom.Node;
018    import org.w3c.dom.DOMException;
019    
020    /**
021     *  An interface to an object that is able to build, or augment, a DOM tree
022     * from various input sources.
023     * <p> <code>LSParser</code> provides an API for parsing XML and building the
024     * corresponding DOM document structure. A <code>LSParser</code> instance
025     * can be obtained by invoking the
026     * <code>DOMImplementationLS.createLSParser()</code> method.
027     * <p> As specified in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
028     * , when a document is first made available via the LSParser:
029     * <ul>
030     * <li> there will
031     * never be two adjacent nodes of type NODE_TEXT, and there will never be
032     * empty text nodes.
033     * </li>
034     * <li> it is expected that the <code>value</code> and
035     * <code>nodeValue</code> attributes of an <code>Attr</code> node initially
036     * return the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#AVNormalize'>XML 1.0
037     * normalized value</a>. However, if the parameters "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate-if-schema'>
038     * validate-if-schema</a>" and "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-datatype-normalization'>
039     * datatype-normalization</a>" are set to <code>true</code>, depending on the attribute normalization
040     * used, the attribute values may differ from the ones obtained by the XML
041     * 1.0 attribute normalization. If the parameters "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-datatype-normalization'>
042     * datatype-normalization</a>" is set to <code>false</code>, the XML 1.0 attribute normalization is
043     * guaranteed to occur, and if the attributes list does not contain
044     * namespace declarations, the <code>attributes</code> attribute on
045     * <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>]
046     * .
047     * </li>
048     * </ul>
049     * <p> Asynchronous <code>LSParser</code> objects are expected to also
050     * implement the <code>events::EventTarget</code> interface so that event
051     * listeners can be registered on asynchronous <code>LSParser</code>
052     * objects.
053     * <p> Events supported by asynchronous <code>LSParser</code> objects are:
054     * <dl>
055     * <dt>load</dt>
056     * <dd>
057     *  The <code>LSParser</code> finishes to load the document. See also the
058     * definition of the <code>LSLoadEvent</code> interface. </dd>
059     * <dt>progress</dt>
060     * <dd> The
061     * <code>LSParser</code> signals progress as data is parsed.  This
062     * specification does not attempt to define exactly when progress events
063     * should be dispatched. That is intentionally left as
064     * implementation-dependent. Here is one example of how an application might
065     * dispatch progress events: Once the parser starts receiving data, a
066     * progress event is dispatched to indicate that the parsing starts. From
067     * there on, a progress event is dispatched for every 4096 bytes of data
068     * that is received and processed. This is only one example, though, and
069     * implementations can choose to dispatch progress events at any time while
070     * parsing, or not dispatch them at all.  See also the definition of the
071     * <code>LSProgressEvent</code> interface. </dd>
072     * </dl>
073     * <p ><b>Note:</b>  All events defined in this specification use the
074     * namespace URI <code>"http://www.w3.org/2002/DOMLS"</code>.
075     * <p> While parsing an input source, errors are reported to the application
076     * 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'>
077     * error-handler</a>" parameter). This specification does in no way try to define all possible
078     * errors that can occur while parsing XML, or any other markup, but some
079     * common error cases are defined. The types (<code>DOMError.type</code>) of
080     * errors and warnings defined by this specification are:
081     * <dl>
082     * <dt>
083     * <code>"check-character-normalization-failure" [error]</code> </dt>
084     * <dd> Raised if
085     * the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-check-character-normalization'>
086     * check-character-normalization</a>" is set to true and a string is encountered that fails normalization
087     * checking. </dd>
088     * <dt><code>"doctype-not-allowed" [fatal]</code></dt>
089     * <dd> Raised if the
090     * configuration parameter "disallow-doctype" is set to <code>true</code>
091     * and a doctype is encountered. </dd>
092     * <dt><code>"no-input-specified" [fatal]</code></dt>
093     * <dd>
094     * Raised when loading a document and no input is specified in the
095     * <code>LSInput</code> object. </dd>
096     * <dt>
097     * <code>"pi-base-uri-not-preserved" [warning]</code></dt>
098     * <dd> Raised if a processing
099     * instruction is encountered in a location where the base URI of the
100     * processing instruction can not be preserved.  One example of a case where
101     * 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'>
102     * entities</a>" is set to <code>false</code> and the following XML file is parsed:
103     * <pre>
104     * &lt;!DOCTYPE root [ &lt;!ENTITY e SYSTEM 'subdir/myentity.ent' ]&gt;
105     * &lt;root&gt; &amp;e; &lt;/root&gt;</pre>
106     *  And <code>subdir/myentity.ent</code>
107     * contains:
108     * <pre>&lt;one&gt; &lt;two/&gt; &lt;/one&gt; &lt;?pi 3.14159?&gt;
109     * &lt;more/&gt;</pre>
110     * </dd>
111     * <dt><code>"unbound-prefix-in-entity" [warning]</code></dt>
112     * <dd> An
113     * implementation dependent warning that may be raised if the configuration
114     * parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-namespaces'>
115     * namespaces</a>" is set to <code>true</code> and an unbound namespace prefix is
116     * encountered in an entity's replacement text. Raising this warning is not
117     * enforced since some existing parsers may not recognize unbound namespace
118     * prefixes in the replacement text of entities. </dd>
119     * <dt>
120     * <code>"unknown-character-denormalization" [fatal]</code></dt>
121     * <dd> Raised if the
122     * configuration parameter "ignore-unknown-character-denormalizations" is
123     * set to <code>false</code> and a character is encountered for which the
124     * processor cannot determine the normalization properties. </dd>
125     * <dt>
126     * <code>"unsupported-encoding" [fatal]</code></dt>
127     * <dd> Raised if an unsupported
128     * encoding is encountered. </dd>
129     * <dt><code>"unsupported-media-type" [fatal]</code></dt>
130     * <dd>
131     * Raised if the configuration parameter "supported-media-types-only" is set
132     * to <code>true</code> and an unsupported media type is encountered. </dd>
133     * </dl>
134     * <p> In addition to raising the defined errors and warnings, implementations
135     * are expected to raise implementation specific errors and warnings for any
136     * other error and warning cases such as IO errors (file not found,
137     * permission denied,...), XML well-formedness errors, and so on.
138     * <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
139    and Save Specification</a>.
140     */
141    public interface LSParser {
142        /**
143         *  The <code>DOMConfiguration</code> object used when parsing an input
144         * source. This <code>DOMConfiguration</code> is specific to the parse
145         * operation. No parameter values from this <code>DOMConfiguration</code>
146         *  object are passed automatically to the <code>DOMConfiguration</code>
147         * object on the <code>Document</code> that is created, or used, by the
148         * parse operation. The DOM application is responsible for passing any
149         * needed parameter values from this <code>DOMConfiguration</code>
150         * object to the <code>DOMConfiguration</code> object referenced by the
151         * <code>Document</code> object.
152         * <br> In addition to the parameters recognized in on the <a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#DOMConfiguration'>
153         * DOMConfiguration</a> interface defined in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
154         * , the <code>DOMConfiguration</code> objects for <code>LSParser</code>
155         * add or modify the following parameters:
156         * <dl>
157         * <dt>
158         * <code>"charset-overrides-xml-encoding"</code></dt>
159         * <dd>
160         * <dl>
161         * <dt><code>true</code></dt>
162         * <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
163         * indication of the character encoding of the input stream being
164         * processed, that will override any encoding specified in the XML
165         * declaration or the Text declaration (see also section 4.3.3,
166         * "Character Encoding in Entities", in [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>]).
167         * Explicitly setting an encoding in the <code>LSInput</code> overrides
168         * any encoding from the protocol. </dd>
169         * <dt><code>false</code></dt>
170         * <dd>[<em>required</em>] The parser ignores any character set encoding information from
171         * higher-level protocols. </dd>
172         * </dl></dd>
173         * <dt><code>"disallow-doctype"</code></dt>
174         * <dd>
175         * <dl>
176         * <dt>
177         * <code>true</code></dt>
178         * <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
179         * useful when dealing with things like SOAP envelopes where doctype
180         * nodes are not allowed. </dd>
181         * <dt><code>false</code></dt>
182         * <dd>[<em>required</em>] (<em>default</em>) Allow doctype nodes in the document. </dd>
183         * </dl></dd>
184         * <dt>
185         * <code>"ignore-unknown-character-denormalizations"</code></dt>
186         * <dd>
187         * <dl>
188         * <dt>
189         * <code>true</code></dt>
190         * <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
191         * supported, a processor encounters characters for which it cannot
192         * determine the normalization properties, then the processor will
193         * ignore any possible denormalizations caused by these characters.
194         * This parameter is ignored for [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>]. </dd>
195         * <dt>
196         * <code>false</code></dt>
197         * <dd>[<em>optional</em>] Report an fatal <b>"unknown-character-denormalization"</b> error if a character is encountered for which the processor cannot
198         * determine the normalization properties. </dd>
199         * </dl></dd>
200         * <dt><code>"infoset"</code></dt>
201         * <dd> See
202         * the definition of <code>DOMConfiguration</code> for a description of
203         * this parameter. Unlike in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
204         * , this parameter will default to <code>true</code> for
205         * <code>LSParser</code>. </dd>
206         * <dt><code>"namespaces"</code></dt>
207         * <dd>
208         * <dl>
209         * <dt><code>true</code></dt>
210         * <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>]
211         *  and [<a href='http://www.w3.org/TR/2004/REC-xml-names11-20040204/'>XML Namespaces 1.1</a>]
212         * . </dd>
213         * <dt><code>false</code></dt>
214         * <dd>[<em>optional</em>] Do not perform the namespace processing. </dd>
215         * </dl></dd>
216         * <dt>
217         * <code>"resource-resolver"</code></dt>
218         * <dd>[<em>required</em>] A reference to a <code>LSResourceResolver</code> object, or null. If
219         * the value of this parameter is not null when an external resource
220         * (such as an external XML entity or an XML schema location) is
221         * encountered, the implementation will request that the
222         * <code>LSResourceResolver</code> referenced in this parameter resolves
223         * the resource. </dd>
224         * <dt><code>"supported-media-types-only"</code></dt>
225         * <dd>
226         * <dl>
227         * <dt>
228         * <code>true</code></dt>
229         * <dd>[<em>optional</em>] Check that the media type of the parsed resource is a supported media
230         * type. If an unsupported media type is encountered, a fatal error of
231         * 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
232         * be accepted. </dd>
233         * <dt><code>false</code></dt>
234         * <dd>[<em>required</em>] (<em>default</em>) Accept any media type. </dd>
235         * </dl></dd>
236         * <dt><code>"validate"</code></dt>
237         * <dd> See the definition of
238         * <code>DOMConfiguration</code> for a description of this parameter.
239         * Unlike in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
240         * , the processing of the internal subset is always accomplished, even
241         * if this parameter is set to <code>false</code>. </dd>
242         * <dt>
243         * <code>"validate-if-schema"</code></dt>
244         * <dd> See the definition of
245         * <code>DOMConfiguration</code> for a description of this parameter.
246         * Unlike in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
247         * , the processing of the internal subset is always accomplished, even
248         * if this parameter is set to <code>false</code>. </dd>
249         * <dt>
250         * <code>"well-formed"</code></dt>
251         * <dd> See the definition of
252         * <code>DOMConfiguration</code> for a description of this parameter.
253         * Unlike in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
254         * , this parameter cannot be set to <code>false</code>. </dd>
255         * </dl>
256         */
257        public DOMConfiguration getDomConfig();
258    
259        /**
260         *  When a filter is provided, the implementation will call out to the
261         * filter as it is constructing the DOM tree structure. The filter can
262         * choose to remove elements from the document being constructed, or to
263         * terminate the parsing early.
264         * <br> The filter is invoked after the operations requested by the
265         * <code>DOMConfiguration</code> parameters have been applied. For
266         * example, if "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate'>
267         * validate</a>" is set to <code>true</code>, the validation is done before invoking the
268         * filter.
269         */
270        public LSParserFilter getFilter();
271        /**
272         *  When a filter is provided, the implementation will call out to the
273         * filter as it is constructing the DOM tree structure. The filter can
274         * choose to remove elements from the document being constructed, or to
275         * terminate the parsing early.
276         * <br> The filter is invoked after the operations requested by the
277         * <code>DOMConfiguration</code> parameters have been applied. For
278         * example, if "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate'>
279         * validate</a>" is set to <code>true</code>, the validation is done before invoking the
280         * filter.
281         */
282        public void setFilter(LSParserFilter filter);
283    
284        /**
285         *  <code>true</code> if the <code>LSParser</code> is asynchronous,
286         * <code>false</code> if it is synchronous.
287         */
288        public boolean getAsync();
289    
290        /**
291         *  <code>true</code> if the <code>LSParser</code> is currently busy
292         * loading a document, otherwise <code>false</code>.
293         */
294        public boolean getBusy();
295    
296        /**
297         * Parse an XML document from a resource identified by a
298         * <code>LSInput</code>.
299         * @param input  The <code>LSInput</code> from which the source of the
300         *   document is to be read.
301         * @return  If the <code>LSParser</code> is a synchronous
302         *   <code>LSParser</code>, the newly created and populated
303         *   <code>Document</code> is returned. If the <code>LSParser</code> is
304         *   asynchronous, <code>null</code> is returned since the document
305         *   object may not yet be constructed when this method returns.
306         * @exception DOMException
307         *    INVALID_STATE_ERR: Raised if the <code>LSParser</code>'s
308         *   <code>LSParser.busy</code> attribute is <code>true</code>.
309         * @exception LSException
310         *    PARSE_ERR: Raised if the <code>LSParser</code> was unable to load
311         *   the XML document. DOM applications should attach a
312         *   <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'>
313         *   error-handler</a>" if they wish to get details on the error.
314         */
315        public Document parse(LSInput input)
316                              throws DOMException, LSException;
317    
318        /**
319         *  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
320         * contains a fragment identifier (see section 4.1 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]), the
321         * behavior is not defined by this specification, future versions of
322         * this specification may define the behavior.
323         * @param uri The location of the XML document to be read.
324         * @return  If the <code>LSParser</code> is a synchronous
325         *   <code>LSParser</code>, the newly created and populated
326         *   <code>Document</code> is returned, or <code>null</code> if an error
327         *   occured. If the <code>LSParser</code> is asynchronous,
328         *   <code>null</code> is returned since the document object may not yet
329         *   be constructed when this method returns.
330         * @exception DOMException
331         *    INVALID_STATE_ERR: Raised if the <code>LSParser.busy</code>
332         *   attribute is <code>true</code>.
333         * @exception LSException
334         *    PARSE_ERR: Raised if the <code>LSParser</code> was unable to load
335         *   the XML document. DOM applications should attach a
336         *   <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'>
337         *   error-handler</a>" if they wish to get details on the error.
338         */
339        public Document parseURI(String uri)
340                                 throws DOMException, LSException;
341    
342        // ACTION_TYPES
343        /**
344         *  Append the result of the parse operation as children of the context
345         * node. For this action to work, the context node must be an
346         * <code>Element</code> or a <code>DocumentFragment</code>.
347         */
348        public static final short ACTION_APPEND_AS_CHILDREN = 1;
349        /**
350         *  Replace all the children of the context node with the result of the
351         * parse operation. For this action to work, the context node must be an
352         * <code>Element</code>, a <code>Document</code>, or a
353         * <code>DocumentFragment</code>.
354         */
355        public static final short ACTION_REPLACE_CHILDREN   = 2;
356        /**
357         *  Insert the result of the parse operation as the immediately preceding
358         * sibling of the context node. For this action to work the context
359         * node's parent must be an <code>Element</code> or a
360         * <code>DocumentFragment</code>.
361         */
362        public static final short ACTION_INSERT_BEFORE      = 3;
363        /**
364         *  Insert the result of the parse operation as the immediately following
365         * sibling of the context node. For this action to work the context
366         * node's parent must be an <code>Element</code> or a
367         * <code>DocumentFragment</code>.
368         */
369        public static final short ACTION_INSERT_AFTER       = 4;
370        /**
371         *  Replace the context node with the result of the parse operation. For
372         * this action to work, the context node must have a parent, and the
373         * parent must be an <code>Element</code> or a
374         * <code>DocumentFragment</code>.
375         */
376        public static final short ACTION_REPLACE            = 5;
377    
378        /**
379         *  Parse an XML fragment from a resource identified by a
380         * <code>LSInput</code> and insert the content into an existing document
381         * at the position specified with the <code>context</code> and
382         * <code>action</code> arguments. When parsing the input stream, the
383         * context node (or its parent, depending on where the result will be
384         * inserted) is used for resolving unbound namespace prefixes. The
385         * context node's <code>ownerDocument</code> node (or the node itself if
386         * the node of type <code>DOCUMENT_NODE</code>) is used to resolve
387         * default attributes and entity references.
388         * <br> As the new data is inserted into the document, at least one
389         * mutation event is fired per new immediate child or sibling of the
390         * context node.
391         * <br> If the context node is a <code>Document</code> node and the action
392         * is <code>ACTION_REPLACE_CHILDREN</code>, then the document that is
393         * passed as the context node will be changed such that its
394         * <code>xmlEncoding</code>, <code>documentURI</code>,
395         * <code>xmlVersion</code>, <code>inputEncoding</code>,
396         * <code>xmlStandalone</code>, and all other such attributes are set to
397         * what they would be set to if the input source was parsed using
398         * <code>LSParser.parse()</code>.
399         * <br> This method is always synchronous, even if the
400         * <code>LSParser</code> is asynchronous (<code>LSParser.async</code> is
401         * <code>true</code>).
402         * <br> If an error occurs while parsing, the caller is notified through
403         * the <code>ErrorHandler</code> instance associated with the "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'>
404         * error-handler</a>" parameter of the <code>DOMConfiguration</code>.
405         * <br> When calling <code>parseWithContext</code>, the values of the
406         * following configuration parameters will be ignored and their default
407         * values will always be used instead: "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate'>
408         * validate</a>", "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate-if-schema'>
409         * validate-if-schema</a>", and "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-element-content-whitespace'>
410         * element-content-whitespace</a>". Other parameters will be treated normally, and the parser is expected
411         * to call the <code>LSParserFilter</code> just as if a whole document
412         * was parsed.
413         * @param input  The <code>LSInput</code> from which the source document
414         *   is to be read. The source document must be an XML fragment, i.e.
415         *   anything except a complete XML document (except in the case where
416         *   the context node of type <code>DOCUMENT_NODE</code>, and the action
417         *   is <code>ACTION_REPLACE_CHILDREN</code>), a DOCTYPE (internal
418         *   subset), entity declaration(s), notation declaration(s), or XML or
419         *   text declaration(s).
420         * @param contextArg  The node that is used as the context for the data
421         *   that is being parsed. This node must be a <code>Document</code>
422         *   node, a <code>DocumentFragment</code> node, or a node of a type
423         *   that is allowed as a child of an <code>Element</code> node, e.g. it
424         *   cannot be an <code>Attribute</code> node.
425         * @param action  This parameter describes which action should be taken
426         *   between the new set of nodes being inserted and the existing
427         *   children of the context node. The set of possible actions is
428         *   defined in <code>ACTION_TYPES</code> above.
429         * @return  Return the node that is the result of the parse operation. If
430         *   the result is more than one top-level node, the first one is
431         *   returned.
432         * @exception DOMException
433         *   HIERARCHY_REQUEST_ERR: Raised if the content cannot replace, be
434         *   inserted before, after, or as a child of the context node (see also
435         *   <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>]
436         *   ).
437         *   <br> NOT_SUPPORTED_ERR: Raised if the <code>LSParser</code> doesn't
438         *   support this method, or if the context node is of type
439         *   <code>Document</code> and the DOM implementation doesn't support
440         *   the replacement of the <code>DocumentType</code> child or
441         *   <code>Element</code> child.
442         *   <br> NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is a
443         *   read only node and the content is being appended to its child list,
444         *   or if the parent node of the context node is read only node and the
445         *   content is being inserted in its child list.
446         *   <br> INVALID_STATE_ERR: Raised if the <code>LSParser.busy</code>
447         *   attribute is <code>true</code>.
448         * @exception LSException
449         *    PARSE_ERR: Raised if the <code>LSParser</code> was unable to load
450         *   the XML fragment. DOM applications should attach a
451         *   <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'>
452         *   error-handler</a>" if they wish to get details on the error.
453         */
454        public Node parseWithContext(LSInput input,
455                                     Node contextArg,
456                                     short action)
457                                     throws DOMException, LSException;
458    
459        /**
460         *  Abort the loading of the document that is currently being loaded by
461         * the <code>LSParser</code>. If the <code>LSParser</code> is currently
462         * not busy, a call to this method does nothing.
463         */
464        public void abort();
465    
466    }