com.sun.lwuit.xml
Class XMLParser

java.lang.Object
  com.sun.lwuit.xml.XMLParser

Direct Known Subclasses:

HTMLParser

public class XMLParser
extends java.lang.Object

The parser class is used to parse an XML document into a DOM object (Element).

Constructor Summary

XMLParser()
Constructs the XMLParser

Method Summary

void	addCharEntitiesRange(java.lang.String[] symbols, int startcode) Adds the given symbols array to the user defined char entities table with the startcode provided as the code of the first string, startcode+1 for the second etc.
void	addCharEntity(java.lang.String symbol, int code) Adds the given symbol and code to the user defined char entities table http://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references
protected void	attribute(java.lang.String tag, java.lang.String attributeName, java.lang.String value) Invoked for every attribute value of the givne tag This callback method is invoked only on the eventParser.
protected java.lang.String	convertCharEntity(java.lang.String charEntity) Converts a char entity to the matching character.
protected Element	createNewElement(java.lang.String name) Creates a new element.
protected Element	createNewTextElement(java.lang.String text) Creates a new text element.
protected void	endTag(java.lang.String tag) Invoked when a tag ends This callback method is invoked only on the eventParser.
void	eventParser(java.io.Reader r) The event parser requires deriving this class and overriding callback methods to work effectively.
protected java.lang.String	getSupportedStandardName() Returns a string identifying the document type this parser supports.
protected boolean	isEmptyTag(java.lang.String tagName) Checks whether the specified tag is an empty tag
protected boolean	isSupported(Element element) Returns true if this element is supported, false otherwise In XMLParser this always returns true, but subclasses can determine if an element is supported in their context according to its name etc.
protected boolean	isWhiteSpace(char ch) Checks if the specified character is a white space or not.
protected void	notifyError(int errorId, java.lang.String tag, java.lang.String attribute, java.lang.String value, java.lang.String description) A utility method used to notify an error to the ParserCallback and throw an IllegalArgumentException if parsingError returned false
Element	parse(java.io.Reader is) This is the entry point for parsing a document and the only non-private member method in this class
protected Element	parseCommentOrXMLDeclaration(java.io.Reader is, java.lang.String endTag) This utility method is used to parse comments and XML declarations in the XML.
protected Element	parseTag(java.io.Reader is) This method collects the tag name and all of its attributes.
protected void	parseTagContent(Element element, java.io.Reader is) Parses tags content, accumulating text and child elements .
void	setIncludeWhitespacesBetweenTags(boolean include)
void	setParserCallback(ParserCallback parserCallback) Sets the specified callback to serve as the callback for parsing errors
protected boolean	shouldEvaluate(Element element) Checks if this element should be evaluated by the parser This can be overriden by subclasses to skip certain elements
protected boolean	startTag(java.lang.String tag) Invoked when a tag is opened, this method should return true to process the tag or return false to skip the tag.
protected void	textElement(java.lang.String text) Invoked when the event parser encounters a text element.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XMLParser

public XMLParser()

Constructs the XMLParser

Method Detail

getSupportedStandardName

protected java.lang.String getSupportedStandardName()

Returns a string identifying the document type this parser supports. This should be overriden by subclassing parsers.

Returns:

a string identifying the document type this parser supports.

addCharEntity

public void addCharEntity(java.lang.String symbol,
                          int code)

Adds the given symbol and code to the user defined char entities table http://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references

Parameters:

symbol - The symbol to add

code - The symbol's code

addCharEntitiesRange

public void addCharEntitiesRange(java.lang.String[] symbols,
                                 int startcode)

Adds the given symbols array to the user defined char entities table with the startcode provided as the code of the first string, startcode+1 for the second etc. Some strings in the symbols array may be null thus skipping code numbers.

Parameters:

symbols - The symbols to add

startcode - The symbol's code

convertCharEntity

protected java.lang.String convertCharEntity(java.lang.String charEntity)

Converts a char entity to the matching character. This handles both numbered and symbol char entities (The latter is done via getCharEntityCode)

Parameters:

charEntity - The char entity to convert

Returns:

A string containing a single char, or the original char entity string (with & and ;) if the char entity couldn't be resolved

parse

public Element parse(java.io.Reader is)

This is the entry point for parsing a document and the only non-private member method in this class

Parameters:

is - The InputStream containing the XML

Returns:

an Element object describing the parsed document (Basically its DOM)

createNewElement

protected Element createNewElement(java.lang.String name)

Creates a new element. This should be overriden by parsers that use a subclass of Element.

Parameters:

name - The new element's name

Returns:

a new instance of the element

createNewTextElement

protected Element createNewTextElement(java.lang.String text)

Creates a new text element. This should be overriden by parsers that use a subclass of Element.

Parameters:

text - The new element's text

Returns:

a new instance of the element

setIncludeWhitespacesBetweenTags

public void setIncludeWhitespacesBetweenTags(boolean include)

eventParser

public void eventParser(java.io.Reader r)
                 throws java.io.IOException

The event parser requires deriving this class and overriding callback methods to work effectively. To stop the event parser in mid way a callback can simply throw an IOException on purpose.

Parameters:

r - the reader from which the data should be parsed

Throws:

java.io.IOException - if an exception is thrown by the reader

textElement

protected void textElement(java.lang.String text)

Invoked when the event parser encounters a text element. This callback method is invoked only on the eventParser.

Parameters:

text - the text encountered

startTag

protected boolean startTag(java.lang.String tag)

Invoked when a tag is opened, this method should return true to process the tag or return false to skip the tag. This callback method is invoked only on the eventParser.

Parameters:

tag - the tag name

Returns:

true to process the tag, false to skip the tag

endTag

protected void endTag(java.lang.String tag)

Invoked when a tag ends This callback method is invoked only on the eventParser.

Parameters:

tag - the tag name

attribute

protected void attribute(java.lang.String tag,
                         java.lang.String attributeName,
                         java.lang.String value)

Invoked for every attribute value of the givne tag This callback method is invoked only on the eventParser.

Parameters:

tag - the tag name

parseTagContent

protected void parseTagContent(Element element,
                               java.io.Reader is)
                        throws java.io.IOException

Parses tags content, accumulating text and child elements . Upon bumping a start tag character it calls the parseTag method. This method is called at first from the parse method, and later on from parseTag (which creates the recursion).

Parameters:

element - The current parent element

is - The InputStream containing the XML

Throws:

java.io.IOException - if an I/O error in the stream is encountered

isWhiteSpace

protected boolean isWhiteSpace(char ch)

Checks if the specified character is a white space or not. Exposed to packaage since used by HTMLComponent as well

Parameters:

ch - The character to check

Returns:

true if the character is a white space, false otherwise

parseTag

protected Element parseTag(java.io.Reader is)
                    throws java.io.IOException

This method collects the tag name and all of its attributes. For comments and XML declarations this will call the parseCommentOrXMLDeclaration method. Note that this method returns an Element with a name and attrbutes, but not its content/children which will be done by parseTagContent

Parameters:

is - The InputStream containing the XML

Returns:

The parsed element

Throws:

java.io.IOException - if an I/O error in the stream is encountered

parseCommentOrXMLDeclaration

protected Element parseCommentOrXMLDeclaration(java.io.Reader is,
                                               java.lang.String endTag)
                                        throws java.io.IOException

This utility method is used to parse comments and XML declarations in the XML. The comment/declaration is returned as an Element, but is flagged as a comment since both comments and XML declarations are not part of the XML DOM. This method can be overridden to process specific XML declarations

Parameters:

is - The inputstream

endTag - The endtag to look for

Returns:

An Element representing the comment or XML declartaion

Throws:

java.io.IOException

isEmptyTag

protected boolean isEmptyTag(java.lang.String tagName)

Checks whether the specified tag is an empty tag

Parameters:

tagName - The tag name to check

Returns:

true if that tag is defined as an empty tag, false otherwise

notifyError

protected void notifyError(int errorId,
                           java.lang.String tag,
                           java.lang.String attribute,
                           java.lang.String value,
                           java.lang.String description)

A utility method used to notify an error to the ParserCallback and throw an IllegalArgumentException if parsingError returned false

Parameters:

errorId - The error ID, one of the ERROR_* constants in ParserCallback

tag - The tag in which the error occured (Can be null for non-tag related errors)

attribute - The attribute in which the error occured (Can be null for non-attribute related errors)

value - The value in which the error occured (Can be null for non-value related errors)

description - A verbal description of the error

Throws:

java.lang.IllegalArgumentException - If the parser callback returned false on this error

isSupported

protected boolean isSupported(Element element)

Returns true if this element is supported, false otherwise In XMLParser this always returns true, but subclasses can determine if an element is supported in their context according to its name etc. Unsupported elements will be skipped by the parser and excluded from the resulting DOM object

Parameters:

element - The element to check

Returns:

true if the element is supported, false otherwise

shouldEvaluate

protected boolean shouldEvaluate(Element element)

Checks if this element should be evaluated by the parser This can be overriden by subclasses to skip certain elements

Parameters:

element - The element to check

Returns:

true if this element should be evaluated by the parser, false to skip it completely

setParserCallback

public void setParserCallback(ParserCallback parserCallback)

Sets the specified callback to serve as the callback for parsing errors

Parameters:

parserCallback - The callback to use for parsing errors