|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--xml.DomBuilder
Builds a DOM Level 1 (or Level 2) Document object from the output of a
SAX2 parser, using a defaulted or specified DOM
implementation and parser. For example, a validating XML parser can be
connected with an XML DOM; or an HTML parser could be connected to an
HTML (or non-HTML) DOM. By default, if the DOM supports Level 2 calls,
namespace rules are used when building the DOM document; this will cause
some legal XML 1.0 documents to be rejected. If standard XML behavior is
desired, use setUsingNamespaces(false)
.
Note that some of the information exposed through DOM is only of
exotic interest, and does not truly relate to the core semantic model
of XML as consisting of elements, attributes, text, and processing
instructions. By default, this builder only exposes core node types,
and will not create any "extra" nodes, such as those for comments or
ignorable whitespace. This behavior may be changed by using the
setSavingExtraNodes(true)
method. The most useful
of such nodes are probably comments, which are used in some legacy
environments, such as HTML/XHTML, to wrap content such as inlined CSS
style directives or scripting code. However, some applications may
also want to know when text was represented using CDATA delimiters.
As a rule, if you ignore "extra" nodes and all of the incomplete DOM DTD functionality, and provide a fully featured SAX2 parser, the main portability issue your code may have is that some nonvalidating parsers will report ignorable whitespace characters as normal character data, so that your application can't as readily ignore it.
The DOM implementation class used is specified either as a parameter
to a construction method, or is derived from the value of the
xml.DomBuilder.Document
system property.
That class must provide a default constructor, which creates an object
conforming to the DOM Level 1 core "Document" API.
The SAX2 parser used is either provided as a constructor parameter, or is identified from "org.xml.sax.driver" system property. The parser used should be a SAX2 XMLReader supporting the "lexical-handler" feature; see below for details of how the SAX1 API does not provide information needed to support DOM correctly (it's more than just hiding data for "extra" nodes). (There are fallbacks in case the system property is not defined.)
By providing a parser directly, the caller can ensure that it has been properly configured. For example, it might be set up to validate. The caller may set up the ErrorHandler, Locale, and EntityResolver. This builder will assign the SAX2 Content and Lexical handlers of the parser, Other handlers, except for the error handler and the entity resolver, are reserved for future use by this builder.
Because of missing functionality in the DOM APIs, the following DTD-related functionality can't be supported by software, such as this builder, which does not rely on nonstandard extensions to the DOM APIs.
Some other functionality is not available through SAX, even using the SAX2 parser APIs, and so can't be provided here. Some other functionality (some affecting completeness of DOM data models) is only available in those SAX2 APIs, and so can't be provided when a SAX1 parser is in use.
At this time, XML 1.0 conformance is assumed unless a Level 2 implementation of DOM is used, in which case the more restrictive XML namespace rules are used when elements and processing instructions are processed. This means that the use of colons in element and attribute names is more restrictive than in the XML 1.0 specification, and is completely forbidden in the names of processing instruction targets. Also, only attributes of types CDATA, NMTOKEN, and NMTOKENS may contain colons; and name prefixes must be declared. The namespace restrictions on entity and notation names (they must not contain colons) are not currently enforced.
DomConsumer
Constructor Summary | |
DomBuilder()
Constructs a builder using the default DOM document class and the default SAX parser. |
|
DomBuilder(java.lang.String DOMDocumentClassName)
Constructs a builder using the specified DOM document class and the default SAX2 parser. |
|
DomBuilder(java.lang.String DOMDocumentClassName,
XMLReader parser)
Constructs a builder using the specified DOM document class and the specified SAX parser. |
|
DomBuilder(XMLReader parser)
Constructs a builder using the default DOM document class and the specified SAX2 parser. |
Method Summary | |
static Document |
createDocument(InputSource input)
Convenience routine, which uses the default DOM and parser (as described above) to parse the specified (XML) document into a DOM document tree. |
static Document |
createDocument(java.lang.String uri)
Convenience routine, which uses the default DOM and parser (as described above) to parse the specified (XML) document into a DOM document tree. |
static Document |
createEmptyDocument()
Returns an empty DOM document of the system default implementation. |
static Document |
createEmptyDocument(java.lang.String name)
Returns an empty DOM document of the specified implementation. |
boolean |
isSavingExtraNodes()
Returns true if the builder is saving "extra" nodes, and false (the default) otherwise. |
boolean |
isUsingNamespaces()
Returns true (the default for L2 DOM implementations) if the builder is using an "XML + Namespaces" style DOM construction, which will cause fatal errors on some legal XML 1.0 documents. |
Document |
parse(InputSource input)
Parses the document provided, returning its contents as a DOM document. |
Document |
parse(java.lang.String uri)
Parses the specified document, returning its contents as a DOM document. |
void |
setSavingExtraNodes(boolean flag)
Controls whether the builder will save "extra" nodes. |
void |
setUsingNamespaces(boolean flag)
Controls whether the builder uses an "XML + Namespaces" style DOM construction. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
public DomBuilder() throws SAXException
SAXException
- Normally wraps another exception reflecting
a problem uncovered when trying to instantiate a SAX2 parser or
DOM document object.public DomBuilder(java.lang.String DOMDocumentClassName) throws SAXException
DOMDocumentClassName
- The name of the class implementing the
kind of DOM document to be returned.SAXException
- Normally wraps another exception reflecting
a problem uncovered when trying to instantiate a SAX2 parser or
DOM document object.public DomBuilder(XMLReader parser) throws SAXException
parser
- The SAX parser to be used; it may be partially
configured, as described above.SAXException
- Normally wraps another exception reflecting
a problem uncovered when trying to instantiate a document object.public DomBuilder(java.lang.String DOMDocumentClassName, XMLReader parser) throws SAXException
DOMDocumentClassName
- The name of the class implementing the
kind of DOM document to be returned.parser
- The SAX parser to be used; it may be partially
configured, as described above.SAXException
- Normally wraps another exception reflecting
a problem uncovered when trying to instantiate a document object.Method Detail |
public static Document createEmptyDocument() throws SAXException
SAXException
- Normally wraps another exception reflecting
a problem uncovered when trying to instantiate the document.public static Document createEmptyDocument(java.lang.String name) throws SAXException
SAXException
- Normally wraps another exception reflecting
a problem uncovered when trying to instantiate the document.public static Document createDocument(java.lang.String uri) throws SAXException, java.io.IOException
uri
- Identifies the resource to be parsed.SAXException
- Normally wraps another exception reflecting
a problem uncovered when trying to instantiate the document object
or a parser.java.io.IOException
- when there is a problem reading a part of
the specified documentpublic static Document createDocument(InputSource input) throws SAXException, java.io.IOException
input
- Provided to the SAX parser as input.SAXException
- Normally wraps another exception reflecting
a problem uncovered when trying to instantiate the document object
or a parser.java.io.IOException
- when there is a problem reading a part of
the specified documentpublic boolean isSavingExtraNodes()
setSavingExtraNodes(boolean)
public void setSavingExtraNodes(boolean flag)
flag
- True iff extra nodes should be saved; false otherwise.isSavingExtraNodes()
public boolean isUsingNamespaces()
setUsingNamespaces(boolean)
public void setUsingNamespaces(boolean flag)
flag
- True iff namespaces should be enforced; else false.isUsingNamespaces()
public Document parse(java.lang.String uri) throws SAXException, java.io.IOException, DOMException
uri
- Identifies the resource to be parsed.SAXException
- As reported by the parser (in which case it is
often a SAXParseException) or this builder.java.io.IOException
- As reported by the parserDOMException
- As reported by the DOM; always indicates
a bug in either the DOM or the SAX parserpublic Document parse(InputSource input) throws SAXException, java.io.IOException, DOMException
input
- Provided to the SAX parser as input.SAXException
- As reported by the parser (in which case it is
often a SAXParseException) or this builder.java.io.IOException
- As reported by the parserDOMException
- As reported by the DOM; always indicates
a bug in either the DOM or the SAX parser
|
Source code is GPL'd at http://xmlconf.sourceforge.net. |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |