DOM Level 3 API: Interface DOMBuilder

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.xerces.dom3.ls
Interface DOMBuilder

All Known Subinterfaces:: DOMASBuilder

public interface DOMBuilder

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 from the DOMImplementationLS interface by invoking its createDOMBuildermethod.

As specified in , when a document is first made available via the DOMBuilder: there is only one Text node for each block of text. The Text nodes are into "normal" form: only structure (e.g., elements, comments, processing instructions, CDATA sections, and entity references) separates Text nodes, i.e., there are neither adjacent Text nodes nor empty Text nodes. it is expected that the value and nodeValue attributes of an Attr node initially return the XML 1.0 normalized value. However, if the features validate-if-schema and datatype-normalization are set to true, depending on the attribute normalization used, the attribute values may differ from the ones obtained by the XML 1.0 attribute normalization. If the feature datatype-normalization is not set to true, the XML 1.0 attribute normalization is garantee to occur, and if attributes list does not contain namespace declarations, the attributes attribute on Element node represents the property [attributes] defined in . XML Schemas does not modified the XML attribute normalization but represents their normalized value in an other information item property: [schema normalized value]XML Schema normalization only occurs if datatype-normalization is set to true.

The Document Object Model Level 3 Load and Save does not provide a way to disable the namespace resolution: Namespaces are always taken into account during loading and saving operations.

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

Events supported by asynchronous DOMBuilder are: ls-load: The document that's being loaded is completely parsed, see the definition of LSLoadEventls-progress: Progress notification, see the definition of LSProgressEvent

DOMBuilders have a number of named features that can be queried or set. The name of DOMBuilder features must be valid XML names. Implementation specific features (extensions) should choose a implementation specific prefix to avoid name collisions.

Even if all features must be recognized by all implementations, being able to set a state (true or false) is not always required. The following list of recognized features indicates the definitions of each feature state, if setting the state to true or false must be supported or is optional and, which state is the default one:

"namespace-declarations"

true: [required] (default) include the namespace declaration attributes, specified or defaulted from the schema or the DTD, in the DOM document. See also the section Declaring Namespaces in .
false: [optional] discard all namespace declaration attributes. The Namespace prefixes will be retained even if this feature is set to false.

"validation"

true: [ optional] report validation errors (setting true also will force the external-general-entities and external-parameter-entities features to be true .) Also note that the validate-if-schema feature will alter the validation behavior when this feature is set true.
false: [required] (default) do not report validation errors.

"external-parameter-entities"

true: [required] ( default)load external parameter entities.
false: [optional]do not load external parameter entities.
default value: true

"external-general-entities"

true: [required] ( default) include all external general (text) entities.
false: [ optional]do not include external general entities.

"external-dtd-subset"

true: [required] (default) load the external dtd and also all external parameter entities.
false: [optional] do not load the dtd nor external parameter entities.

"validate-if-schema"

true: [optional] when both this feature and validation are true, enable validation only if the document being processed has a schema (i.e. XML schema, DTD, any other type of schema, note that this is unrelated to the abstract schema specification). Documents without schemas are parsed without validation.
false: [required] (default) the validation feature alone controls whether the document is checked for validity. Documents without a schemas are not valid.

"validate-against-dtd"

true: [optional] Prefere validation against the DTD over any other schema referenced in the XML file.
false: [required] (default) Let the parser decide what to validate against if there are references to multiple types of schemas.

"datatype-normalization"

true: [required] Let the (non-DTD) validation process do its datatype normalization that is defined in the used schema language. We should define "datatype normalization".
false: [required] (default) Disable datatype normalization. The XML 1.0 attribute value normalization is garantee to occur in that case.

"create-entity-ref-nodes"

true: [required] (default) Create EntityReference nodes in the DOM document. It will also set create-entity-nodes to be true.
false: [optional] omit all EntityReference nodes from the DOM document, putting the entity expansions directly in their place. Text nodes are into "normal" form. EntityReference nodes to non-defined entities will still be created in the DOM document.

"create-entity-nodes"

true: [required] (default) Create Entity nodes in the DOM document.
false: [optional] Omit all entity nodes from the DOM document. It will also set create-entity-ref-nodes to false.

"whitespace-in-element-content"

true: [required] ( default) Include white space characters appearing within element content (see 2.10 "White Space Handling").
false: [optional] Omit white space characters appearing within element content. Note that white space characters within element content will only be omitted if it can be identified as such, and not all parsers may be able to do so (see 2.10 "White Space Handling").

"create-cdata-nodes"

true: [required] (default) Create CDATASection nodes in response to the appearance of CDATA sections in the XML document.
false: [optional] Do not create CDATASection nodes in the DOM document. The content of any CDATA sections in the XML document appears in the DOM as if it had been normal (non-CDATA) content. If a CDATA section is adjacent to other content, the combined content appears in a single Text node, i.e. the Text nodes are into "normal" form.

"comments"

true: [required] (default) Include XML comments in the DOM document.
false: [required] Discard XML comments, do not create Comment nodes in the DOM Document resulting from a parse.

"charset-overrides-xml-encoding"

true: [required] (default) If a higher level protocol such as HTTP 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 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.

"load-as-infoset"

true: [optional] Load the document and store only the information defined in the XML Information Set . This will force the following features to false: namespace-declarations, validate-if-schema, create-entity-ref-nodes, create-entity-nodes, create-cdata-nodes. This will force the following features to true: datatype-normalization, whitespace-in-element-content, comments, charset-overrides-xml-encoding. Other features are not changed unless explicity specified in the description of the features. Note that querying this feature with getFeature will return true only if the individual features specified above are appropriately set.
false: Setting load-as-infoset to false has no effect.

"supported-mediatypes-only"

true: [optional] Check that the media type of the parsed resource is a supported media type and call the error handler if an unsupported media type is encountered. The media types defined in must be accepted.
false: [required] ( default) Don't check the media type, accept any type of data.

Field Summary

static short ACTION_APPEND
          Append the result of parsing the input source to the context node.

static short ACTION_INSERT_AFTER
          Insert the result of parsing the input source after the context node.

static short ACTION_INSERT_BEFORE
          Insert the result of parsing the input source before the context node.

static short ACTION_REPLACE
          Replace the context node with the result of parsing the input source.

Method Summary

boolean canSetFeature(java.lang.String name, boolean state)
          Query whether setting a feature to a specific value is supported.

DOMEntityResolver getEntityResolver()
          If a DOMEntityResolver has been specified, each time a reference to an external entity is encountered the DOMBuilder will pass the public and system IDs to the entity resolver, which can then specify the actual source of the entity.

DOMErrorHandler getErrorHandler()
          In the event that an error is encountered in the XML document being parsed, the DOMDcoumentBuilder will call back to the errorHandler with the error information.

boolean getFeature(java.lang.String name)
          Look up the value of a feature.

DOMBuilderFilter getFilter()
          When the application provides a filter, the parser will call out to the filter at the completion of the construction of each Element node.

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

org.w3c.dom.Document parseURI(java.lang.String uri)
          Parse an XML document from a location identified by an URI reference .

void parseWithContext(DOMInputSource is, org.w3c.dom.Node cnode, short action)
          Parse an XML document or fragment from a resource identified by an DOMInputSource and insert the content into an existing document at the position epcified with the contextNode and action arguments.

void setEntityResolver(DOMEntityResolver entityResolver)
          If a DOMEntityResolver has been specified, each time a reference to an external entity is encountered the DOMBuilder will pass the public and system IDs to the entity resolver, which can then specify the actual source of the entity.

void setErrorHandler(DOMErrorHandler errorHandler)
          In the event that an error is encountered in the XML document being parsed, the DOMDcoumentBuilder will call back to the errorHandler with the error information.

void setFeature(java.lang.String name, boolean state)
          Set the state of a feature.

void setFilter(DOMBuilderFilter filter)
          When the application provides a filter, the parser will call out to the filter at the completion of the construction of each Element node.

Field Detail

ACTION_REPLACE

public static final short ACTION_REPLACE

Replace the context node with the result of parsing the input source. For this action to work the context node must be an Element, Text, CDATASection, Comment, ProcessingInstruction, or EntityReference node.

ACTION_APPEND

public static final short ACTION_APPEND

Append the result of parsing the input source to the context node. For this action to work, the context node must be an Element.

ACTION_INSERT_AFTER

public static final short ACTION_INSERT_AFTER

Insert the result of parsing the input source after the context node. For this action to work the context nodes parent must be an Element.

ACTION_INSERT_BEFORE

public static final short ACTION_INSERT_BEFORE

Insert the result of parsing the input source before the context node. For this action to work the context nodes parent must be an Element.

Method Detail

getEntityResolver

public DOMEntityResolver getEntityResolver()

If a DOMEntityResolver has been specified, each time a reference to an external entity is encountered the DOMBuilder will pass the public and system IDs to the entity resolver, which can then specify the actual source of the entity.

setEntityResolver

public void setEntityResolver(DOMEntityResolver entityResolver)

getErrorHandler

public DOMErrorHandler getErrorHandler()

In the event that an error is encountered in the XML document being parsed, the DOMDcoumentBuilder will call back to the errorHandler with the error information. When the document loading process calls the error handler the node closest to where the error occured is passed to the error handler if the implementation, if the implementation is unable to pass the node where the error occures the document Node is passed to the error handler. Mutations to the document from within an error handler will result in implementation dependent behavour.

setErrorHandler

public void setErrorHandler(DOMErrorHandler errorHandler)

getFilter

public DOMBuilderFilter getFilter()

When the application provides a filter, the parser will call out to the filter at the completion of the construction of each Element node. The filter implementation can choose to remove the element from the document being constructed (unless the element is the document element) or to terminate the parse early. If the document is being validated when it's loaded the validation happens before the filter is called.

setFilter

public void setFilter(DOMBuilderFilter filter)

setFeature

public void setFeature(java.lang.String name,
                       boolean state)
                throws org.w3c.dom.DOMException

Set the state of a feature.
The feature name has the same form as a DOM hasFeature string.
It is possible for a DOMBuilder to recognize a feature name but to be unable to set its value.

Parameters:: name - The feature name.; state - The requested state of the feature (true or false).
Throws:: org.w3c.dom.DOMException - Raise a NOT_SUPPORTED_ERR exception when the DOMBuilder recognizes the feature name but cannot set the requested value.
Raise a NOT_FOUND_ERR When the DOMBuilder does not recognize the feature name.

canSetFeature

public boolean canSetFeature(java.lang.String name,
                             boolean state)

Query whether setting a feature to a specific value is supported.
The feature name has the same form as a DOM hasFeature string.

Parameters:: name - The feature name, which is a DOM has-feature style string.; state - The requested state of the feature (true or false).
Returns:: true if the feature could be successfully set to the specified value, or false if the feature is not recognized or the requested value is not supported. The value of the feature itself is not changed.

getFeature

public boolean getFeature(java.lang.String name)
                   throws org.w3c.dom.DOMException

Look up the value of a feature.
The feature name has the same form as a DOM hasFeature string

Parameters:: name - The feature name, which is a string with DOM has-feature syntax.
Returns:: The current state of the feature (true or false).
Throws:: org.w3c.dom.DOMException - Raise a NOT_FOUND_ERR When the DOMBuilder does not recognize the feature name.

parseURI

public org.w3c.dom.Document parseURI(java.lang.String uri)
                              throws java.lang.Exception

Parse an XML document from a location identified by an URI reference . If the URI contains a fragment identifier (see section 4.1 in ), the behavior is not defined by this specification.

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 then null is returned since the document object is not yet parsed when this method returns.
Throws:: DOMSystemException - Exceptions raised by parseURI originate with the installed ErrorHandler, and thus depend on the implementation of the DOMErrorHandler interfaces. The default error handlers will raise a DOMSystemException if any form I/O or other system error occurs during the parse, but application defined error handlers are not required to do so.

parse

public org.w3c.dom.Document parse(DOMInputSource is)
                           throws java.lang.Exception

Parse an XML document from a resource identified by an DOMInputSource.

Parameters:: is - The DOMInputSource from which the source 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 then null is returned since the document object is not yet parsed when this method returns.
Throws:: DOMSystemException - Exceptions raised by parse originate with the installed ErrorHandler, and thus depend on the implementation of the DOMErrorHandler interfaces. The default ErrorHandlers will raise a DOMSystemException if any form I/O or other system error occurs during the parse, but application defined ErrorHandlers are not required to do so.

parseWithContext

public void parseWithContext(DOMInputSource is,
                             org.w3c.dom.Node cnode,
                             short action)
                      throws org.w3c.dom.DOMException

Parse an XML document or fragment from a resource identified by an DOMInputSource and insert the content into an existing document at the position epcified with the contextNode and action arguments. When parsing the input stream the context node is used for resolving unbound namespace prefixes.

Parameters:: is - The DOMInputSource from which the source document is to be read.; cnode - The Node that is used as the context for the data that is being parsed.; 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.
Throws:: org.w3c.dom.DOMException - HIERARCHY_REQUEST_ERR: Thrown if this action results in an invalid hierarchy (i.e. a Document with more than one document element).