nanoxml
Class XMLElement

java.lang.Object
  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 method getStringAttribute. The following example shows how to list the attributes of an element:

XMLElement element = ...;
Iterator iter = element.getAttributeNames();
while (iter.hasNext()) {
String key = (String) iter.next();
String value = element.getStringAttribute(key);
System.out.println(key + " = " + value);
}

Retrieving Child Elements

You can enumerate the children of an element using iterateChildren. The number of child iterator can be retrieved using countChildren.

Elements Containing Character Data

If an iterator contains character data, like in the following example:

<title>The Title</title>

you can retrieve that data using the method getContent.

Subclassing XMLElement

When subclassing XMLElement, you need to override the method createElement which has to return a new copy of the receiver.

See Also:

XMLParseException

Field Summary

static int	NANOXML_MAJOR_VERSION Major version of NanoXML.
static int	NANOXML_MINOR_VERSION Minor version of NanoXML.

Constructor Summary

	XMLElement() Creates and initializes a new XML element.
	XMLElement(boolean skipLeadingWhitespace) Creates and initializes a new XML element.
	XMLElement(java.util.HashMap entities) Creates and initializes a new XML element.
	XMLElement(java.util.HashMap entities, boolean skipLeadingWhitespace) Creates and initializes a new XML element.
	XMLElement(java.util.HashMap entities, boolean skipLeadingWhitespace, boolean ignoreCase) Creates and initializes a new XML element.
protected	XMLElement(java.util.HashMap entities, boolean skipLeadingWhitespace, boolean fillBasicConversionTable, boolean ignoreCase) Creates and initializes a new XML element.
protected	XMLElement(java.util.HashMap entities, boolean skipLeadingWhitespace, boolean fillBasicConversionTable, boolean ignoreCase, boolean encodeUnicodeCharacters)

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 iterator of the element.
protected XMLElement	createElement() Creates a new similar XML element.
XMLElement	createElement(java.lang.String name) Creates a new similar XML element.
java.util.Iterator	enumerateAttributeNames() Enumerates the attribute names.
protected XMLParseException	expectedInput(java.lang.String charSet) 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.Object	getAttribute(java.lang.String name, java.util.Map valueSet, java.lang.String defaultKey, boolean allowLiterals) Returns an attribute by looking up a key in a hashtable.
java.lang.Object	getAttribute(java.lang.String name, java.lang.Object defaultValue) Returns an attribute of the element.
boolean	getBooleanAttribute(java.lang.String name, boolean defaultValue)
boolean	getBooleanAttribute(java.lang.String name, java.lang.String trueValue, java.lang.String falseValue, boolean defaultValue) Returns an attribute of the element.
java.util.ArrayList	getChildren() Returns the child iterator as a ArrayList.
java.lang.String	getContent() Returns the PCDATA content of the object.
double	getDoubleAttribute(java.lang.String name) Returns an attribute of the element.
double	getDoubleAttribute(java.lang.String name, double defaultValue) Returns an attribute of the element.
double	getDoubleAttribute(java.lang.String name, java.util.HashMap valueSet, java.lang.String defaultKey, boolean allowLiteralNumbers) Returns an attribute by looking up a key in a hashtable.
int	getIntAttribute(java.lang.String name) Returns an attribute of the element.
int	getIntAttribute(java.lang.String name, java.util.HashMap valueSet, java.lang.String defaultKey, boolean allowLiteralNumbers) Returns an attribute by looking up a key in a hashtable.
int	getIntAttribute(java.lang.String name, int defaultValue) Returns an attribute of the element.
int	getIntAttribute(java.lang.String name, int min, int max, int defaultValue)
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.
java.lang.String	getStringAttribute(java.lang.String name) Returns an attribute of the element.
java.lang.String	getStringAttribute(java.lang.String name, java.util.HashMap valueSet, java.lang.String defaultKey, boolean allowLiterals) Returns an attribute by looking up a key in a hashtable.
java.lang.String	getStringAttribute(java.lang.String name, java.lang.String defaultValue) Returns an attribute 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.
java.util.Iterator	iterateChildren() Enumerates the child iterator.
void	parseCharArray(char[] input, int offset, int end) Reads one XML element from a char array and parses it.
void	parseCharArray(char[] input, int offset, int end, int startingLineNr) Reads one XML element from a char array and parses it.
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.
void	parseString(java.lang.String string) Reads one XML element from a String and parses it.
void	parseString(java.lang.String string, int offset) Reads one XML element from a String and parses it.
void	parseString(java.lang.String string, int offset, int end) Reads one XML element from a String and parses it.
void	parseString(java.lang.String string, int offset, int end, int startingLineNr) Reads one XML element from a String and parses it.
void	print(java.io.PrintWriter writer) Writes the XML element to a print writer and indents the elements.
protected void	print(java.io.PrintWriter writer, int indent) Writes the XML element to a print writer and indents the elements.
protected char	readChar() Reads a character from a reader.
void	removeAttribute(java.lang.String name) Removes an attribute.
void	removeChild(XMLElement child) Removes a child element.
protected void	resolveEntity(java.lang.StringBuffer buf) Resolves an entity.
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	setDoubleAttribute(java.lang.String name, double value) Adds or modifies an attribute.
void	setIntAttribute(java.lang.String name, int value) Adds or modifies an attribute.
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.
java.lang.String	toString() Writes the XML element to a string.
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.
void	write(java.io.Writer writer) Writes the XML element to a writer.
protected void	writeEncoded(java.io.Writer writer, java.lang.String str) Writes a string encoded to a writer.

Methods inherited from class java.lang.Object

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

Field Detail

NANOXML_MAJOR_VERSION

public static final int NANOXML_MAJOR_VERSION

Major version of NanoXML. Classes with the same major and minor version are binary compatible. Classes with the same major version are source compatible. If the major version is different, you may need to modify the client source code.

See Also:

NANOXML_MINOR_VERSION, Constant Field Values

NANOXML_MINOR_VERSION

public static final int NANOXML_MINOR_VERSION

Minor version of NanoXML. Classes with the same major and minor version are binary compatible. Classes with the same major version are source compatible. If the major version is different, you may need to modify the client source code.

See Also:

NANOXML_MAJOR_VERSION, Constant Field Values

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
• iterateChildren() => empty enumeration
• enumeratePropertyNames() => empty enumeration
• getChildren() => empty vector
• getContent() => ""
• getLineNr() => 0
• getName() => null

See Also:

XMLElement(HashMap), XMLElement(boolean), XMLElement(HashMap, boolean)

XMLElement

public XMLElement(java.util.HashMap entities)

Creates and initializes a new XML element. Calling the construction is equivalent to:

new XMLElement(entities, false, true)

Parameters:

entities - The entity conversion table.

Preconditions:

• entities != null

Postconditions:

• countChildren() => 0
• iterateChildren() => empty enumeration
• enumeratePropertyNames() => empty enumeration
• getChildren() => empty vector
• getContent() => ""
• getLineNr() => 0
• getName() => null

See Also:

XMLElement(), XMLElement(boolean), XMLElement(HashMap, boolean)

XMLElement

public XMLElement(boolean skipLeadingWhitespace)

Creates and initializes a new XML element. Calling the construction is equivalent to:

new XMLElement(new HashMap(), skipLeadingWhitespace, true)

Parameters:

skipLeadingWhitespace - true if leading and trailing whitespace in PCDATA content has to be removed.

Postconditions:

• countChildren() => 0
• iterateChildren() => empty enumeration
• enumeratePropertyNames() => empty enumeration
• getChildren() => empty vector
• getContent() => ""
• getLineNr() => 0
• getName() => null

See Also:

XMLElement(), XMLElement(HashMap), XMLElement(HashMap, boolean)

XMLElement

public XMLElement(java.util.HashMap entities,
                  boolean skipLeadingWhitespace)

Creates and initializes a new XML element. Calling the construction is equivalent to:

new XMLElement(entities, skipLeadingWhitespace, true)

Parameters:

entities - The entity conversion table.

skipLeadingWhitespace - true if leading and trailing whitespace in PCDATA content has to be removed.

Preconditions:

• entities != null

Postconditions:

• countChildren() => 0
• iterateChildren() => empty enumeration
• enumeratePropertyNames() => empty enumeration
• getChildren() => empty vector
• getContent() => ""
• getLineNr() => 0
• getName() => null

See Also:

XMLElement(), XMLElement(boolean), XMLElement(HashMap)

XMLElement

public XMLElement(java.util.HashMap entities,
                  boolean skipLeadingWhitespace,
                  boolean ignoreCase)

Creates and initializes a new XML element.

Parameters:

entities - The entity conversion table.

skipLeadingWhitespace - true if leading and trailing whitespace in PCDATA content has to be removed.

ignoreCase - true if the case of element and attribute names have to be ignored.

Preconditions:

• entities != null

Postconditions:

• countChildren() => 0
• iterateChildren() => empty enumeration
• enumeratePropertyNames() => empty enumeration
• getChildren() => empty vector
• getContent() => ""
• getLineNr() => 0
• getName() => null

See Also:

XMLElement(), XMLElement(boolean), XMLElement(HashMap), XMLElement(HashMap, boolean)

XMLElement

protected XMLElement(java.util.HashMap entities,
                     boolean skipLeadingWhitespace,
                     boolean fillBasicConversionTable,
                     boolean ignoreCase)

Creates and initializes a new XML element.

This constructor should only be called from createElement to create child iterator.

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.

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
• iterateChildren() => empty enumeration
• enumeratePropertyNames() => empty enumeration
• getChildren() => empty vector
• getContent() => ""
• getLineNr() => 0
• getName() => null

See Also:

createElement()

XMLElement

protected XMLElement(java.util.HashMap entities,
                     boolean skipLeadingWhitespace,
                     boolean fillBasicConversionTable,
                     boolean ignoreCase,
                     boolean encodeUnicodeCharacters)

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
• iterateChildren() => old.iterateChildren() + child
• getChildren() => old.iterateChildren() + child

See Also:

countChildren(), iterateChildren(), getChildren(), removeChild(XMLElement)

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

setIntAttribute

public void setIntAttribute(java.lang.String name,
                            int 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

Postconditions:

• enumerateAttributeNames() => old.enumerateAttributeNames() + name
• getIntAttribute(name) => value

setDoubleAttribute

public void setDoubleAttribute(java.lang.String name,
                               double 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

Postconditions:

• enumerateAttributeNames() => old.enumerateAttributeNames() + name
• getDoubleAttribute(name) => value

countChildren

public int countChildren()

Returns the number of child iterator of the element.

Postconditions:

• result >= 0

See Also:

addChild(XMLElement), iterateChildren(), getChildren(), removeChild(XMLElement)

enumerateAttributeNames

public java.util.Iterator enumerateAttributeNames()

Enumerates the attribute names.

Postconditions:

• result != null

iterateChildren

public java.util.Iterator iterateChildren()

Enumerates the child iterator.

Postconditions:

• result != null

getChildren

public java.util.ArrayList getChildren()

Returns the child iterator as a ArrayList. It is safe to modify this ArrayList.

Postconditions:

• result != null

See Also:

addChild(XMLElement), countChildren(), iterateChildren(), removeChild(XMLElement)

getContent

public java.lang.String getContent()

Returns the PCDATA content of the object. If there is no such content, null is returned.

See Also:

setContent(String)

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

getAttribute

public java.lang.Object getAttribute(java.lang.String name,
                                     java.lang.Object defaultValue)

Returns an attribute of the element. If the attribute doesn't exist, defaultValue is returned.

Parameters:

name - The name of the attribute.

defaultValue - Key to use if the attribute is missing.

Preconditions:

• name != null
• name is a valid XML identifier

getAttribute

public java.lang.Object getAttribute(java.lang.String name,
                                     java.util.Map valueSet,
                                     java.lang.String defaultKey,
                                     boolean allowLiterals)

Returns an attribute by looking up a key in a hashtable. If the attribute doesn't exist, the value corresponding to defaultKey is returned.

As an example, if valueSet contains the mapping "one" => "1" and the element contains the attribute attr="one", then getAttribute("attr", mapping, defaultKey, false) returns "1".

Parameters:

name - The name of the attribute.

valueSet - HashMap mapping keySet().iterator to values.

defaultKey - Key to use if the attribute is missing.

allowLiterals - true if literals are valid.

Preconditions:

• name != null
• name is a valid XML identifier
• valueSet != null
• the keySet().iterator of valueSet are strings

See Also:

setAttribute(String, Object), removeAttribute(String), enumerateAttributeNames(), getAttribute(String), getAttribute(String, Object)

getStringAttribute

public java.lang.String getStringAttribute(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

See Also:

setAttribute(String, Object), removeAttribute(String), enumerateAttributeNames(), getStringAttribute(String, String), getStringAttribute(String, HashMap, String, boolean)

getStringAttribute

public java.lang.String getStringAttribute(java.lang.String name,
                                           java.lang.String defaultValue)

Returns an attribute of the element. If the attribute doesn't exist, defaultValue is returned.

Parameters:

name - The name of the attribute.

defaultValue - Key to use if the attribute is missing.

Preconditions:

• name != null
• name is a valid XML identifier

See Also:

setAttribute(String, Object), removeAttribute(String), enumerateAttributeNames(), getStringAttribute(String), getStringAttribute(String, HashMap, String, boolean)

getStringAttribute

public java.lang.String getStringAttribute(java.lang.String name,
                                           java.util.HashMap valueSet,
                                           java.lang.String defaultKey,
                                           boolean allowLiterals)

Returns an attribute by looking up a key in a hashtable. If the attribute doesn't exist, the value corresponding to defaultKey is returned.

As an example, if valueSet contains the mapping "one" => "1" and the element contains the attribute attr="one", then getAttribute("attr", mapping, defaultKey, false) returns "1".

Parameters:

name - The name of the attribute.

valueSet - HashMap mapping keySet().iterator to values.

defaultKey - Key to use if the attribute is missing.

allowLiterals - true if literals are valid.

Preconditions:

• name != null
• name is a valid XML identifier
• valueSet != null
• the keySet().iterator of valueSet are strings
• the values of valueSet are strings

See Also:

setAttribute(String, Object), removeAttribute(String), enumerateAttributeNames(), getStringAttribute(String), getStringAttribute(String, String)

getIntAttribute

public int getIntAttribute(java.lang.String name)

Returns an attribute of the element. If the attribute doesn't exist, 0 is returned.

Parameters:

name - The name of the attribute.

Preconditions:

• name != null
• name is a valid XML identifier

See Also:

setIntAttribute(String, int), enumerateAttributeNames(), getIntAttribute(String, int), getIntAttribute(String, HashMap, String, boolean)

getIntAttribute

public int getIntAttribute(java.lang.String name,
                           int defaultValue)

Returns an attribute of the element. If the attribute doesn't exist, defaultValue is returned.

Parameters:

name - The name of the attribute.

defaultValue - Key to use if the attribute is missing.

Preconditions:

• name != null
• name is a valid XML identifier

See Also:

setIntAttribute(String, int), enumerateAttributeNames(), getIntAttribute(String), getIntAttribute(String, HashMap, String, boolean)

getIntAttribute

public int getIntAttribute(java.lang.String name,
                           int min,
                           int max,
                           int defaultValue)

getIntAttribute

public int getIntAttribute(java.lang.String name,
                           java.util.HashMap valueSet,
                           java.lang.String defaultKey,
                           boolean allowLiteralNumbers)

Returns an attribute by looking up a key in a hashtable. If the attribute doesn't exist, the value corresponding to defaultKey is returned.

As an example, if valueSet contains the mapping "one" => 1 and the element contains the attribute attr="one", then getIntAttribute("attr", mapping, defaultKey, false) returns 1.

Parameters:

name - The name of the attribute.

valueSet - HashMap mapping keySet().iterator to values.

defaultKey - Key to use if the attribute is missing.

allowLiteralNumbers - true if literal numbers are valid.

Preconditions:

• name != null
• name is a valid XML identifier
• valueSet != null
• the keySet().iterator of valueSet are strings
• the values of valueSet are Integer objects
• defaultKey is either null, a key in valueSet or an integer.

See Also:

setIntAttribute(String, int), enumerateAttributeNames(), getIntAttribute(String), getIntAttribute(String, int)

getDoubleAttribute

public double getDoubleAttribute(java.lang.String name)

Returns an attribute of the element. If the attribute doesn't exist, 0.0 is returned.

Parameters:

name - The name of the attribute.

Preconditions:

• name != null
• name is a valid XML identifier

See Also:

setDoubleAttribute(String, double), enumerateAttributeNames(), getDoubleAttribute(String, double), getDoubleAttribute(String, HashMap, String, boolean)

getDoubleAttribute

public double getDoubleAttribute(java.lang.String name,
                                 double defaultValue)

Returns an attribute of the element. If the attribute doesn't exist, defaultValue is returned.

Parameters:

name - The name of the attribute.

defaultValue - Key to use if the attribute is missing.

Preconditions:

• name != null
• name is a valid XML identifier

See Also:

setDoubleAttribute(String, double), enumerateAttributeNames(), getDoubleAttribute(String), getDoubleAttribute(String, HashMap, String, boolean)

getDoubleAttribute

public double getDoubleAttribute(java.lang.String name,
                                 java.util.HashMap valueSet,
                                 java.lang.String defaultKey,
                                 boolean allowLiteralNumbers)

Returns an attribute by looking up a key in a hashtable. If the attribute doesn't exist, the value corresponding to defaultKey is returned.

As an example, if valueSet contains the mapping "one" => 1.0 and the element contains the attribute attr="one", then getDoubleAttribute("attr", mapping, defaultKey, false) returns 1.0.

Parameters:

name - The name of the attribute.

valueSet - HashMap mapping keySet().iterator to values.

defaultKey - Key to use if the attribute is missing.

allowLiteralNumbers - true if literal numbers are valid.

Preconditions:

• name != null
• name is a valid XML identifier
• valueSet != null
• the keySet().iterator of valueSet are strings
• the values of valueSet are Double objects
• defaultKey is either null, a key in valueSet or a double.

See Also:

setDoubleAttribute(String, double), enumerateAttributeNames(), getDoubleAttribute(String), getDoubleAttribute(String, double)

getBooleanAttribute

public boolean getBooleanAttribute(java.lang.String name,
                                   java.lang.String trueValue,
                                   java.lang.String falseValue,
                                   boolean defaultValue)

Returns an attribute of the element. If the attribute doesn't exist, defaultValue is returned. If the value of the attribute is equal to trueValue, true is returned. If the value of the attribute is equal to falseValue, false is returned. If the value doesn't match trueValue or falseValue, an exception is thrown.

Parameters:

name - The name of the attribute.

trueValue - The value associated with true.

falseValue - The value associated with true.

defaultValue - Value to use if the attribute is missing.

Preconditions:

• name != null
• name is a valid XML identifier
• trueValue and falseValue are different strings.

See Also:

setAttribute(String, Object), removeAttribute(String), enumerateAttributeNames()

getBooleanAttribute

public boolean getBooleanAttribute(java.lang.String name,
                                   boolean defaultValue)

getName

public java.lang.String getName()

Returns the name of the element.

See Also:

setName(String)

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.

parseString

public void parseString(java.lang.String string)
                 throws XMLParseException

Reads one XML element from a String and parses it.

Parameters:

string - The reader from which to retrieve the XML data.

Preconditions:

• string != null
• string.length() > 0

Postconditions:

• the state of the receiver is updated to reflect the XML element parsed from the reader

Throws:

XMLParseException - If an error occured while parsing the string.

parseString

public void parseString(java.lang.String string,
                        int offset)
                 throws XMLParseException

Reads one XML element from a String and parses it.

Parameters:

string - The reader from which to retrieve the XML data.

offset - The first character in string to scan.

Preconditions:

• string != null
• offset < string.length()
• offset >= 0

Postconditions:

• the state of the receiver is updated to reflect the XML element parsed from the reader

Throws:

XMLParseException - If an error occured while parsing the string.

parseString

public void parseString(java.lang.String string,
                        int offset,
                        int end)
                 throws XMLParseException

Reads one XML element from a String and parses it.

Parameters:

string - The reader from which to retrieve the XML data.

offset - The first character in string to scan.

end - The character where to stop scanning. This character is not scanned.

Preconditions:

• string != null
• end <= string.length()
• offset < end
• offset >= 0

Postconditions:

• the state of the receiver is updated to reflect the XML element parsed from the reader

Throws:

XMLParseException - If an error occured while parsing the string.

parseString

public void parseString(java.lang.String string,
                        int offset,
                        int end,
                        int startingLineNr)
                 throws XMLParseException

Reads one XML element from a String and parses it.

Parameters:

string - The reader from which to retrieve the XML data.

offset - The first character in string to scan.

end - The character where to stop scanning. This character is not scanned.

startingLineNr - The line number of the first line in the data.

Preconditions:

• string != null
• end <= string.length()
• offset < end
• offset >= 0

Postconditions:

• the state of the receiver is updated to reflect the XML element parsed from the reader

Throws:

XMLParseException - If an error occured while parsing the string.

parseCharArray

public void parseCharArray(char[] input,
                           int offset,
                           int end)
                    throws XMLParseException

Reads one XML element from a char array and parses it.

Parameters:

input - The reader from which to retrieve the XML data.

offset - The first character in string to scan.

end - The character where to stop scanning. This character is not scanned.

Preconditions:

• input != null
• end <= input.length
• offset < end
• offset >= 0

Postconditions:

• the state of the receiver is updated to reflect the XML element parsed from the reader

Throws:

XMLParseException - If an error occured while parsing the string.

parseCharArray

public void parseCharArray(char[] input,
                           int offset,
                           int end,
                           int startingLineNr)
                    throws XMLParseException

Reads one XML element from a char array and parses it.

Parameters:

input - The reader from which to retrieve the XML data.

offset - The first character in string to scan.

end - The character where to stop scanning. This character is not scanned.

startingLineNr - The line number of the first line in the data.

Preconditions:

• input != null
• end <= input.length
• offset < end
• offset >= 0

Postconditions:

• the state of the receiver is updated to reflect the XML element parsed from the reader

Throws:

XMLParseException - If an error occured while parsing the string.

removeChild

public void removeChild(XMLElement child)

Removes a child element.

Parameters:

child - The child element to remove.

Preconditions:

• child != null
• child is a child element of the receiver

Postconditions:

• countChildren() => old.countChildren() - 1
• iterateChildren() => old.iterateChildren() - child
• getChildren() => old.iterateChildren() - child

See Also:

addChild(XMLElement), countChildren(), iterateChildren(), getChildren()

removeAttribute

public void removeAttribute(java.lang.String name)

Removes an attribute.

Parameters:

name - The name of the attribute.

Preconditions:

• name != null
• name is a valid XML identifier

Postconditions:

• enumerateAttributeNames() => old.enumerateAttributeNames() - name
• getAttribute(name) => null

createElement

public XMLElement createElement(java.lang.String name)

Creates a new similar XML element.

createElement

protected XMLElement createElement()

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

See Also:

getName()

toString

public java.lang.String toString()

Writes the XML element to a string.

Overrides:

toString in class java.lang.Object

See Also:

write(Writer)

write

public void write(java.io.Writer writer)
           throws java.io.IOException

Writes the XML element to a writer.

Parameters:

writer - The writer to write the XML data to.

Preconditions:

• writer != null
• writer is not closed

Throws:

java.io.IOException - If the data could not be written to the writer.

See Also:

toString()

print

public void print(java.io.PrintWriter writer)

Writes the XML element to a print writer and indents the elements.

Parameters:

writer - The writer to write the XML data to.

Preconditions:

• writer != null
• writer is not closed

Throws:

java.io.IOException - If the data could not be written to the writer.

See Also:

toString()

print

protected void print(java.io.PrintWriter writer,
                     int indent)

Writes the XML element to a print writer and indents the elements.

Parameters:

writer - The writer to write the XML data to.

Preconditions:

• writer != null
• writer is not closed

indent - The indentation.

Throws:

java.io.IOException - If the data could not be written to the writer.

See Also:

toString()

writeEncoded

protected void writeEncoded(java.io.Writer writer,
                            java.lang.String str)
                     throws java.io.IOException

Writes a string encoded to a writer.

Parameters:

writer - The writer to write the XML data to.

str - The string to write encoded.

Preconditions:

• writer != null
• writer is not closed
• str != null

Throws:

java.io.IOException

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:

• string != null
• the next char read is the string delimiter

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:

• data != null

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:

• buf != null
• The first < has already been read.

Throws:

java.io.IOException

skipComment

protected void skipComment()
                    throws java.io.IOException

Skips a comment.

Preconditions:

• The first <!-- has already been read.

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

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