|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.sun.xml.tree.XmlDocumentBuilder
This class is a SAX DocumentHandler which converts a stream of parse events into an in-memory DOM document. After each Parser.parse() invocation returns, a resulting DOM Document may be accessed via the getDocument method. The parser and its builder should be used together; the builder may be used with only one parser at a time.
This builder optionally does XML namespace processing, reporting conformance problems as recoverable errors using the parser's error handler. If the parser is not a Sun parser, that handler will be inaccessible and so such errors will always be fatal. Also, if that handler does not treat such errors as fatal, processing will continue without raising an exception.
To customize the document, a powerful technique involves using an element factory specifying what element tags (from a given XML namespace) correspond to what implementation classes. Parse trees produced by such a builder can have nodes which add behaviors to achieve application-specific functionality, such as modifing the tree as it is parsed.
The object model here is that XML elements are polymorphic, with semantic intelligence embedded through customized internal nodes. Those nodes are created as the parse tree is built. Such trees now build on the W3C Document Object Model (DOM), and other models may be supported by the customized nodes. This allows both generic tools (understanding generic interfaces such as the DOM core) and specialized tools (supporting specialized behaviors, such as the HTML extensions to the DOM core; or for XSL elements) to share data structures.
Normally only "model" semantics are in document data structures, but "view" or "controller" semantics can be supported if desired.
Elements may choose to intercept certain parsing events directly. They do this by overriding the default implementations of methods in the XmlReadable interface. This is normally done to make the DOM tree represent application level modeling requirements, rather than matching an XML structure that may not be optimized appropriately.
Constructor Summary | |
XmlDocumentBuilder()
Default constructor is for use in conjunction with a SAX parser's DocumentHandler callback. |
Method Summary | |
void |
characters(char[] buf,
int offset,
int len)
SAX DocumentHandler callback, not for general application use. |
java.util.Locale |
chooseLocale(java.lang.String[] languages)
Chooses a client locale to use for diagnostics, using the first language specified in the list that is supported by this builder. |
void |
comment(java.lang.String text)
LexicalEventListener callback, not for general application use. |
XmlDocument |
createDocument()
This is a factory method, used to create an XmlDocument. |
void |
endCDATA()
LexicalEventListener callback, not for general application use. |
void |
endDocument()
SAX DocumentHandler callback, not for general application use. |
void |
endElement(java.lang.String tag)
SAX DocumentHandler callback, not for general application use. |
void |
endParsedEntity(java.lang.String name,
boolean included)
LexicalEventListener callback, not for general application use. |
boolean |
getDisableNamespaces()
Returns true if namespace conformance is not checked as the DOM tree is built. |
XmlDocument |
getDocument()
Returns the fruits of parsing, after a SAX parser has used this as a document handler during parsing. |
Locator |
getDocumentLocator()
Returns the document locator provided by the SAX parser. |
ElementFactory |
getElementFactory()
Returns the factory to be associated with documents produced by this builder. |
java.util.Locale |
getLocale()
Returns the locale to be used for diagnostic messages by this builder, and by documents it produces. |
Parser |
getParser()
Returns the parser used by this builder, if it is recorded; only Sun parsers are now recorded. |
void |
ignorableWhitespace(char[] buf,
int offset,
int len)
SAX DocumentHandler callback, not for general application use. |
boolean |
isIgnoringLexicalInfo()
Returns true (the default) if certain lexical information is automatically discarded when a DOM tree is built, producing smaller parse trees that are easier to use. |
void |
processingInstruction(java.lang.String name,
java.lang.String instruction)
SAX DocumentHandler callback, not for general application use. |
void |
setDisableNamespaces(boolean value)
Controls whether namespace conformance is checked during DOM tree construction, or (the default) not. |
void |
setDocumentLocator(Locator locator)
SAX DocumentHandler callback, not for general application use. |
void |
setElementFactory(ElementFactory factory)
Assigns the factory to be associated with documents produced by this builder. |
void |
setIgnoringLexicalInfo(boolean value)
Controls whether certain lexical information is discarded; by default, that information is discarded. |
void |
setLocale(java.util.Locale locale)
Assigns the locale to be used for diagnostic messages. |
void |
setParser(Parser p)
Sets the parser used by this builder. |
void |
startCDATA()
LexicalEventListener callback, not for general application use. |
void |
startDocument()
SAX DocumentHandler callback, not for general application use. |
void |
startElement(java.lang.String tag,
AttributeList attributes)
SAX DocumentHandler callback, not for general application use. |
void |
startParsedEntity(java.lang.String name)
LexicalEventListener callback, not for general application use. |
Methods inherited from class java.lang.Object |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait |
Constructor Detail |
public XmlDocumentBuilder()
Method Detail |
public boolean isIgnoringLexicalInfo()
public void setIgnoringLexicalInfo(boolean value)
That information includes whitespace in element content which is ignorable (note that some nonvalidating XML parsers will not report that information); all comments; which text is found in CDATA sections; and boundaries of entity references.
"Ignorable whitespace" as reported by parsers is whitespace used to format XML markup. That is, all whitespace except that in "mixed" or ANY content models is ignorable. When it is discarded, pretty-printing may be necessary to make the document be readable again by humans.
Whitespace inside "mixed" and ANY content models needs different treatment, since it could be part of the document content. In such cases XML defines a xml:space attribute which applications should use to determine whether whitespace must be preserved (value of the attribute is preserve) or whether default behavior (such as eliminating leading and trailing space, and normalizing consecutive internal whitespace to a single space) is allowed.
value
- true indicates that such lexical information should
be discarded during parsing.public boolean getDisableNamespaces()
public void setDisableNamespaces(boolean value)
public void setParser(Parser p)
public Parser getParser()
public XmlDocument getDocument()
public java.util.Locale getLocale()
public void setLocale(java.util.Locale locale) throws SAXException
When an XmlDocument is created, its locale is the default locale for the virtual machine. If a parser was recorded, the locale will be associated with that parser.
chooseLocale(java.lang.String[])
public java.util.Locale chooseLocale(java.lang.String[] languages) throws SAXException
languages
- Array of language specifiers, ordered with the most
preferable one at the front. For example, "en-ca" then "fr-ca",
followed by "zh_CN". Both RFC 1766 and Java styles are supported.MessageCatalog
,
Parser.chooseLocale(java.lang.String[])
public void setDocumentLocator(Locator locator)
locator
- used to identify a location in an XML document
being parsed.public Locator getDocumentLocator()
public XmlDocument createDocument()
public final void setElementFactory(ElementFactory factory)
public final ElementFactory getElementFactory()
public void startDocument() throws SAXException
public void endDocument() throws SAXException
public void startElement(java.lang.String tag, AttributeList attributes) throws SAXException
public void endElement(java.lang.String tag) throws SAXException
public void comment(java.lang.String text) throws SAXException
text
- body of the comment.public void startCDATA() throws SAXException
If this builder is set to record lexical information (by default it ignores such information) then this callback arranges that character data (and ignorable whitespace) be recorded as part of a CDATA section, until the matching endCDATA method is called.
public void endCDATA() throws SAXException
public void characters(char[] buf, int offset, int len) throws SAXException
Some parsers report "ignorable" whitespace through this interface, which can cause portability problems. That's because there is no safe way to discard it from a parse tree without accessing DTD information, of a type which DOM doesn't expose and most applications won't want to deal with. Avoid using such parsers.
buf
- holds text charactersoffset
- initial index of characters in buflen
- how many characters are being passedpublic void ignorableWhitespace(char[] buf, int offset, int len) throws SAXException
buf
- holds text charactersoffset
- initial index of characters in buflen
- how many characters are being passedpublic void processingInstruction(java.lang.String name, java.lang.String instruction) throws SAXException
Some applications may want to intercept processing instructions by overriding this method as one way to make such instructions take immediate effect during parsing, or to ensure that processing instructions in DTDs aren't ignored.
name
- the processor to which the instruction is directedinstruction
- the text of the instruction (no leading spaces)public void startParsedEntity(java.lang.String name) throws SAXException
If this builder is set to record lexical information (by default it ignores such information) then this callback arranges that an entity reference node hold data that is reported until the matching endParsedEntity callback. Otherwise that data is treated like any other content found in a document (and will not be marked as readonly).
name
- identifies the parsed general entity whose
expansion will be represented in the DOM tree.public void endParsedEntity(java.lang.String name, boolean included) throws SAXException
name
- identifies the parsed general entity whose
expansion will be represented in the DOM tree.included
- lets nonvalidating XML parser tell applications
about any external entities that were recognized but not included.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |