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.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 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()`
    `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 a `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(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 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` 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<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 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:
        `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 `'&gt;'` 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 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` - 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 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:
        `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 &gt;= 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() &gt; 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() &gt; 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() &gt; 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() &gt; 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.

    - #### isBOM

          public boolean isBOM()

Submit a bug or feature