Package net.sourceforge.nanoxml
Class XMLElement
- java.lang.Object
-
- 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:
XMLElement xml = new XMLElement(); FileReader reader = new FileReader("filename.xml"); xml.parseFromReader(reader);
- Retrieving Attributes
-
You can enumerate the attributes of an element using the method
enumerateAttributeNames
. The attribute values can be retrieved using the methodgetAttribute
. The following example shows how to list the attributes of an element:XMLElement element = ...; Enumeration enum = element.enumerateAttributeNames(); while (enum.hasMoreElements()) { String key = (String) enum.nextElement(); String value = (String) element.getAttribute(key); System.out.println(key + " = " + value); }
- Retrieving Child Elements
-
You can enumerate the children of an element using
enumerateChildren
. The number of child elements can be retrieved usingcountChildren
.
- Elements Containing Character Data
-
If an elements contains character data, like in the following example:
you can retrieve that data using the method<title>The Title</title>
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
Constructors Modifier Constructor Description XMLElement()
Creates and initializes a new XML element.protected
XMLElement(java.util.Map<java.lang.String,char[]> entities, boolean skipLeadingWhitespace, boolean fillBasicConversionTable, boolean ignoreCase)
Creates and initializes a new XML element.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description 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 tobuf
.protected boolean
checkLiteral(java.lang.String literal)
Scans the data for literal text.int
countChildren()
protected XMLElement
createAnotherElement()
Creates a new similar XML element.java.util.Enumeration<java.lang.String>
enumerateAttributeNames()
java.util.Enumeration<XMLElement>
enumerateChildren()
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)
java.lang.String
getContent()
int
getLineNr()
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.boolean
isBOM()
void
parseFromReader(java.io.Reader reader)
Reads one XML element from aReader
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.Reader isr, java.io.OutputStream 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(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.
-
-
-
Constructor Detail
-
XMLElement
public XMLElement()
Creates and initializes a new XML element.Calling the construction is equivalent to:
new XMLElement(new HashMap(), false, true)
- Postconditions:
-
- countChildren() => 0
- enumerateChildren() => empty enumeration
- enumeratePropertyNames() => empty enumeration
- getChildren() => empty vector
- getContent() => ""
- getLineNr() => 0
- getName() => null
-
XMLElement
protected XMLElement(java.util.Map<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
thenentities
contains at least the following entries:amp
,lt
,gt
,apos
andquot
- 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 identifiervalue != 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<java.lang.String> enumerateAttributeNames()
- Returns:
- Enumeration of the attribute names.
- Postconditions:
-
result != null
-
enumerateChildren
public java.util.Enumeration<XMLElement> enumerateChildren()
- Returns:
- Enumeration 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)
- Parameters:
name
- The name of the attribute.- Preconditions:
-
name != null
name
is a valid XML identifier
- Returns:
- an attribute of the element.
If the attribute doesn't exist,
null
is returned.
-
getName
public java.lang.String getName()
Returns the name of the element.- Returns:
- this
XMLElement
object's name
-
parseFromReader
public void parseFromReader(java.io.Reader reader) throws java.io.IOException, XMLParseException
Reads one XML element from aReader
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.
- Returns:
- next element in tree based on global settings
-
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 toresult
.- 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
- if something goes wrong
-
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
.- Parameters:
result
- where to append scanned text- Returns:
- the next character following the whitespace.
- Preconditions:
-
result != null
- Throws:
java.io.IOException
- if something goes wrong
-
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:
-
string != null
- the next char read is the string delimiter
- Parameters:
string
- where to append the result- Throws:
java.io.IOException
- if something goes wrong
-
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:
-
data != null
- Parameters:
data
- where to append data- Throws:
java.io.IOException
- if something goes wrong
-
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 tobuf
.- Preconditions:
-
buf != null
- The first < has already been read.
- Parameters:
buf
- buffer where to append data- Returns:
- whether the CDATA were ok
- Throws:
java.io.IOException
- if something goes wrong
-
skipComment
protected void skipComment() throws java.io.IOException
Skips a comment.- Preconditions:
-
- The first <!-- has already been read.
- Throws:
java.io.IOException
- if something goes wrong
-
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
- if something goes wrong
-
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
- Returns:
- true if literal was ok
- Throws:
java.io.IOException
- if something goes wrong
-
readChar
protected char readChar() throws java.io.IOException
Reads a character from a reader.- Returns:
- the read char
- Throws:
java.io.IOException
- if something goes wrong
-
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
- if something goes wrong
-
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
- if something goes wrong
-
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
- Returns:
- exception to be thrown
-
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
- Returns:
- exception to be used
-
unexpectedEndOfData
protected XMLParseException unexpectedEndOfData()
Creates a parse exception for when the end of the data input has been reached.- Returns:
- exception to be used
-
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
- Returns:
- exception to be used
-
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
- Returns:
- exception to be used
-
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
- Returns:
- exception to be used
-
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.- Returns:
- exception to be used
- Preconditions:
-
name != null
name.length() > 0
-
sanitizeInput
public void sanitizeInput(java.io.Reader isr, java.io.OutputStream pout)
Reads an xml file and removes the comments, leaving only relevant xml code.- Parameters:
isr
- The reader of theInputStream
containing the xml.pout
- ThePipedOutputStream
that will be receiving the filtered xml file.
-
isBOM
public boolean isBOM()
-
-