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