|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
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 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 guaranteed 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 modify 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.
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 are: load: The
document that's being loaded is completely parsed, see the definition of
LSLoadEventprogress: Progress notification, see the
definition of LSProgressEvent All events defined in this
specification use the namespace URI
"http://www.w3.org/2002/DOMLS".
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:
"canonical-form"Document.setNormalizationFeature in . "cdata-sections"Document.setNormalizationFeature in . "certified"truefalse"charset-overrides-xml-encoding"trueDOMInputSource
overrides encodings from the protocol. false"comments"Document.setNormalizationFeature in . "datatype-normalization"Document.setNormalizationFeature in . "entities"Document.setNormalizationFeature in . "infoset"Document.setNormalizationFeature in . Setting this feature
to true will also force the feature namespaces
to true. "namespaces"truefalse"namespace-declarations"Document.setNormalizationFeature in . "supported-mediatypes-only"truefalse"unknown-characters"truefalse"validate"Document.setNormalizationFeature in . "validate-if-schema"Document.setNormalizationFeature in . "whitespace-in-element-content"Document.setNormalizationFeature in . 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 input source as children of 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. |
org.apache.xerces.dom3.DOMErrorHandler |
getErrorHandler()
In the event that an error is encountered in the XML document being parsed, the DOMDocumentBuilder 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. |
Document |
parse(DOMInputSource is)
Parse an XML document from a resource identified by a DOMInputSource. |
Document |
parseURI(java.lang.String uri)
Parse an XML document from a location identified by a URI reference . |
void |
parseWithContext(DOMInputSource is,
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 |
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(org.apache.xerces.dom3.DOMErrorHandler errorHandler)
In the event that an error is encountered in the XML document being parsed, the DOMDocumentBuilder 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 |
public static final short ACTION_REPLACE
Element, Text,
CDATASection, Comment,
ProcessingInstruction, or EntityReference
node.public static final short ACTION_APPEND_AS_CHILDREN
Element or a DocumentFragment.public static final short ACTION_INSERT_AFTER
Element.public static final short ACTION_INSERT_BEFORE
Element.| Method Detail |
public DOMEntityResolver getEntityResolver()
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.
null, the resolution of entities
in the document is implementation dependent.public void setEntityResolver(DOMEntityResolver entityResolver)
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.
null, the resolution of entities
in the document is implementation dependent.public org.apache.xerces.dom3.DOMErrorHandler getErrorHandler()
DOMDocumentBuilder 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 is unable to pass the node where the error occures the
document Node is passed to the error handler. In addition to passing
the Node closest to to where the error occured, the implementation
should also pass any other valuable information to the error handler,
such as file name, line number, and so on. Mutations to the document
from within an error handler will result in implementation dependent
behaviour.public void setErrorHandler(org.apache.xerces.dom3.DOMErrorHandler errorHandler)
DOMDocumentBuilder 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 is unable to pass the node where the error occures the
document Node is passed to the error handler. In addition to passing
the Node closest to to where the error occured, the implementation
should also pass any other valuable information to the error handler,
such as file name, line number, and so on. Mutations to the document
from within an error handler will result in implementation dependent
behaviour.public DOMBuilderFilter getFilter()
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.public void setFilter(DOMBuilderFilter filter)
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.
public void setFeature(java.lang.String name,
boolean state)
throws DOMException
DOMBuilder to recognize a feature
name but to be unable to set its value.name - The feature name.state - The requested state of the feature (true or
false).DOMException - NOT_SUPPORTED_ERR: Raised when the DOMBuilder recognizes
the feature name but cannot set the requested value.
DOMBuilder does not
recognize the feature name.
public boolean canSetFeature(java.lang.String name,
boolean state)
name - The feature name, which is a DOM has-feature style string.state - The requested state of the feature (true or
false).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.
public boolean getFeature(java.lang.String name)
throws DOMException
name - The feature name, which is a string with DOM has-feature
syntax.true or
false).DOMException - NOT_FOUND_ERR: Raised when the DOMBuilder does not
recognize the feature name.public Document parseURI(java.lang.String uri)
uri - The location of the XML document to be read.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.public Document parse(DOMInputSource is)
DOMInputSource.is - The DOMInputSource from which the source
document is to be read.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.
public void parseWithContext(DOMInputSource is,
Node cnode,
short action)
throws DOMException
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
Document node, attached to the context node, is used to
resolved default attributes and entity references.
is - The DOMInputSource from which the source
document is to be read. The source document must be an XML
fragment, i.e. anything except an XML Document, a DOCTYPE, entities
declarations, notations declarations, or XML or text declarations.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, 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.DOMException - NOT_SUPPORTED_ERR: Raised when the DOMBuilder doesn't
support this method.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||