org.w3c.dom.ls
Interface DOMBuilder


public interface DOMBuilder

DOM Level 3 WD Experimental: The DOM Level 3 specification is at the stage of Working Draft, which represents work in progress and thus may be updated, replaced, or obsoleted by other documents at any time. A interface to an object that is able to build a DOM tree from various input sources.

DOMBuilder provides an API for parsing XML documents and building the corresponding DOM document tree. A DOMBuilder instance is obtained by invoking the DOMImplementationLS.createDOMBuilder method.

As specified in [DOM Level 3 Core] , when a document is first made available via the DOMBuilder:

Asynchronous DOMBuilder objects are expected to also implement the events::EventTarget interface so that event listeners can be registered on asynchronous DOMBuilder objects.

Events supported by asynchronous DOMBuilder objects are:

Note: All events defined in this specification use the namespace URI "http://www.w3.org/2002/DOMLS". ED: State that a parse operation may fail due to security reasons (DOM LS telecon 20021202).

See also the Document Object Model (DOM) Level 3 Load and Save Specification.


Field Summary
static short ACTION_APPEND_AS_CHILDREN
          Append the result of the parse operation as children of the context node.
static short ACTION_INSERT_AFTER
          Insert the result of the parse operation as the immediately following sibling of the context node.
static short ACTION_INSERT_BEFORE
          Insert the result of the parse operation as the immediately preceeding sibling of the context node.
static short ACTION_REPLACE
          Replace the context node with the result of the parse operation.
static short ACTION_REPLACE_CHILDREN
          Replace all the children of the context node with the result of the parse operation.
 
Method Summary
 void abort()
          Abort the loading of the document that is currently being loaded by the DOMBuilder.
 boolean getAsync()
          True if the DOMBuider is asynchronous, false if it is synchronous.
 boolean getBusy()
          True if the DOMBuider is currently busy loading a document, otherwise false.
 org.apache.xerces.dom3.DOMConfiguration getConfig()
          The configuration used when a document is loaded.
 DOMBuilderFilter getFilter()
          When a filter is provided, the implementation will call out to the filter as it is constructing the DOM tree structure.
 org.w3c.dom.Document parse(DOMInputSource is)
          Parse an XML document from a resource identified by a DOMInputSource.
 org.w3c.dom.Document parseURI(java.lang.String uri)
          Parse an XML document from a location identified by a URI reference [IETF RFC 2396].
 org.w3c.dom.Node parseWithContext(DOMInputSource is, org.w3c.dom.Node cnode, short action)
          Parse an XML fragment from a resource identified by a DOMInputSource and insert the content into an existing document at the position specified with the contextNode and action arguments.
 void setFilter(DOMBuilderFilter filter)
          When a filter is provided, the implementation will call out to the filter as it is constructing the DOM tree structure.
 

Field Detail

ACTION_APPEND_AS_CHILDREN

public static final short ACTION_APPEND_AS_CHILDREN
Append the result of the parse operation as children of the context node. For this action to work, the context node must be an Element or a DocumentFragment.

See Also:
Constant Field Values

ACTION_REPLACE_CHILDREN

public static final short ACTION_REPLACE_CHILDREN
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 Element or a DocumentFragment.

See Also:
Constant Field Values

ACTION_INSERT_BEFORE

public static final short ACTION_INSERT_BEFORE
Insert the result of the parse operation as the immediately preceeding sibling of the context node. For this action to work the context node's parent must be an Element or a DocumentFragment.

See Also:
Constant Field Values

ACTION_INSERT_AFTER

public static final short ACTION_INSERT_AFTER
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 Element or a DocumentFragment.

See Also:
Constant Field Values

ACTION_REPLACE

public static final short ACTION_REPLACE
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 Element or a DocumentFragment.

See Also:
Constant Field Values
Method Detail

getConfig

public org.apache.xerces.dom3.DOMConfiguration getConfig()
The configuration used when a document is loaded. The values of parameters used to load a document are not passed automatically to the DOMConfiguration object used by the Document nodes. The DOM application is responsible for passing the parameters values from the DOMConfiguration object referenced from the DOMBuilder to the DOMConfiguration object referenced from the Document node.
In addition to the boolean parameters and parameters recognized in the Core module, the DOMConfiguration objects for DOMBuider adds the following boolean parameters:
"entity-resolver"
[required] A DOMEntityResolver object. If this parameter has been specified, each time a reference to an external entity is encountered the implementation will pass the public and system IDs to the entity resolver, which can then specify the actual source of the entity. If this parameter is not set, the resolution of entities in the document is implementation dependent.

Note: When the features "LS-Load" or "LS-Save" are supported, this parameter may also be supported by the DOMConfiguration object referenced from the Document node.

"certified"
true
[optional] Assume, when XML 1.1 is supported, that the input is certified (see section 2.13 in [XML 1.1]).
false
[required] (default) Don't assume that the input is certified (see section 2.13 in [XML 1.1]).
"charset-overrides-xml-encoding"
true
[required] (default) If a higher level protocol such as HTTP [IETF RFC 2616] provides an indication of the character encoding of the input stream being processed, that will override any encoding specified in the XML declaration or the Text declaration (see also [XML 1.0] 4.3.3 "Character Encoding in Entities"). Explicitly setting an encoding in the DOMInputSource overrides encodings from the protocol.
false
[required] Any character set encoding information from higher level protocols is ignored by the parser.
"supported-mediatypes-only"
true
[optional] Check that the media type of the parsed resource is a supported media type. If an unsupported media type is encountered, a fatal error of type "unsupported-media-type" will be raised. The media types defined in [IETF RFC 3023] must always be accepted.
false
[required] (default) Accept any media type.
"unknown-characters"
true
[required] (default) If, while verifying full normalization when [XML 1.1] is supported, a processor encounters characters for which it cannot determine the normalization properties, then the processor will ignore any possible denormalizations caused by these characters. This parameter is ignored [XML 1.0].
false
[optional] Report an fatal error if a character is encountered for which the processor can not determine the normalization properties.


getFilter

public DOMBuilderFilter 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.
The filter is invoked after the operations requested by the DOMConfiguration parameters have been applied. For example, if "validate" is set to true, the validation is done before invoking the filter.


setFilter

public void setFilter(DOMBuilderFilter filter)
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.
The filter is invoked after the operations requested by the DOMConfiguration parameters have been applied. For example, if "validate" is set to true, the validation is done before invoking the filter.


getAsync

public boolean getAsync()
True if the DOMBuider is asynchronous, false if it is synchronous.


getBusy

public boolean getBusy()
True if the DOMBuider is currently busy loading a document, otherwise false.


parse

public org.w3c.dom.Document parse(DOMInputSource is)
                           throws org.w3c.dom.DOMException
Parse an XML document from a resource identified by a DOMInputSource.

Parameters:
is - The DOMInputSource from which the source of the document is to be read.
Returns:
If the DOMBuilder is a synchronous DOMBuilder, the newly created and populated Document is returned. If the DOMBuilder is asynchronous, null is returned since the document object may not yet be constructed when this method returns.
Throws:
org.w3c.dom.DOMException - INVALID_STATE_ERR: Raised if the DOMBuilder's DOMBuilder.busy attribute is true.

parseURI

public org.w3c.dom.Document parseURI(java.lang.String uri)
                              throws org.w3c.dom.DOMException
Parse an XML document from a location identified by a URI reference [IETF RFC 2396]. If the URI contains a fragment identifier (see section 4.1 in [IETF RFC 2396]), the behavior is not defined by this specification, future versions of this specification may define the behavior.

Parameters:
uri - The location of the XML document to be read.
Returns:
If the DOMBuilder is a synchronous DOMBuilder, the newly created and populated Document is returned. If the DOMBuilder is asynchronous, null is returned since the document object may not yet be constructed when this method returns.
Throws:
org.w3c.dom.DOMException - INVALID_STATE_ERR: Raised if the DOMBuilder's DOMBuilder.busy attribute is true.

parseWithContext

public org.w3c.dom.Node parseWithContext(DOMInputSource is,
                                         org.w3c.dom.Node cnode,
                                         short action)
                                  throws org.w3c.dom.DOMException
Parse an XML fragment from a resource identified by a DOMInputSource and insert the content into an existing document at the position specified with the contextNode and action arguments. When parsing the input stream, the context node is used for resolving unbound namespace prefixes. The context node's ownerDocument node is used to resolve default attributes and entity references.
As the new data is inserted into the document, at least one mutation event is fired per immediate child (or sibling) of context node.
If an error occurs while parsing, the caller is notified through the error handler.

Parameters:
is - The DOMInputSource 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, a DOCTYPE (internal subset), entity declaration(s), notation declaration(s), or XML or text declaration(s).
cnode - The node that is used as the context for the data that is being parsed. This node must be a Document node, a DocumentFragment node, or a node of a type that is allowed as a child of an Element node, e.g. it can not be an Attribute node.
action - This parameter describes which action should be taken between the new set of node being inserted and the existing children of the context node. The set of possible actions is defined above.
Returns:
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.
Throws:
org.w3c.dom.DOMException - NOT_SUPPORTED_ERR: Raised if the DOMBuilder doesn't support this method.
NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is readonly.
INVALID_STATE_ERR: Raised if the DOMBuilder's DOMBuilder.busy attribute is true.

abort

public void abort()
Abort the loading of the document that is currently being loaded by the DOMBuilder. If the DOMBuilder is currently not busy, a call to this method does nothing.



Copyright ? 1999-2003 Apache XML Project. All Rights Reserved.