org.w3c.dom.ls.DOMBuilder Maven / Gradle / Ivy
/*
* Copyright (c) 2002 World Wide Web Consortium,
* (Massachusetts Institute of Technology, Institut National de
* Recherche en Informatique et en Automatique, Keio University). All
* Rights Reserved. This program is distributed under the W3C's Software
* Intellectual Property License. This program is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY; without even
* the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
* PURPOSE.
* See W3C License http://www.w3.org/Consortium/Legal/ for more details.
*/
package org.w3c.dom.ls;
import org.w3c.dom.Document;
import org.w3c.dom.Node;
import org.w3c.dom.DOMException;
import org.apache.xerces.dom3.DOMErrorHandler;
/**
* 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"- This
* feature is equivalent to the one provided on
*
Document.setNormalizationFeature in .
* -
*
"cdata-sections"
* - This feature is equivalent to the one
* provided on
Document.setNormalizationFeature in .
* -
*
"certified"
* -
*
* true- [optional] Assume, when XML 1.1
* is supported, that the input is certified (see section 2.13 in ).
* -
*
false
* - [required] (default) Don't assume that the input is
* certified (see section 2.13 in ).
*
* -
*
"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.
*
* "comments"- This feature is equivalent to the
* one provided on
Document.setNormalizationFeature in .
* -
*
"datatype-normalization"
* - This feature is equivalent to the
* one provided on
Document.setNormalizationFeature in .
* -
*
"entities"
* - This feature is equivalent to the one provided on
*
Document.setNormalizationFeature in .
* "infoset"-
* This feature is equivalent to the one provided on
*
Document.setNormalizationFeature in . Setting this feature
* to true will also force the feature namespaces
* to true.
* "namespaces"-
*
* true- [required
* ] (default) Perform the namespace processing as defined in .
* -
*
false
* - [optional] Do not perform the namespace processing.
*
* -
*
"namespace-declarations"
* - This feature is equivalent to the
* one provided on
Document.setNormalizationFeature in .
* -
*
"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.
*
* -
*
"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.
* false- [optional]
* Report an fatal error if a character is encountered for which the
* processor can not determine the normalization properties.
*
* -
*
"validate"
* - This feature is equivalent to the one provided on
*
Document.setNormalizationFeature in .
* -
*
"validate-if-schema"
* - This feature is equivalent to the one
* provided on
Document.setNormalizationFeature in .
* -
*
"whitespace-in-element-content"
* - This feature is equivalent
* to the one provided on
Document.setNormalizationFeature in .
*
* See also the Document Object Model (DOM) Level 3 Load
and Save Specification.
*/
public interface DOMBuilder {
/**
* 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.
*
If this attribute is null, the resolution of entities
* in the document is implementation dependent.
*/
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.
*
If this attribute is null, the resolution of entities
* in the document is implementation dependent.
*/
public void setEntityResolver(DOMEntityResolver entityResolver);
/**
* 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. 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 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. 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(DOMErrorHandler errorHandler);
/**
* 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.
*/
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.
*/
public void setFilter(DOMBuilderFilter filter);
/**
* 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.
* @param name The feature name.
* @param state The requested state of the feature (true or
* false).
* @exception DOMException
* NOT_SUPPORTED_ERR: Raised when the DOMBuilder recognizes
* the feature name but cannot set the requested value.
*
NOT_FOUND_ERR: Raised when the DOMBuilder does not
* recognize the feature name.
*/
public void setFeature(String name,
boolean state)
throws DOMException;
/**
* Query whether setting a feature to a specific value is supported.
*
The feature name has the same form as a DOM hasFeature string.
* @param name The feature name, which is a DOM has-feature style string.
* @param state The requested state of the feature (true or
* false).
* @return 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 canSetFeature(String name,
boolean state);
/**
* Look up the value of a feature.
*
The feature name has the same form as a DOM hasFeature string
* @param name The feature name, which is a string with DOM has-feature
* syntax.
* @return The current state of the feature (true or
* false).
* @exception DOMException
* NOT_FOUND_ERR: Raised when the DOMBuilder does not
* recognize the feature name.
*/
public boolean getFeature(String name)
throws DOMException;
/**
* Parse an XML document from a location identified by a URI reference .
* If the URI contains a fragment identifier (see section 4.1 in ), the
* behavior is not defined by this specification, but future versions of
* this specification might define the behavior.
* @param uri The location of the XML document to be read.
* @return 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.
*/
public Document parseURI(String uri);
/**
* Parse an XML document from a resource identified by a
* DOMInputSource.
* @param is The DOMInputSource from which the source
* document is to be read.
* @return 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.
*/
public Document parse(DOMInputSource is);
// ACTION_TYPES
/**
* Replace the context node with the result of parsing the input source.
* For this action to work the context node must have a parent and the
* context node must be an Element, Text,
* CDATASection, Comment,
* ProcessingInstruction, or EntityReference
* node.
*/
public static final short ACTION_REPLACE = 1;
/**
* Append the result of the input source as children of the context node.
* For this action to work, the context node must be an
* Element or a DocumentFragment.
*/
public static final short ACTION_APPEND_AS_CHILDREN = 2;
/**
* 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.
*/
public static final short ACTION_INSERT_AFTER = 3;
/**
* 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.
*/
public static final short ACTION_INSERT_BEFORE = 4;
/**
* 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
* Document node, attached to the context node, is used to
* resolved 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.
* @param 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.
* @param 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.
* @param 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.
* @exception DOMException
* NOT_SUPPORTED_ERR: Raised when the DOMBuilder doesn't
* support this method.
*
NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is
* readonly.
*/
public void parseWithContext(DOMInputSource is,
Node cnode,
short action)
throws DOMException;
}