|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 createDOMBuilder
method.
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 LSLoadEvent
ls-progress: Progress notification, see the
definition of LSProgressEvent
DOMBuilder
s 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
false
false
. "validation"
true
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
"external-parameter-entities"
true
false
true
"external-general-entities"
true
false
"external-dtd-subset"
true
false
"validate-if-schema"
true
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
"validate-against-dtd"
true
false
"datatype-normalization"
true
false
"create-entity-ref-nodes"
true
EntityReference
nodes in the DOM document. It will also set
create-entity-nodes
to be true
. false
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
Entity
nodes in
the DOM document. false
entity
nodes from the DOM document. It will also set
create-entity-ref-nodes
to false
. "whitespace-in-element-content"
true
false
"create-cdata-nodes"
true
CDATASection
nodes in response to the appearance of CDATA sections in the XML
document. false
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
false
Comment
nodes in the DOM Document
resulting from a parse. "charset-overrides-xml-encoding"
true
DOMInputSource
overrides encodings from the protocol. false
"load-as-infoset"
true
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
load-as-infoset
to false
has no effect. "supported-mediatypes-only"
true
false
See also the Document Object Model (DOM) Level 3 Abstract Schemas and Load and Save Specification.
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 |
public static final short ACTION_REPLACE
Element
, Text
, CDATASection
,
Comment
, ProcessingInstruction
, or
EntityReference
node.public static final short ACTION_APPEND
Element
.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.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.public DOMErrorHandler getErrorHandler()
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.public void setErrorHandler(DOMErrorHandler errorHandler)
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.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 org.w3c.dom.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
).org.w3c.dom.DOMException
- Raise a NOT_SUPPORTED_ERR exception 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 org.w3c.dom.DOMException
name
- The feature name, which is a string with DOM has-feature
syntax.true
or
false
).org.w3c.dom.DOMException
- Raise a NOT_FOUND_ERR When the DOMBuilder
does not
recognize the feature name.public org.w3c.dom.Document parseURI(java.lang.String uri) throws java.lang.Exception
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.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.public org.w3c.dom.Document parse(DOMInputSource is) throws java.lang.Exception
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.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.public void parseWithContext(DOMInputSource is, org.w3c.dom.Node cnode, short action) throws org.w3c.dom.DOMException
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.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.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).
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |