com.sun.lwuit.xml
Class XMLParser

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

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  com.sun.lwuit.xml.Element createNewElement(java.lang.String name)
          Creates a new element.
protected  com.sun.lwuit.xml.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(com.sun.lwuit.xml.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
 com.sun.lwuit.xml.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  com.sun.lwuit.xml.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  com.sun.lwuit.xml.Element parseTag(java.io.Reader is)
          This method collects the tag name and all of its attributes.
protected  void parseTagContent(com.sun.lwuit.xml.Element element, java.io.Reader is)
          Parses tags content, accumulating text and child elements .
 void setIncludeWhitespacesBetweenTags(boolean include)
           
 void setParserCallback(com.sun.lwuit.xml.ParserCallback parserCallback)
          Sets the specified callback to serve as the callback for parsing errors
protected  boolean shouldEvaluate(com.sun.lwuit.xml.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 com.sun.lwuit.xml.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 com.sun.lwuit.xml.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 com.sun.lwuit.xml.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(com.sun.lwuit.xml.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 com.sun.lwuit.xml.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 com.sun.lwuit.xml.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(com.sun.lwuit.xml.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(com.sun.lwuit.xml.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(com.sun.lwuit.xml.ParserCallback parserCallback)
Sets the specified callback to serve as the callback for parsing errors

Parameters:
parserCallback - The callback to use for parsing errors