Class XMLElement

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

public class XMLElement extends 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 getAttribute. 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 using countChildren.
Elements Containing Character Data
If an elements 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 createAnotherElement which has to return a new copy of the receiver.
See Also:
  • 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:
    • 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 then entities contains at least the following entries: amp, lt, gt, apos and quot
      Postconditions:
  • Method Details

    • 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:
    • setAttribute

      public void setAttribute(String name, 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:
    • countChildren

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

      public Enumeration<String> enumerateAttributeNames()
      Returns:
      Enumeration of the attribute names.
      Postconditions:
      • result != null
    • enumerateChildren

      public Enumeration<XMLElement> enumerateChildren()
      Returns:
      Enumeration the child elements.
      Postconditions:
      • result != null
    • getContent

      public 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 Object getAttribute(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 String getName()
      Returns the name of the element.
      Returns:
      this XMLElement object's name
    • parseFromReader

      public void parseFromReader(Reader reader) throws IOException, XMLParseException
      Reads one XML element from a 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 '&gt;' 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 '&gt;' 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

      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(String content)
      Changes the content string.
      Parameters:
      content - The new content string.
    • setName

      public void setName(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(StringBuffer result) throws 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:
      IOException - if something goes wrong
    • scanWhitespace

      protected char scanWhitespace(StringBuffer result) throws 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:
      IOException - if something goes wrong
    • scanString

      protected void scanString(StringBuffer string) throws 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:
      IOException - if something goes wrong
    • scanPCData

      protected void scanPCData(StringBuffer data) throws 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:
      IOException - if something goes wrong
    • checkCDATA

      protected boolean checkCDATA(StringBuffer buf) throws 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.
      Parameters:
      buf - buffer where to append data
      Returns:
      whether the CDATA were ok
      Throws:
      IOException - if something goes wrong
    • skipComment

      protected void skipComment() throws IOException
      Skips a comment.
      Preconditions:
      • The first <!-- has already been read.
      Throws:
      IOException - if something goes wrong
    • skipSpecialTag

      protected void skipSpecialTag(int bracketLevel) throws 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 &gt;= 0
      Throws:
      IOException - if something goes wrong
    • checkLiteral

      protected boolean checkLiteral(String literal) throws 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:
      IOException - if something goes wrong
    • readChar

      protected char readChar() throws IOException
      Reads a character from a reader.
      Returns:
      the read char
      Throws:
      IOException - if something goes wrong
    • scanElement

      protected void scanElement(XMLElement elt) throws IOException
      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

      protected void resolveEntity(StringBuffer buf) throws 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:
      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(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(String name, 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(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() &gt; 0
      Returns:
      exception to be used
    • expectedInput

      protected XMLParseException expectedInput(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() &gt; 0
      Returns:
      exception to be used
    • expectedInput

      protected XMLParseException expectedInput(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() &gt; 0
      Returns:
      exception to be used
    • unknownEntity

      protected XMLParseException unknownEntity(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() &gt; 0
    • sanitizeInput

      public void sanitizeInput(Reader isr, OutputStream 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.
    • isBOM

      public boolean isBOM()