com.prosyst.util.xml
Class XMLReader

java.lang.Object
  com.prosyst.util.xml.XMLReader

public class XMLReader
extends java.lang.Object

Class used for reading of xml files, creating tree structure of 'TagClass' for each xml tag. When reader reaches a closed tag it notifies a given 'TagListener' and sends the last tag to it. If closing tag does not correspond with the last open IllegalArgumentException is thrown. There is a debug property 'xml.debug' used to dump an Exceptions occurred while operation is running.

The parser, in general, is a simple XML parser that implements "Recursive descent" parsing method. Known limitations:

  Currently this XMLParser does not support the following special tags:
  1. <?TAG_NAME ..... ?>   or also "Processing Instructions"
  2. <!DOCTYPE .... >
  3. <!ELEMENT .... >
  4. <!ATTLIST .... >
  5. <!ENTITY .... >
 

The parser skippes these tags (it searches for '>' symbol and closes the 'special' tag).

Author:

Ivan Dimitrov

Field Summary

protected char	currentChar
protected char[]	fBuffer
protected int	fBufferLen
protected int	fBufferPos
protected int	fCurrentLevel
protected int	fLevel
protected int	fLine
protected static char[]	fNew_ent_chars
protected static java.lang.String[]	fNew_entities
protected static char[]	fOld_ent_chars
protected static java.lang.String[]	fOld_entities
protected int	fPos
protected java.io.Reader	fReader
protected java.io.InputStream	fStream
protected TagListener	fTagListener
protected char	prev_char

Constructor Summary

XMLReader()
An empty default constructor

XMLReader(java.io.InputStream aInputStream, TagListener aListener)
Constructs a new XMLReader.

XMLReader(java.io.Reader aReader, TagListener aListener)
Constructs a new XMLReader.

Method Summary

protected boolean	accept_char(char ch) Accepts one character from the input stream and if it's successful moves one character forward.
protected boolean	accept_seq(java.lang.String seq) Accepts a sequence of characters given by seq parameter.
protected void	clearWhiteSpaces() Clears the white spaces starting from the current position
protected void	err(int pos, java.lang.String message) Throws an IOException with the given message for the given line position.
protected void	err(java.lang.String message) Throws an IOException with a given message.
protected java.lang.String	getAttrValue() Parses an attribute value and returns it as a string
protected com.prosyst.util.string.CharBuffer	getCharBuffer()
java.lang.String	getEncoding() Returns the XML encoding attribute
protected boolean	getNextChar() Reads the next char from the input stream and sets it to private field currentChar
java.lang.String	getStandalone() Returns the value of XML standalone attribute
java.lang.String	getVersion() Returns the XML version attribute
static boolean	isNameChar(char ch) This method returns true if the passed characted may be used as part of a tag name or an attribute name
static boolean	isNameStartChar(char ch) This method returns true is the passed character may be used as starting character for tag name and attribute name
protected void	notifyListeners(TagClass aTag) Helper function that notify listeners depending on certain conditions such as if the tag event is on-close or on-open
protected boolean	parse_attr_list(TagClass aParent) Parses a tag attribute list with the following simplified grammar:
protected void	parse_attr_value(com.prosyst.util.string.CharBuffer sb, char quot) Parses the attribute value and if it's successful then adds it to the CharBuffer.
protected boolean	parse_attr(com.prosyst.util.string.CharBuffer cb) Parses an attribute with the given simplified grammar:
protected boolean	parse_CharRef(com.prosyst.util.string.CharBuffer sb) Parses a CharReference and if it is successful then appends it to the passed CharBuffer
protected boolean	parse_comment(TagClass aParent) Parses a comment.
protected boolean	parse_content(TagClass aParent) Parses the content of the tag (including sub-tags and sub-elements)
protected boolean	parse_EntityRef(com.prosyst.util.string.CharBuffer sb, boolean inAttribute) EntityRef ::= '&' + EntityValue + ';' EntityValue ::= 'amp' | 'quot' | 'apos' | 'gt' | 'lt' | identifier
protected java.lang.String	parse_identifier() Parses an identifier.
protected int	parse_identifier(com.prosyst.util.string.CharBuffer cb) Parses an identifier and places it into the passed CharBuffer
protected boolean	parse_PCDATA(TagClass aParent) Parses PCDATA content (Parseable Content DATA).
protected boolean	parse_tag_CDATA(TagClass aParent) Parses a CDATA tag (or CDATA content element).
protected boolean	parse_tag_name(TagClass aParent) Parses a tag name and if it is successfully parsed the method sets it as a name of the parent tag
protected boolean	parse_tag_normal(TagClass aParent) Parses a normal tag.
protected boolean	parse_tag_special(TagClass aParent) Parses special tags, such that begins with:
protected boolean	parse_tag(TagClass aParent) Parses either normal or special tag
protected boolean	parse_xml_prolog(TagClass parent) Parses the XML prolog tag, i.e. <?xml version="..." encoding="..." standalone="..." ?>
protected void	parseXML() Initiates parsing of the XML file given through aInputStream or aReader in the given constructor when creating XMLReader object.
static void	parseXML(java.io.InputStream aInputStream, TagListener aListener, int aLevel) Parses a XML file given through aInputStream and during the parsing notifies aListener for close-tag events Note: The XMLReader does not close the passed Reader or InputStream
static void	parseXML(java.io.Reader aReader, TagListener aListener, int aLevel) Parses a XML file given through aReader and during the parsing notifies aListener for close-tag events Note: The XMLReader does not close the passed Reader or InputStream
static void	read(java.io.InputStream aInputStream, TagListener aListener) Parses a XML file given through aInputStream and during the parsing notifies aListener for close-tag events Note: The XMLReader does not close the passed Reader or InputStream
static void	read(java.io.InputStream aInputStream, TagListener aListener, int aLevel) Parses a XML file given through aInputStream and during the parsing notifies aListener for close-tag events Note: The XMLReader does not close the passed Reader or InputStream
static void	read(java.io.Reader aReader, TagListener aListener) Parses a XML file given through aReader and during the parsing notifies aListener for close-tag events Note: The XMLReader does not close the passed Reader or InputStream
static void	read(java.io.Reader aReader, TagListener aListener, int aLevel) Parses a XML file given through aReader and during the parsing notifies aListener for close-tag events Note: The XMLReader does not close the passed Reader or InputStream
protected void	setEncoding(java.lang.String aEncoding) Sets the parser's encoding.
protected void	setLevel(int aLevel) Sets the level of tags bellow which the listener will be notified for.

Methods inherited from class java.lang.Object

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

Field Detail

fReader

protected java.io.Reader fReader

fStream

protected java.io.InputStream fStream

currentChar

protected char currentChar

fTagListener

protected TagListener fTagListener

fLine

protected int fLine

fPos

protected int fPos

fLevel

protected int fLevel

fCurrentLevel

protected int fCurrentLevel

fNew_entities

protected static final java.lang.String[] fNew_entities

fNew_ent_chars

protected static final char[] fNew_ent_chars

fOld_entities

protected static final java.lang.String[] fOld_entities

fOld_ent_chars

protected static final char[] fOld_ent_chars

prev_char

protected char prev_char

fBuffer

protected char[] fBuffer

fBufferLen

protected int fBufferLen

fBufferPos

protected int fBufferPos

Constructor Detail

XMLReader

public XMLReader()

An empty default constructor

XMLReader

public XMLReader(java.io.InputStream aInputStream,
                 TagListener aListener)

Constructs a new XMLReader.

Note: The XMLReader does not close the passed Reader or InputStream

Parameters:

aInputStream - an InputStream to read the XML file from

aListener - TagListener that will be notified on tag close event

Throws:

java.io.IOException

XMLReader

public XMLReader(java.io.Reader aReader,
                 TagListener aListener)

Constructs a new XMLReader.

Note: The XMLReader does not close the passed Reader or InputStream

Parameters:

aReader - a reader that will be used to read the XML file from

aListener - TagListener that will be notified on tag close event

Method Detail

read

public static void read(java.io.InputStream aInputStream,
                        TagListener aListener)
                 throws java.io.IOException

Parses a XML file given through aInputStream and during the parsing notifies aListener for close-tag events

Note: The XMLReader does not close the passed Reader or InputStream

Parameters:

aInputStream - an InputStream to read the XML file from

aListener - TagListener that will be notified on close-tag events

Throws:

java.io.IOException

read

public static void read(java.io.InputStream aInputStream,
                        TagListener aListener,
                        int aLevel)
                 throws java.io.IOException

Parses a XML file given through aInputStream and during the parsing notifies aListener for close-tag events

Note: The XMLReader does not close the passed Reader or InputStream

Parameters:

aInputStream - an InputStream to read the XML file from

aListener - TagListener that will be notified on close-tag events

aLevel - see parseXML(Reader aReader, TagListener aListener, int aLevel description

Throws:

java.io.IOException

read

public static void read(java.io.Reader aReader,
                        TagListener aListener)
                 throws java.io.IOException

Parses a XML file given through aReader and during the parsing notifies aListener for close-tag events

Note: The XMLReader does not close the passed Reader or InputStream

Parameters:

aReader - a Reader to read the XML file from

aListener - TagListener that will be notified on close-tag events

Throws:

java.io.IOException

read

public static void read(java.io.Reader aReader,
                        TagListener aListener,
                        int aLevel)
                 throws java.io.IOException

Parses a XML file given through aReader and during the parsing notifies aListener for close-tag events

Note: The XMLReader does not close the passed Reader or InputStream

Parameters:

aReader - a Reader to read the XML file from

aListener - TagListener that will be notified on close-tag events

aLevel - see parseXML(Reader aReader, TagListener aListener, int aLevel description

Throws:

java.io.IOException

setEncoding

protected void setEncoding(java.lang.String aEncoding)

Sets the parser's encoding. If there is a current encoding associated with the parser the method returns immediately

Parameters:

aEncoding - new encoding to be set

Throws:

java.io.UnsupportedEncodingException - if the encoding is not supported.

setLevel

protected void setLevel(int aLevel)

Sets the level of tags bellow which the listener will be notified for. For internal use only.

Parameters:

aLevel -

getCharBuffer

protected com.prosyst.util.string.CharBuffer getCharBuffer()

getNextChar

protected boolean getNextChar()
                       throws java.io.IOException

Reads the next char from the input stream and sets it to private field currentChar

Returns:

true if the next char is successfully read of false if End-Of-Stream is reached

Throws:

java.io.IOException - if some error occurs during reading the character or if the caller tries to read beyond the End-Of-Stream.

parse_attr_value

protected void parse_attr_value(com.prosyst.util.string.CharBuffer sb,
                                char quot)
                         throws java.io.IOException

Parses the attribute value and if it's successful then adds it to the CharBuffer. If there are EntityReferences of CharReferences in the attribute value, they will be turned to their equivalent symbols.
attr_value ::= (acceptable_char | EntityRef | CharRef)* - quot_symbol

Throws:

java.io.IOException

See Also:

parse_attr, parse_CharRef, parse_EntityRef

parse_attr

protected boolean parse_attr(com.prosyst.util.string.CharBuffer cb)
                      throws java.io.IOException

Parses an attribute with the given simplified grammar:

 attribute ::= S* + attr_name + S* + '=' + S* + ('\'' + (attr_value - '\'') + '\'')) | ('"' + (attr_value - '"') + '"'))
 attr_value ::= (acceptable_char | EntityRef | CharRef)*
 attr_name ::= identifier
 

Parameters:

aParent - the parent tag where the correctly parsed attribute will be added

Throws:

java.io.IOException

See Also:

parse_identifier, parse_attr_value

parse_attr_list

protected boolean parse_attr_list(TagClass aParent)
                           throws java.io.IOException

Parses a tag attribute list with the following simplified grammar:

 attr_list ::= attribute*


Parameters:
aParent - the parent tag that the parsed attributes will be added to
Returns:
true if at least one attribute is parsed correctly and false otherwise
Throws:
java.io.IOException
See Also:
parse_attr

isNameStartChar

public static final boolean isNameStartChar(char ch)

This method returns true is the passed character may be used as starting character for tag name and attribute name

Parameters:

ch - the tested character

Returns:

true if the character could be used as starting character for a tag name and an attribute name and false otherwise

isNameChar

public static final boolean isNameChar(char ch)

This method returns true if the passed characted may be used as part of a tag name or an attribute name

Parameters:

ch - the tested character

Returns:

true is the characted could be used as part of a tag name or an attribute name and false otherwise

parse_identifier

protected java.lang.String parse_identifier()
                                     throws java.io.IOException

Parses an identifier.

Returns:

an identifier as a string if it is parsed successfully and null otherwise

Throws:

java.io.IOException - if an exception occurs during read operations from the Reader or the InputStream

parse_identifier

protected int parse_identifier(com.prosyst.util.string.CharBuffer cb)
                        throws java.io.IOException

Parses an identifier and places it into the passed CharBuffer

Parameters:

cb - CharBuffer where the parsed identifier will be placed into

Returns:

the length of the parsed identifier

Throws:

java.io.IOException - if an exception occurs during read operations from the Reader or the InputStream

parse_tag_name

protected boolean parse_tag_name(TagClass aParent)
                          throws java.io.IOException

Parses a tag name and if it is successfully parsed the method sets it as a name of the parent tag

Parameters:

aParent - parent tag

Returns:

true if the name is parsed successfully and false otherwise

Throws:

java.io.IOException

See Also:

parse_identifier

notifyListeners

protected void notifyListeners(TagClass aTag)

Helper function that notify listeners depending on certain conditions such as if the tag event is on-close or on-open

Parameters:

aTag - The tag that the notification event is valid for.

isStart - true if the event is on-open and false if it is on-close

parse_tag_normal

protected boolean parse_tag_normal(TagClass aParent)
                            throws java.io.IOException

Parses a normal tag. There are two cases - (1) the tag has separate open and close tag elements and (2) the tag is simple suchas <tag_name ... />

Parameters:

aParent - The parent tag that this tag will be added to if the parsing is successful

Returns:

true on success and false otherwise

Throws:

java.io.IOException

See Also:

clearWhiteSpaces, parse_tag_name, parse_attr_list, notifyListeners, accept_char, accept_seq, parse_PCDATA

parse_tag_special

protected boolean parse_tag_special(TagClass aParent)
                             throws java.io.IOException

Parses special tags, such that begins with:

 

getAttrValue
protected java.lang.String getAttrValue()
                                 throws java.io.IOException

Parses an attribute value and returns it as a string



Returns:
the parsed attribute value as a string.
Throws:
java.io.IOException - if an exception occurs during read operations from the
 Reader or the InputStream





parse_xml_prolog
protected boolean parse_xml_prolog(TagClass parent)
                            throws java.io.IOException

Parses the XML prolog tag, i.e.

  <?xml version="..." encoding="..." standalone="..." ?> 



Parameters:
parent - the parent tag (in this case this is the root "fake" tag, which
 the listeners will never be informed for...)
Throws:
java.io.IOException - if an exception occurs during read operations from the
 Reader or the InputStream





parse_comment
protected boolean parse_comment(TagClass aParent)
                         throws java.io.IOException

Parses a comment. The grammar is:

 Comment  ::=  '<!--' ((Char - '-') | ('-' (Char - '-')))* '-->'

 Note that the grammar does not allow a comment ending in --->. 
 The following example is not well-formed.

 <!-- B+, B, or B--->


Parameters:
aParent - The parent tag
Returns:
true on success and false otherwise
Throws:
java.io.IOException
See Also:
accept_char





parse_tag
protected boolean parse_tag(TagClass aParent)
                     throws java.io.IOException

Parses either normal or special tag


Parameters:
aParent - The parent tag that the successfully parsed tag will 
 (if it is normal tag or CDATA element)
 be added
Returns:
true on success and false otherwise
Throws:
java.io.IOException
See Also:
accept_cahr, 
parse_tag_normal, 
parse_tag_special, 
clearWhiteSpaces





parse_content
protected boolean parse_content(TagClass aParent)
                         throws java.io.IOException

Parses the content of the tag (including sub-tags and sub-elements)


Parameters:
aParent - The parent tag that the content and tags will be added to
Returns:
true on success and false otherwise
Throws:
java.io.IOException
See Also:
parse_PCDATA, 
parse_tag





parse_tag_CDATA
protected boolean parse_tag_CDATA(TagClass aParent)
                           throws java.io.IOException

Parses a CDATA tag (or CDATA content element).


Parameters:
aParent - The parent tag that the content will be added to
Returns:
true on success and false otherwise
Throws:
java.io.IOException





parse_PCDATA
protected boolean parse_PCDATA(TagClass aParent)
                        throws java.io.IOException

Parses PCDATA content (Parseable Content DATA). The EntityRefs and CharRefs
 that are parsed will be turned to its symbol equivalent.


Parameters:
aParent - The parent tag that the PCDATA will be added to
Returns:
true on success and false otherwise
Throws:
java.io.IOException
See Also:
accept_char, 
parse_CharRef, 
parse_EntityRef





accept_char
protected boolean accept_char(char ch)
                       throws java.io.IOException

Accepts one character from the input stream and if it's successful moves one
 character forward.


Parameters:
ch - The character that should be accepted
Returns:
true on success and false otherwise
Throws:
java.io.IOException





accept_seq
protected boolean accept_seq(java.lang.String seq)
                      throws java.io.IOException

Accepts a sequence of characters given by seq parameter. If the sequence is 
 accepted successfully then the currentChar field will contain the character
 immediately after the accepted sequence.


Parameters:
seq - The character sequence that should be accepted
Returns:
true on success and false otherwise
Throws:
java.io.IOException





parse_EntityRef
protected boolean parse_EntityRef(com.prosyst.util.string.CharBuffer sb,
                                  boolean inAttribute)
                           throws java.io.IOException


 EntityRef ::= '&' + EntityValue + ';'

 EntityValue ::= 'amp' | 'quot' | 'apos' | 'gt' | 'lt' | identifier
 


Parameters:
sb - The string buffer that the recognized entity will be appended to
Returns:
true on success and false otherwise
Throws:
java.io.IOException
See Also:
parse_identifier, 
accept_char





parse_CharRef
protected boolean parse_CharRef(com.prosyst.util.string.CharBuffer sb)
                         throws java.io.IOException

Parses a CharReference and if it is successful then appends it to the
 passed CharBuffer


Parameters:
sb - CharBuffer that the parsed CharReference will be added to
Returns:
true on success and false otherwise
Throws:
java.io.IOException





clearWhiteSpaces
protected void clearWhiteSpaces()
                         throws java.io.IOException

Clears the white spaces starting from the current position



Throws:
java.io.IOException





err
protected void err(java.lang.String message)
            throws java.io.IOException

Throws an IOException with a given message. The current line number and line
 position are appended to the error message


Parameters:
message - The message of the exception
Throws:
java.io.IOException





err
protected void err(int pos,
                   java.lang.String message)
            throws java.io.IOException

Throws an IOException with the given message for the given line position.
 The current line number and position (pos) are appended to the exception 
 message


Parameters:
pos - The line position that the error will be reported for
message - 
Throws:
java.io.IOException





parseXML
protected void parseXML()
                 throws java.io.IOException

Initiates parsing of the XML file given through aInputStream or aReader
 in the given constructor when creating XMLReader object.



Throws:
java.io.IOException - if an error occurs during reading the XML file or if 
  a parsing error eccurs.





parseXML
public static void parseXML(java.io.InputStream aInputStream,
                            TagListener aListener,
                            int aLevel)
                     throws java.io.IOException

Parses a XML file given through aInputStream and during the parsing notifies
 aListener for close-tag events
 

Note: The XMLReader does not close the passed Reader or InputStream


Parameters:
aInputStream - an InputStream to read the XML file from
aListener - TagListener that will be notified on close-tag event
aLevel - see parseXML(Reader aReader, TagListener aListener, int aLevel 
  description
Throws:
java.io.IOException - if some IO error occurs when reading the XML file or if
  a parser error occurs.






parseXML
public static void parseXML(java.io.Reader aReader,
                            TagListener aListener,
                            int aLevel)
                     throws java.io.IOException

Parses a XML file given through aReader and during the parsing notifies
 aListener for close-tag events
 

Note: The XMLReader does not close the passed Reader or InputStream


Parameters:
aReader - a reader that will be used to read the XML file from
aListener - TagListener that will be notified on close-tag event
aLevel - indicates the tag level that the listener will be invoked for.
  For example if the XML is:
  <a>
    <b>
      <c />
    </b>
  </a>
 


 and the passed aLevel is 2 then the listener will be invoked only for tags
 that have level 2, i.e. in our example the listener will be invoked only for
 tag <b>

 

 
Value less than 0 indicates "invoke listener for all tags no matter what 
 are their levels"
 
Value of 0 indicates that the listener must not be invoked in general
 no matter what is the tag level
 
Value greater than 0 indicates the tag level that the listener will
 be invoked for
Throws:
java.io.IOException - if some IO error occurs when reading the XML file or if
  a parser error occurs.






getVersion
public java.lang.String getVersion()

Returns the XML version attribute



Returns:
the XML file version attribute





getEncoding
public java.lang.String getEncoding()

Returns the XML encoding attribute



Returns:
the XML encoding attribute





getStandalone
public java.lang.String getStandalone()

Returns the value of XML standalone attribute



Returns:
the value of XML standalone attribute