IcedTea-Web
NetX

net.sourceforge.nanoxml
Class XMLElement

java.lang.Object
  extended by net.sourceforge.nanoxml.XMLElement

public class XMLElement
extends java.lang.Object

XMLElement is a representation of an XML object. The object is able to parse XML code.

Parsing XML Data
You can parse XML data using the following code:
Retrieving Attributes
You can enumerate the attributes of an element using the method enumerateAttributeNames. The attribute values can be retrieved using the method getAttribute. The following example shows how to list the attributes of an element:
Retrieving Child Elements
You can enumerate the children of an element using enumerateChildren. The number of child elements can be retrieved using countChildren.
Elements Containing Character Data
If an elements contains character data, like in the following example: you can retrieve that data using the method getContent.
Subclassing XMLElement
When subclassing XMLElement, you need to override the method createAnotherElement which has to return a new copy of the receiver.

See Also:
XMLParseException

Constructor Summary
  XMLElement()
          Creates and initializes a new XML element.
protected XMLElement(java.util.Hashtable<java.lang.String,char[]> entities, boolean skipLeadingWhitespace, boolean fillBasicConversionTable, boolean ignoreCase)
          Creates and initializes a new XML element.
 
Method Summary
 void addChild(XMLElement child)
          Adds a child element.
protected  boolean checkCDATA(java.lang.StringBuffer buf)
          Scans a special tag and if the tag is a CDATA section, append its content to buf.
protected  boolean checkLiteral(java.lang.String literal)
          Scans the data for literal text.
 int countChildren()
          Returns the number of child elements of the element.
protected  XMLElement createAnotherElement()
          Creates a new similar XML element.
 java.util.Enumeration enumerateAttributeNames()
          Enumerates the attribute names.
 java.util.Enumeration enumerateChildren()
          Enumerates the child elements.
protected  XMLParseException expectedInput(java.lang.String charSet)
          Creates a parse exception for when the next character read is not the character that was expected.
protected  XMLParseException expectedInput(java.lang.String charSet, char ch)
          Creates a parse exception for when the next character read is not the character that was expected.
 java.lang.Object getAttribute(java.lang.String name)
          Returns an attribute of the element.
 java.lang.String getContent()
          Returns the PCDATA content of the object.
 int getLineNr()
          Returns the line nr in the source data on which the element is found.
 java.lang.String getName()
          Returns the name of the element.
protected  XMLParseException invalidValue(java.lang.String name, java.lang.String value)
          Creates a parse exception for when an invalid value is given to a method.
protected  XMLParseException invalidValueSet(java.lang.String name)
          Creates a parse exception for when an invalid valueset is given to a method.
 void parseFromReader(java.io.Reader reader)
          Reads one XML element from a java.io.Reader and parses it.
 void parseFromReader(java.io.Reader reader, int startingLineNr)
          Reads one XML element from a java.io.Reader and parses it.
protected  char readChar()
          Reads a character from a reader.
protected  void resolveEntity(java.lang.StringBuffer buf)
          Resolves an entity.
 void sanitizeInput(java.io.InputStreamReader isr, java.io.PipedOutputStream pout)
          Reads an xml file and removes the comments, leaving only relevant xml code.
protected  void scanElement(XMLElement elt)
          Scans an XML element.
protected  void scanIdentifier(java.lang.StringBuffer result)
          Scans an identifier from the current reader.
protected  void scanPCData(java.lang.StringBuffer data)
          Scans a #PCDATA element.
protected  void scanString(java.lang.StringBuffer string)
          This method scans a delimited string from the current reader.
protected  char scanWhitespace()
          This method scans an identifier from the current reader.
protected  char scanWhitespace(java.lang.StringBuffer result)
          This method scans an identifier from the current reader.
 void setAttribute(java.lang.String name, java.lang.Object value)
          Adds or modifies an attribute.
 void setContent(java.lang.String content)
          Changes the content string.
 void setName(java.lang.String name)
          Changes the name of the element.
protected  void skipComment()
          Skips a comment.
protected  void skipSpecialTag(int bracketLevel)
          Skips a special tag or comment.
protected  XMLParseException syntaxError(java.lang.String context)
          Creates a parse exception for when a syntax error occured.
protected  XMLParseException unexpectedEndOfData()
          Creates a parse exception for when the end of the data input has been reached.
protected  XMLParseException unknownEntity(java.lang.String name)
          Creates a parse exception for when an entity could not be resolved.
protected  void unreadChar(char ch)
          Pushes a character back to the read-back buffer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XMLElement

public XMLElement()
Creates and initializes a new XML element. Calling the construction is equivalent to:
Postconditions:
  • countChildren() => 0
  • enumerateChildren() => empty enumeration
  • enumeratePropertyNames() => empty enumeration
  • getChildren() => empty vector
  • getContent() => ""
  • getLineNr() => 0
  • getName() => null


XMLElement

protected XMLElement(java.util.Hashtable<java.lang.String,char[]> entities,
                     boolean skipLeadingWhitespace,
                     boolean fillBasicConversionTable,
                     boolean ignoreCase)
Creates and initializes a new XML element.

This constructor should only be called from createAnotherElement to create child elements.

Parameters:
entities - The entity conversion table.
skipLeadingWhitespace - true if leading and trailing whitespace in PCDATA content has to be removed.
fillBasicConversionTable - true if the basic entities need to be added to the entity list (client code calling this constructor).
ignoreCase - true if the case of element and attribute names have to be ignored.
Preconditions:
  • entities != null
  • if fillBasicConversionTable == false then entities contains at least the following entries: amp, lt, gt, apos and quot
Postconditions:
  • countChildren() => 0
  • enumerateChildren() => empty enumeration
  • enumeratePropertyNames() => empty enumeration
  • getChildren() => empty vector
  • getContent() => ""
  • getLineNr() => 0
  • getName() => null
Method Detail

addChild

public void addChild(XMLElement child)
Adds a child element.

Parameters:
child - The child element to add.
Preconditions:
  • child != null
  • child.getName() != null
  • child does not have a parent element
Postconditions:
  • countChildren() => old.countChildren() + 1
  • enumerateChildren() => old.enumerateChildren() + child
  • getChildren() => old.enumerateChildren() + child

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.Object value)
Adds or modifies an attribute.

Parameters:
name - The name of the attribute.
value - The value of the attribute.
Preconditions:
  • name != null
  • name is a valid XML identifier
  • value != null
Postconditions:
  • enumerateAttributeNames() => old.enumerateAttributeNames() + name
  • getAttribute(name) => value

countChildren

public int countChildren()
Returns the number of child elements of the element.
Postconditions:
  • result >= 0


enumerateAttributeNames

public java.util.Enumeration enumerateAttributeNames()
Enumerates the attribute names.
Postconditions:
  • result != null


enumerateChildren

public java.util.Enumeration enumerateChildren()
Enumerates the child elements.
Postconditions:
  • result != null


getContent

public java.lang.String getContent()
Returns the PCDATA content of the object. If there is no such content, null is returned.


getLineNr

public int getLineNr()
Returns the line nr in the source data on which the element is found. This method returns 0 there is no associated source data.
Postconditions:
  • result >= 0


getAttribute

public java.lang.Object getAttribute(java.lang.String name)
Returns an attribute of the element. If the attribute doesn't exist, null is returned.

Parameters:
name - The name of the attribute.
Preconditions:
  • name != null
  • name is a valid XML identifier

getName

public java.lang.String getName()
Returns the name of the element.


parseFromReader

public void parseFromReader(java.io.Reader reader)
                     throws java.io.IOException,
                            XMLParseException
Reads one XML element from a java.io.Reader and parses it.

Parameters:
reader - The reader from which to retrieve the XML data.
Preconditions:
  • reader != null
  • reader is not closed
Postconditions:
  • the state of the receiver is updated to reflect the XML element parsed from the reader
  • the reader points to the first character following the last '>' character of the XML element
Throws:
java.io.IOException - If an error occured while reading the input.
XMLParseException - If an error occured while parsing the read data.

parseFromReader

public void parseFromReader(java.io.Reader reader,
                            int startingLineNr)
                     throws java.io.IOException,
                            XMLParseException
Reads one XML element from a java.io.Reader and parses it.

Parameters:
reader - The reader from which to retrieve the XML data.
startingLineNr - The line number of the first line in the data.
Preconditions:
  • reader != null
  • reader is not closed
Postconditions:
  • the state of the receiver is updated to reflect the XML element parsed from the reader
  • the reader points to the first character following the last '>' character of the XML element
Throws:
java.io.IOException - If an error occured while reading the input.
XMLParseException - If an error occured while parsing the read data.

createAnotherElement

protected XMLElement createAnotherElement()
Creates a new similar XML element.

You should override this method when subclassing XMLElement.


setContent

public void setContent(java.lang.String content)
Changes the content string.

Parameters:
content - The new content string.

setName

public void setName(java.lang.String name)
Changes the name of the element.

Parameters:
name - The new name.
Preconditions:
  • name != null
  • name is a valid XML identifier

scanIdentifier

protected void scanIdentifier(java.lang.StringBuffer result)
                       throws java.io.IOException
Scans an identifier from the current reader. The scanned identifier is appended to result.

Parameters:
result - The buffer in which the scanned identifier will be put.
Preconditions:
  • result != null
  • The next character read from the reader is a valid first character of an XML identifier.
Postconditions:
  • The next character read from the reader won't be an identifier character.
Throws:
java.io.IOException

scanWhitespace

protected char scanWhitespace()
                       throws java.io.IOException
This method scans an identifier from the current reader.

Returns:
the next character following the whitespace.
Throws:
java.io.IOException

scanWhitespace

protected char scanWhitespace(java.lang.StringBuffer result)
                       throws java.io.IOException
This method scans an identifier from the current reader. The scanned whitespace is appended to result.

Returns:
the next character following the whitespace.
Preconditions:
  • result != null
Throws:
java.io.IOException

scanString

protected void scanString(java.lang.StringBuffer string)
                   throws java.io.IOException
This method scans a delimited string from the current reader. The scanned string without delimiters is appended to string.
Preconditions:

Throws:
java.io.IOException

scanPCData

protected void scanPCData(java.lang.StringBuffer data)
                   throws java.io.IOException
Scans a #PCDATA element. CDATA sections and entities are resolved. The next < char is skipped. The scanned data is appended to data.
Preconditions:

Throws:
java.io.IOException

checkCDATA

protected boolean checkCDATA(java.lang.StringBuffer buf)
                      throws java.io.IOException
Scans a special tag and if the tag is a CDATA section, append its content to buf.
Preconditions:

Throws:
java.io.IOException

skipComment

protected void skipComment()
                    throws java.io.IOException
Skips a comment.
Preconditions:

Throws:
java.io.IOException

skipSpecialTag

protected void skipSpecialTag(int bracketLevel)
                       throws java.io.IOException
Skips a special tag or comment.

Parameters:
bracketLevel - The number of open square brackets ([) that have already been read.
Preconditions:
  • The first <! has already been read.
  • bracketLevel >= 0
Throws:
java.io.IOException

checkLiteral

protected boolean checkLiteral(java.lang.String literal)
                        throws java.io.IOException
Scans the data for literal text. Scanning stops when a character does not match or after the complete text has been checked, whichever comes first.

Parameters:
literal - the literal to check.
Preconditions:
  • literal != null
Throws:
java.io.IOException

readChar

protected char readChar()
                 throws java.io.IOException
Reads a character from a reader.

Throws:
java.io.IOException

scanElement

protected void scanElement(XMLElement elt)
                    throws java.io.IOException
Scans an XML element.

Parameters:
elt - The element that will contain the result.
Preconditions:
  • The first < has already been read.
  • elt != null
Throws:
java.io.IOException

resolveEntity

protected void resolveEntity(java.lang.StringBuffer buf)
                      throws java.io.IOException
Resolves an entity. The name of the entity is read from the reader. The value of the entity is appended to buf.

Parameters:
buf - Where to put the entity value.
Preconditions:
  • The first & has already been read.
  • buf != null
Throws:
java.io.IOException

unreadChar

protected void unreadChar(char ch)
Pushes a character back to the read-back buffer.

Parameters:
ch - The character to push back.
Preconditions:
  • The read-back buffer is empty.
  • ch != '\0'

invalidValueSet

protected XMLParseException invalidValueSet(java.lang.String name)
Creates a parse exception for when an invalid valueset is given to a method.

Parameters:
name - The name of the entity.
Preconditions:
  • name != null

invalidValue

protected XMLParseException invalidValue(java.lang.String name,
                                         java.lang.String value)
Creates a parse exception for when an invalid value is given to a method.

Parameters:
name - The name of the entity.
value - The value of the entity.
Preconditions:
  • name != null
  • value != null

unexpectedEndOfData

protected XMLParseException unexpectedEndOfData()
Creates a parse exception for when the end of the data input has been reached.


syntaxError

protected XMLParseException syntaxError(java.lang.String context)
Creates a parse exception for when a syntax error occured.

Parameters:
context - The context in which the error occured.
Preconditions:
  • context != null
  • context.length() > 0

expectedInput

protected XMLParseException expectedInput(java.lang.String charSet)
Creates a parse exception for when the next character read is not the character that was expected.

Parameters:
charSet - The set of characters (in human readable form) that was expected.
Preconditions:
  • charSet != null
  • charSet.length() > 0

expectedInput

protected XMLParseException expectedInput(java.lang.String charSet,
                                          char ch)
Creates a parse exception for when the next character read is not the character that was expected.

Parameters:
charSet - The set of characters (in human readable form) that was expected.
ch - The character that was received instead.
Preconditions:
  • charSet != null
  • charSet.length() > 0

unknownEntity

protected XMLParseException unknownEntity(java.lang.String name)
Creates a parse exception for when an entity could not be resolved.

Parameters:
name - The name of the entity.
Preconditions:
  • name != null
  • name.length() > 0

sanitizeInput

public void sanitizeInput(java.io.InputStreamReader isr,
                          java.io.PipedOutputStream pout)
Reads an xml file and removes the comments, leaving only relevant xml code.

Parameters:
isr - The reader of the InputStream containing the xml.
pout - The PipedOutputStream that will be receiving the filtered xml file.

IcedTea-Web
NetX

Submit a bug or feature