Package net.sourceforge.nanoxml
Class XMLElement
java.lang.Object
net.sourceforge.nanoxml.XMLElement
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:
-
Constructor Summary
ConstructorsModifierConstructorDescriptionCreates and initializes a new XML element.protected
XMLElement
(Map<String, char[]> entities, boolean skipLeadingWhitespace, boolean fillBasicConversionTable, boolean ignoreCase) Creates and initializes a new XML element. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addChild
(XMLElement child) Adds a child element.protected boolean
checkCDATA
(StringBuffer buf) Scans a special tag and if the tag is a CDATA section, append its content tobuf
.protected boolean
checkLiteral
(String literal) Scans the data for literal text.int
protected XMLElement
Creates a new similar XML element.protected XMLParseException
expectedInput
(String charSet) Creates a parse exception for when the next character read is not the character that was expected.protected XMLParseException
expectedInput
(String charSet, char ch) Creates a parse exception for when the next character read is not the character that was expected.getAttribute
(String name) int
getName()
Returns the name of the element.protected XMLParseException
invalidValue
(String name, String value) Creates a parse exception for when an invalid value is given to a method.protected XMLParseException
invalidValueSet
(String name) Creates a parse exception for when an invalid valueset is given to a method.boolean
isBOM()
void
parseFromReader
(Reader reader) Reads one XML element from aReader
and parses it.void
parseFromReader
(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
Resolves an entity.void
sanitizeInput
(Reader isr, 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
(StringBuffer result) Scans an identifier from the current reader.protected void
scanPCData
(StringBuffer data) Scans a#PCDATA
element.protected void
scanString
(StringBuffer string) This method scans a delimited string from the current reader.protected char
scanWhitespace
(StringBuffer result) This method scans an identifier from the current reader.void
setAttribute
(String name, Object value) Adds or modifies an attribute.void
setContent
(String content) Changes the content string.void
Changes the name of the element.protected void
Skips a comment.protected void
skipSpecialTag
(int bracketLevel) Skips a special tag or comment.protected XMLParseException
syntaxError
(String context) Creates a parse exception for when a syntax error occured.protected XMLParseException
Creates a parse exception for when the end of the data input has been reached.protected XMLParseException
unknownEntity
(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 Details
-
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(Map<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 Details
-
addChild
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
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
- Returns:
- Enumeration of the attribute names.
- Postconditions:
-
result != null
-
enumerateChildren
- Returns:
- Enumeration the child elements.
- Postconditions:
-
result != null
-
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
- 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
Returns the name of the element.- Returns:
- this
XMLElement
object's name
-
parseFromReader
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:
IOException
- If an error occured while reading the input.XMLParseException
- If an error occured while parsing the read data.
-
parseFromReader
public void parseFromReader(Reader reader, int startingLineNr) throws 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:
IOException
- If an error occured while reading the input.XMLParseException
- If an error occured while parsing the read data.
-
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
Changes the content string.- Parameters:
content
- The new content string.
-
setName
Changes the name of the element.- Parameters:
name
- The new name.- Preconditions:
-
name != null
name
is a valid XML identifier
-
scanIdentifier
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:
IOException
- if something goes wrong
-
scanWhitespace
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:
IOException
- if something goes wrong
-
scanString
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:
IOException
- if something goes wrong
-
scanPCData
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:
IOException
- if something goes wrong
-
checkCDATA
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:
IOException
- if something goes wrong
-
skipComment
Skips a comment.- Preconditions:
-
- The first <!-- has already been read.
- Throws:
IOException
- if something goes wrong
-
skipSpecialTag
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:
IOException
- if something goes wrong
-
checkLiteral
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:
IOException
- if something goes wrong
-
readChar
Reads a character from a reader.- Returns:
- the read char
- Throws:
IOException
- if something goes wrong
-
scanElement
Scans an XML element.- Parameters:
elt
- The element that will contain the result.- Preconditions:
-
- The first < has already been read.
elt != null
- Throws:
IOException
- if something goes wrong
-
resolveEntity
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:
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
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
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
Creates a parse exception for when the end of the data input has been reached.- Returns:
- exception to be used
-
syntaxError
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
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
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
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
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()
-