lsparser.java

gcc的组建

     * </dl></dd>
     * <dt><code>"validate"</code></dt>
     * <dd> See the definition of 
     * <code>DOMConfiguration</code> for a description of this parameter. 
     * Unlike in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
     * , the processing of the internal subset is always accomplished, even 
     * if this parameter is set to <code>false</code>. </dd>
     * <dt>
     * <code>"validate-if-schema"</code></dt>
     * <dd> See the definition of 
     * <code>DOMConfiguration</code> for a description of this parameter. 
     * Unlike in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
     * , the processing of the internal subset is always accomplished, even 
     * if this parameter is set to <code>false</code>. </dd>
     * <dt>
     * <code>"well-formed"</code></dt>
     * <dd> See the definition of 
     * <code>DOMConfiguration</code> for a description of this parameter. 
     * Unlike in [<a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>DOM Level 3 Core</a>]
     * , this parameter cannot be set to <code>false</code>. </dd>
     * </dl>
     */
    public DOMConfiguration getDomConfig();

    /**
     *  When a filter is provided, the implementation will call out to the 
     * filter as it is constructing the DOM tree structure. The filter can 
     * choose to remove elements from the document being constructed, or to 
     * terminate the parsing early. 
     * <br> The filter is invoked after the operations requested by the 
     * <code>DOMConfiguration</code> parameters have been applied. For 
     * example, if "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate'>
     * validate</a>" is set to <code>true</code>, the validation is done before invoking the 
     * filter. 
     */
    public LSParserFilter getFilter();
    /**
     *  When a filter is provided, the implementation will call out to the 
     * filter as it is constructing the DOM tree structure. The filter can 
     * choose to remove elements from the document being constructed, or to 
     * terminate the parsing early. 
     * <br> The filter is invoked after the operations requested by the 
     * <code>DOMConfiguration</code> parameters have been applied. For 
     * example, if "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate'>
     * validate</a>" is set to <code>true</code>, the validation is done before invoking the 
     * filter. 
     */
    public void setFilter(LSParserFilter filter);

    /**
     *  <code>true</code> if the <code>LSParser</code> is asynchronous, 
     * <code>false</code> if it is synchronous. 
     */
    public boolean getAsync();

    /**
     *  <code>true</code> if the <code>LSParser</code> is currently busy 
     * loading a document, otherwise <code>false</code>. 
     */
    public boolean getBusy();

    /**
     * Parse an XML document from a resource identified by a 
     * <code>LSInput</code>.
     * @param input  The <code>LSInput</code> from which the source of the 
     *   document is to be read. 
     * @return  If the <code>LSParser</code> is a synchronous 
     *   <code>LSParser</code>, the newly created and populated 
     *   <code>Document</code> is returned. If the <code>LSParser</code> is 
     *   asynchronous, <code>null</code> is returned since the document 
     *   object may not yet be constructed when this method returns. 
     * @exception DOMException
     *    INVALID_STATE_ERR: Raised if the <code>LSParser</code>'s 
     *   <code>LSParser.busy</code> attribute is <code>true</code>. 
     * @exception LSException
     *    PARSE_ERR: Raised if the <code>LSParser</code> was unable to load 
     *   the XML document. DOM applications should attach a 
     *   <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'>
     *   error-handler</a>" if they wish to get details on the error. 
     */
    public Document parse(LSInput input)
                          throws DOMException, LSException;

    /**
     *  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 
     * contains a fragment identifier (see section 4.1 in [<a href='http://www.ietf.org/rfc/rfc2396.txt'>IETF RFC 2396</a>]), the 
     * behavior is not defined by this specification, future versions of 
     * this specification may define the behavior. 
     * @param uri The location of the XML document to be read.
     * @return  If the <code>LSParser</code> is a synchronous 
     *   <code>LSParser</code>, the newly created and populated 
     *   <code>Document</code> is returned, or <code>null</code> if an error 
     *   occured. If the <code>LSParser</code> is asynchronous, 
     *   <code>null</code> is returned since the document object may not yet 
     *   be constructed when this method returns. 
     * @exception DOMException
     *    INVALID_STATE_ERR: Raised if the <code>LSParser.busy</code> 
     *   attribute is <code>true</code>. 
     * @exception LSException
     *    PARSE_ERR: Raised if the <code>LSParser</code> was unable to load 
     *   the XML document. DOM applications should attach a 
     *   <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'>
     *   error-handler</a>" if they wish to get details on the error. 
     */
    public Document parseURI(String uri)
                             throws DOMException, LSException;

    // ACTION_TYPES
    /**
     *  Append the result of the parse operation as children of the context 
     * node. For this action to work, the context node must be an 
     * <code>Element</code> or a <code>DocumentFragment</code>. 
     */
    public static final short ACTION_APPEND_AS_CHILDREN = 1;
    /**
     *  Replace all the children of the context node with the result of the 
     * parse operation. For this action to work, the context node must be an 
     * <code>Element</code>, a <code>Document</code>, or a 
     * <code>DocumentFragment</code>. 
     */
    public static final short ACTION_REPLACE_CHILDREN   = 2;
    /**
     *  Insert the result of the parse operation as the immediately preceding 
     * sibling of the context node. For this action to work the context 
     * node's parent must be an <code>Element</code> or a 
     * <code>DocumentFragment</code>. 
     */
    public static final short ACTION_INSERT_BEFORE      = 3;
    /**
     *  Insert the result of the parse operation as the immediately following 
     * sibling of the context node. For this action to work the context 
     * node's parent must be an <code>Element</code> or a 
     * <code>DocumentFragment</code>. 
     */
    public static final short ACTION_INSERT_AFTER       = 4;
    /**
     *  Replace the context node with the result of the parse operation. For 
     * this action to work, the context node must have a parent, and the 
     * parent must be an <code>Element</code> or a 
     * <code>DocumentFragment</code>. 
     */
    public static final short ACTION_REPLACE            = 5;

    /**
     *  Parse an XML fragment from a resource identified by a 
     * <code>LSInput</code> and insert the content into an existing document 
     * at the position specified with the <code>context</code> and 
     * <code>action</code> arguments. When parsing the input stream, the 
     * context node (or its parent, depending on where the result will be 
     * inserted) is used for resolving unbound namespace prefixes. The 
     * context node's <code>ownerDocument</code> node (or the node itself if 
     * the node of type <code>DOCUMENT_NODE</code>) is used to resolve 
     * default attributes and entity references. 
     * <br> As the new data is inserted into the document, at least one 
     * mutation event is fired per new immediate child or sibling of the 
     * context node. 
     * <br> If the context node is a <code>Document</code> node and the action 
     * is <code>ACTION_REPLACE_CHILDREN</code>, then the document that is 
     * passed as the context node will be changed such that its 
     * <code>xmlEncoding</code>, <code>documentURI</code>, 
     * <code>xmlVersion</code>, <code>inputEncoding</code>, 
     * <code>xmlStandalone</code>, and all other such attributes are set to 
     * what they would be set to if the input source was parsed using 
     * <code>LSParser.parse()</code>. 
     * <br> This method is always synchronous, even if the 
     * <code>LSParser</code> is asynchronous (<code>LSParser.async</code> is 
     * <code>true</code>). 
     * <br> If an error occurs while parsing, the caller is notified through 
     * the <code>ErrorHandler</code> instance associated with the "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'>
     * error-handler</a>" parameter of the <code>DOMConfiguration</code>. 
     * <br> When calling <code>parseWithContext</code>, the values of the 
     * following configuration parameters will be ignored and their default 
     * values will always be used instead: "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate'>
     * validate</a>", "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-validate-if-schema'>
     * validate-if-schema</a>", and "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-element-content-whitespace'>
     * element-content-whitespace</a>". Other parameters will be treated normally, and the parser is expected 
     * to call the <code>LSParserFilter</code> just as if a whole document 
     * was parsed. 
     * @param input  The <code>LSInput</code> from which the source document 
     *   is to be read. The source document must be an XML fragment, i.e. 
     *   anything except a complete XML document (except in the case where 
     *   the context node of type <code>DOCUMENT_NODE</code>, and the action 
     *   is <code>ACTION_REPLACE_CHILDREN</code>), a DOCTYPE (internal 
     *   subset), entity declaration(s), notation declaration(s), or XML or 
     *   text declaration(s). 
     * @param contextArg  The node that is used as the context for the data 
     *   that is being parsed. This node must be a <code>Document</code> 
     *   node, a <code>DocumentFragment</code> node, or a node of a type 
     *   that is allowed as a child of an <code>Element</code> node, e.g. it 
     *   cannot be an <code>Attribute</code> node. 
     * @param action  This parameter describes which action should be taken 
     *   between the new set of nodes being inserted and the existing 
     *   children of the context node. The set of possible actions is 
     *   defined in <code>ACTION_TYPES</code> above. 
     * @return  Return the node that is the result of the parse operation. If 
     *   the result is more than one top-level node, the first one is 
     *   returned. 
     * @exception DOMException
     *   HIERARCHY_REQUEST_ERR: Raised if the content cannot replace, be 
     *   inserted before, after, or as a child of the context node (see also 
     *   <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>]
     *   ).
     *   <br> NOT_SUPPORTED_ERR: Raised if the <code>LSParser</code> doesn't 
     *   support this method, or if the context node is of type 
     *   <code>Document</code> and the DOM implementation doesn't support 
     *   the replacement of the <code>DocumentType</code> child or 
     *   <code>Element</code> child. 
     *   <br> NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is a 
     *   read only node and the content is being appended to its child list, 
     *   or if the parent node of the context node is read only node and the 
     *   content is being inserted in its child list.
     *   <br> INVALID_STATE_ERR: Raised if the <code>LSParser.busy</code> 
     *   attribute is <code>true</code>. 
     * @exception LSException
     *    PARSE_ERR: Raised if the <code>LSParser</code> was unable to load 
     *   the XML fragment. DOM applications should attach a 
     *   <code>DOMErrorHandler</code> using the parameter "<a href='http://www.w3.org/TR/DOM-Level-3-Core/core.html#parameter-error-handler'>
     *   error-handler</a>" if they wish to get details on the error. 
     */
    public Node parseWithContext(LSInput input, 
                                 Node contextArg, 
                                 short action)
                                 throws DOMException, LSException;

    /**
     *  Abort the loading of the document that is currently being loaded by 
     * the <code>LSParser</code>. If the <code>LSParser</code> is currently 
     * not busy, a call to this method does nothing. 
     */
    public void abort();

}