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 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:
    `XMLParseException`

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `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

    Methods
    Modifier and Type | Method and 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 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.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()` 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:
      `new XMLElement(new Hashtable(), false, true)`
      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:
        - `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`

    - #### 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.Reader isr,
                           java.io.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.

Submit a bug or feature