Source for org.w3c.dom.ls.LSParser

   1: /*
   2:  * Copyright (c) 2004 World Wide Web Consortium,
   3:  *
   4:  * (Massachusetts Institute of Technology, European Research Consortium for
   5:  * Informatics and Mathematics, Keio University). All Rights Reserved. This
   6:  * work is distributed under the W3C(r) Software License [1] in the hope that
   7:  * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
   8:  * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   9:  *
  10:  * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
  11:  */
  12: 
  13: package org.w3c.dom.ls;
  14: 
  15: import org.w3c.dom.Document;
  16: import org.w3c.dom.DOMConfiguration;
  17: import org.w3c.dom.Node;
  18: import org.w3c.dom.DOMException;
  19: 
  20: /**
  21:  *  An interface to an object that is able to build, or augment, a DOM tree
  22:  * from various input sources.
  23:  * <p> <code>LSParser</code> provides an API for parsing XML and building the
  24:  * corresponding DOM document structure. A <code>LSParser</code> instance
  25:  * can be obtained by invoking the
  26:  * <code>DOMImplementationLS.createLSParser()</code> method.
  27:  * <p> As specified in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
  28:  * , when a document is first made available via the LSParser:
  29:  * <ul>
  30:  * <li> there will
  31:  * never be two adjacent nodes of type NODE_TEXT, and there will never be
  32:  * empty text nodes.
  33:  * </li>
  34:  * <li> it is expected that the <code>value</code> and
  35:  * <code>nodeValue</code> attributes of an <code>Attr</code> node initially
  36:  * return the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#AVNormalize'>XML 1.0
  37:  * normalized value</a>. However, if the parameters "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate-if-schema'>
  38:  * validate-if-schema</a>" and "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-datatype-normalization'>
  39:  * datatype-normalization</a>" are set to <code>true</code>, depending on the attribute normalization
  40:  * used, the attribute values may differ from the ones obtained by the XML
  41:  * 1.0 attribute normalization. If the parameters "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-datatype-normalization'>
  42:  * datatype-normalization</a>" is set to <code>false</code>, the XML 1.0 attribute normalization is
  43:  * guaranteed to occur, and if the attributes list does not contain
  44:  * namespace declarations, the <code>attributes</code> attribute on
  45:  * <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>]
  46:  * .
  47:  * </li>
  48:  * </ul>
  49:  * <p> Asynchronous <code>LSParser</code> objects are expected to also
  50:  * implement the <code>events::EventTarget</code> interface so that event
  51:  * listeners can be registered on asynchronous <code>LSParser</code>
  52:  * objects.
  53:  * <p> Events supported by asynchronous <code>LSParser</code> objects are:
  54:  * <dl>
  55:  * <dt>load</dt>
  56:  * <dd>
  57:  *  The <code>LSParser</code> finishes to load the document. See also the
  58:  * definition of the <code>LSLoadEvent</code> interface. </dd>
  59:  * <dt>progress</dt>
  60:  * <dd> The
  61:  * <code>LSParser</code> signals progress as data is parsed.  This
  62:  * specification does not attempt to define exactly when progress events
  63:  * should be dispatched. That is intentionally left as
  64:  * implementation-dependent. Here is one example of how an application might
  65:  * dispatch progress events: Once the parser starts receiving data, a
  66:  * progress event is dispatched to indicate that the parsing starts. From
  67:  * there on, a progress event is dispatched for every 4096 bytes of data
  68:  * that is received and processed. This is only one example, though, and
  69:  * implementations can choose to dispatch progress events at any time while
  70:  * parsing, or not dispatch them at all.  See also the definition of the
  71:  * <code>LSProgressEvent</code> interface. </dd>
  72:  * </dl>
  73:  * <p ><b>Note:</b>  All events defined in this specification use the
  74:  * namespace URI <code>"http://www.w3.org/2002/DOMLS"</code>.
  75:  * <p> While parsing an input source, errors are reported to the application
  76:  * 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'>
  77:  * error-handler</a>" parameter). This specification does in no way try to define all possible
  78:  * errors that can occur while parsing XML, or any other markup, but some
  79:  * common error cases are defined. The types (<code>DOMError.type</code>) of
  80:  * errors and warnings defined by this specification are:
  81:  * <dl>
  82:  * <dt>
  83:  * <code>"check-character-normalization-failure" [error]</code> </dt>
  84:  * <dd> Raised if
  85:  * the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-check-character-normalization'>
  86:  * check-character-normalization</a>" is set to true and a string is encountered that fails normalization
  87:  * checking. </dd>
  88:  * <dt><code>"doctype-not-allowed" [fatal]</code></dt>
  89:  * <dd> Raised if the
  90:  * configuration parameter "disallow-doctype" is set to <code>true</code>
  91:  * and a doctype is encountered. </dd>
  92:  * <dt><code>"no-input-specified" [fatal]</code></dt>
  93:  * <dd>
  94:  * Raised when loading a document and no input is specified in the
  95:  * <code>LSInput</code> object. </dd>
  96:  * <dt>
  97:  * <code>"pi-base-uri-not-preserved" [warning]</code></dt>
  98:  * <dd> Raised if a processing
  99:  * 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: }